eTranzact International PLC

5th Floor, Fortune Towers,

27/29, Adeyemo Alakija St.
Victoria Island, Lagos.

INSTANT TRANSFER SERVICE

SPECIFICATION
Version 1.0

13th December, 2022

The contents of this document or information disclosed during discussions of this document represents the proprietary, confidential information pertaining to
eTranzact International PLC services, methodologies and methods. Other products and brand names may be trademarks or registered trademarks of their
respective owners.
By reading this document, you agree that the information contained herein will not be disclosed outside the Organization and will not be duplicated, used,
or disclosed for any purpose other than to carry out work internal to eTranzact International PLC only.
Revision History

Version Description of Versions / Changes Responsible Party Date

1.0 Initial specification Enterprise Architecture

13th Dec. 2022
Unit

Approval Block

Version Comments Responsible Party Date

1.0 Approved CTO 13th Dec. 2022

1
 Table of Contents

GENERAL REQUIREMENTS/INFO ........................................................................................................... 3

INTRODUCTION .................................................................................................................................... 3
TRANSACTION FLOW ............................................................................................................................ 4
TRANSACTION FLOW DESCRIPTION...................................................................................................... 4

ENDPOINT SPECIFICATIONS................................................................................................................... 6
NAME ENQUIRY .................................................................................................................................... 6
SINGLE CREDIT ...................................................................................................................................... 7
TRANSACTION STATUS QUERY ............................................................................................................. 9

TRANSACTION RESPONSE CODES .........................................................................................................10

CHANNEL CODES ..................................................................................................................................11

2
 GENERAL REQUIREMENTS/INFO

INTRODUCTION
This document defines application endpoint specifications for client integration with the
Instant Transfer Service. It also defines the overall architecture and transaction flow, from
initiating institution up till point beneficiary is credited. It is expected that all integrating
institutions adhere strictly to these guidelines for optimal transaction processing.

Note that allowed timeout is 15 seconds from time request is received from the Instant
Transfer service. A TSQ should be made after the 15 seconds elapsed to ensure response
integrity at both initiating and beneficiary institutions.

Receiving institutions are expected to implement restful endpoints, secured preferably with
Oauth2; configured with a twenty-four-hour token refresh interval. Absolute expiration
should be used rather than inactivity timeouts for expiring tokens.

3
 TRANSACTION FLOW

TRANSACTION FLOW DESCRIPTION

# DESCRIPTION
A1 Initiating institution sends transfer credit request to eTranzact. The response time
is tracked.
A2 Single credit request is sent to beneficiary institution. Response time is also
tracked.

4
A3 Beneficiary institution responds to request after internal validations are
completed. Response must be returned within 15 seconds timeout window.
A4 Response is forwarded to initiating institution.
A5 If response is not received within 15 seconds window, initiating institution sends a
status query to get final status. Status query can only be done after 15 seconds has
elapsed.
A6 Final transaction status is returned to initiating institution. This status is binding on
both initiating and beneficiary institutions.
B1 Single credit request is sent to beneficiary institution. Response time is being
tracked.
B2 Beneficiary institution responds to request after internal validations are
completed. Response must be returned within 15 seconds timeout window.
B3 Before applying credit to customer account, an asynchronous process is triggered
to handle transaction status query to ensure integrity of transaction response at
both initiating and beneficiary institutions. This query can only be done after 15
seconds has elapsed, from time of receiving single credit request.
B4 Transaction status query is sent to instant transfer service, to retrieve final status.
B5 Final transaction status is returned to beneficiary institution. Beneficiary institution
can only credit customer’s account if transaction has “successful” status.

5
 ENDPOINT SPECIFICATIONS

NAME ENQUIRY
Description: This is specification used by initiating bank to fetch Account name attached to
beneficiary account. It is expected that beneficiary bank implements an interface that accepts the
below request and response. Beneficiary bank will communicate the full restful endpoint url to
eTranzact.
Endpoint: https://{defined_by_beneficiary_bank}
Request Type: POST

