Introduction

Overview

It 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 5 seconds from time request is received from the Instant Transfer service. A TSQ should be made after the 5 seconds elapsed to ensure response integrity at both initiating and beneficiary institutions.

Receiving institutions are expected to implement restful endpoints. All endpoints are protected and must be authorized. Authentication for access to the endpoints will be by message authentication code (encrypted with AES 256) and passed in a header parameter "token". Receiving institutions will be provided with encryption key and salt which are expected to be used to decrypt a combination of client id, client cypher and client reference. The decrypted token values should be extracted and validated.

The following will be shared by eTranzact:

client: This is a unique identifier, client id, for eTranzact.

cypher: This is a secret key for eTranzact.

clientReference: A unique reference number sent in request body for each request.

enc_key: Used to encrypt the token value.

salt: Used to generate a stronger encrypted token value.

The token fields include CLIENT, CYPHER, CLIENTREFERENCE.

TOKEN: AES 256(CLIENT | CYPHER | CLIENTREFERENCE)

Sample Request and response

Please note that the endpoint accepts both plain request objects with plain responses and encrypted requests with encrypted responses.

For sending Encrypted Requests, the following steps should be adhered to

1. Create your plain request object

PlainRequestBody: {
    "clientReference": "testClientReference12345678910",
    "transactionReference": "830UDI83HKHSD8U90U3830UD",
    "channel": 10,
    "initiatorInstitutionCode": "123456",
    "destinationIssuerCode": "345678",
    "accountNumber": "00987601234"
}

2. Using the AES 256 encryption, generate an encrypted request from the plain Request Body (Hint: Use the same AES 256 method used when generating the token) EncryptedRequestBody = AES 256(PlainRequestBody)

3. The final encrypted payload to be sent should look like this

{
  "data": "EncryptedRequestBody"
}

4. When you receive the request at your end, you decrypt it using the AES decryption method (Hint: Use the same AES 256 method used when decrypting the token)

AUTHORIZATION HEADERS

Description: All API calls must have the following headers for authorization access.

Key	Value	Description	Required?
Content-Type	application/json	Applies to all POST requests	Yes
client	client_ID	Client's unique identifier	Yes
token	vI5DS9to8D2+NSONvejuCDFmCFjxEeuVoZj3+PPL510=	Client generated AES 256 signature	Yes