REQUEST PARAMETERS
Parameter Type Description Required?
transactionReference String Transaction reference from eTranzact instant Yes
transfer service. Maximum of 50 characters.
clientReference String Client/initiating bank’s unique reference number. No
Maximum of 50 characters.
channel integer Channel ID through which transaction originated. No
Refer to Channels description table
initiatorInstitutionCode String Initiating institution code, when applicable. No
accountNumber String Beneficiary Account Number. Maximum of 30 Yes
characters.

Sample Request:

{
"transactionReference":"08HKDSHVJHKHSD8U90U3",
"clientReference":"LL37843Y9Y3HJJDHBDKNDEDE8",
"channel":1,
"initiatorInstitutionCode":"011",
"accountNumber":"0123456789"
}

RESPONSE PARAMETERS
Parameter Type Description Mandatory

responseCode integer Transaction Response Code Yes

responsemessage string Description of the response code Yes
execTime integer Time taken to process request(for metrics No
and performance tracking)
data Object Data object holding the response Yes
information
accountName string Customer’s Full Name Yes
accountNumber string Account Number supplied in the request Yes

6
Sample Response:
{
"responseCode": 00,
"responseMessage": "Transaction Successful",
"execTime": 1.4888868,
"data": {
"accountName":"Joe James",
"accountNumber":"0123456789"
}
}

SINGLE CREDIT
Description: This is specification used to credit a beneficiary bank in a direct credit transaction. It is
expected that beneficiary bank implements an interface that accepts the below request and
response. Beneficiary bank will communicate the full restful endpoint url to eTranzact.
Endpoint: https://{defined_by_beneficiary_bank}
Request Type: POST

REQUEST PARAMETERS
Parameter Type Description Required?
transactionReference String Transaction reference from eTranzact Instant Yes
Transfer service. This should be designed to allow a
maximum of 50 characters.
clientReference String Client/initiating institution’s unique reference Yes
number. This should be designed to allow a
maximum of 50 characters.
channel integer Channel ID through which transaction originated. No
Refer to Channels description table
nameVerificationRef string Reference for prior name enquiry No
initiatorDetails object Holds details related to initiator Yes
initiatorInstitutionCode String Beneficiary Bank Code. Refer to Institution codes Yes
list.
initiatorAccountNumber String Originating Account Number Yes
initiatorAccountName String Originating Account Name No
initiatorBVN String BVN of initiator No
beneficiaryDetails object Holds details of beneficiary Yes
beneficiaryAccountName String Beneficiary Account Name, as retrieved via prior Yes
name enquiry
beneficiaryAccountNumber String Beneficiary Account Number Yes
currency string ISO4217 currency code. E.g. NGN, GBP Yes
amount Integer Transaction Amount, in kobo Yes
narration String Transaction Narration Yes

Sample Request:

{ "transactionReference":"08HKDSHVJHKHSD8U90U3",
"clientReference":"LL37843Y9Y3HJJDHBDKNDEDE8",
"channel":1,
"nameVerificationRef":"HSG364564389404",

7
 "initiatorDetails": {
"initiatorBVN":"",
"initiatorAccountNumber":"0123456789",
"initiatorAccountName":"Joe James",
"initiatorInstitutionCode":"001"
},
"beneficiaryDetails": {
"beneficiaryAccountName":"JOHN AGWU HASSAN",
"beneficiaryAccountNumber":"0123456789"
},
"currency":"NGN",
"amount":"5000",
"narration":"08JDHKWTest TransactionO837EKE909Y3"
}

RESPONSE PARAMETERS
Parameter Type Description Mandatory

responseCode integer Transaction Response Code Yes

responsemessage string Description of the response code Yes
execTime integer Time taken to process request(for metrics No
and performance tracking)
data Object Data object holding the response Yes
information
receiverReference string Reference received from beneficiary bank, Yes
a confirmation that transaction will be
completed by beneficiary, after a follow
up transaction status query.
Maximum of 50 characters.
transactionReference string Transaction Reference generated by the Yes
Instant Payment Service. This is to be used
for transaction status query

Sample Response:
{
"responseCode": 00,
"responseMessage": "Transaction Successful",
"execTime": 1.4888868,
"data": {
"receiverReference":"38y9y3030uhi0pghdohwl",
"transactionReference":"08HKDSHVJHKHSD8U90U3"
}
}

8
 TRANSACTION STATUS QUERY
Description: This endpoint will be used by initiating and beneficiary institutions to fetch transaction
status. It is expected that beneficiary bank implements an interface that accepts the below request
and response. Beneficiary bank will communicate the full restful endpoint url to eTranzact.
Endpoint: https://{defined_by_beneficiary_bank}
Request Type: POST

REQUEST PARAMETERS

Parameter Type Description Required?

transactionReference String eTranzact’s Transaction Reference sent in initial FT Yes
credit request by instant transfer Service, and
returned by the beneficiary institution.
clientReference string Client/initiating institution’s unique reference Yes
number. Maximum of 50 characters.

Sample Request:

{
"transactionReference":"08HKDSHVJHKHSD8U90U3",
"clientReference":"LL37843Y9Y3HJJDHBDKNDEDE8"
}

RESPONSE PARAMETERS

Parameter Type Description Mandatory

responseCode integer Transaction Response Code Yes

responseMessage string Description of the response code Yes
execTime integer Time taken to process request(for metrics and No
performance tracking)
data Object Data object holding the response information Yes
transactionReference string Transaction Reference generated by the Yes
Instant Transfer Service. This is to be used for
transaction status query
Clients should design to allow a maximum of
50 characters.
clientReference String Client/initiating bank’s unique reference yes
number. Clients should design to allow for a
maximum of 50 characters.
amount integer Transaction Amount, in kobo Yes
fee integer Transaction fee, in kobo, when applicable No
currency string ISO4217 currency code. E.g. NGN, GBP Yes
transactionDate string Transaction date in format: “yyyy-MM-dd Yes
HH:mm:ss”.
During status validation, this is date within
instant transfer service.
beneficiaryAccountNumber string Beneficiary Account Number Yes

9
 receiverReference string Reference received from beneficiary bank, a No
confirmation that transaction will be
completed by beneficiary, after a follow up
transaction status query.
Maximum of 50 characters.

Sample Response:

{
"responseCode": 00,
"responseMessage": "Transaction Successful",
"execTime": 1.4888868,
"data":{
"transactionReference":"08AAAg384678y3bhsdh998",
"clientReference":"4408372y82g3iqo",
"amount": 700000,
"fee": 00,
"currency":"NGN",
"transactionDate":"2020-09-23 17:44:13",
"beneficiaryAccountNumber":"NGN",
"receiverReference":"N36748930G883N"
}
}

TRANSACTION RESPONSE CODES

All implementations by beneficiary banks must maintain a standard set of response codes within the
response body (in status parameter), when transaction response is received. Response codes are
defined below.
HTTP CODE STATUS DESCRIPTION

-1 Unknown Transaction timeout

00 Successful Transaction Successfully Processed
01 Pending Transaction Status Unknown
02 Pending Awaiting Response from Destination Institution
03 Failed Invalid Sender
05 Failed Do not Honor
12 Failed Invalid Transaction
14 Failed Invalid Reference
15 Failed Invalid Session ID
16 Failed Unknown Bank Code
21 Failed No Action Taken
25 Failed Unable to Locate Record
26 Failed Duplicate Record
30 Failed Format Error
34 Failed Suspected Fraud
35 Failed Contact Sending Bank
51 Failed Insufficient Funds
57 Failed Transaction not Permitted to Sender

10
 61 Failed Transfer Limit Exceeded
63 Failed Security Violation
65 Failed Withdrawal Frequency Exceeded
68 Failed Response Received Late
69 Failed Unsuccessful Amount Block
91 Failed Beneficiary Bank Unavailable
92 Failed Routing Error
94 Failed Duplicate Transaction
96 Failed System Malfunction
97 Failed Time Out Waiting for Response from Destination Bank

CHANNEL CODES
Below are accepted channel codes.
CHANNEL ID
Bank branch/Teller 01
Internet Banking 02
Mobile Apps 03
POS Terminals/Kiosks 04
ATM 05
Vendor/Merchant Web Portal 06
Third – Party Payment Platform 07
Unstructured Supplementary Service Data (USSD) 08
Other Channels 09
Social Media 10
Agency Banking 11

11