IMTO's Remittances

This is the technical specification for the Restful APIs for IMTO remittances.

Introduction

This document is to afford the IMTO’s to be able to carry out remittances in USD via the Application Programming Interface (API) that will be exposed by the Bank.

The service is a Restful service, and this is to be consumed by prospective IMTO’s in line with CBN guidelines regarding remittances in US Dollars,

Specification Details

This service supports only REST requests.

Go to API Reference.

Security Header

Below are the security headers to be used for authorize API call.

Authentication

Every request to the API must come with a Token in the authorization header. In view of this you are expected to generate a token by parsing the below JSON into body of the authentication endpoint

Refresh Token

The token generated has an expiry of 24hours. If the token has expired, you are meant to generate a new token by calling the “RefreshToken” endpoint. So, at this point you will parse the refresh token gotten when the authentication endpoint was called. This is to enable you to get a new token to be used for the next 24 hours

IMTO's NameInquiry

This method is expected to be called in order to validate the beneficiary to receive fund. The output of this is an input into the remittance endpoint.

{ 
   "RequestID": "123456890", 
   "AccountNumber": "0637567567" 
} 

But the sample request becomes:

The response to this call we return the name and account number;
e.g. “SUCCESS|0642341235|OLAYIDE ADERIBIGBE”

Note:

1. If a naira account (01XXXXXXX,02XXXXXXX) is parsed, a DOM account is automatically created and same is communicated in the above sample response given.

2. This request is expected to be encrypted using AES encryption. Detail about this will be discussed under security.

IMTO's Remittance

This endpoint does the debit of the IMTO and credit of the beneficiary. Below is the payload to be parsed:

{ 
   "TransactionReference":"1234567890", 
   "SenderID":"K12345", 
   "SenderName":"1234567890", 
   "CreditAccountNo":"1234567890", 
   "AccountCreditName":"Muritala Salami", 
   "TransactionNarration":"Test Narration", 
   "Amount":"500", 
   "SourceAccountNo":"0987654321" 
}

Sample Request:

The response to this call we return
e.g. SUCCESS/M12345

Note: This request is expected to be encrypted using AES encryption. Detail about this will be discussed under security.

Transaction Status

This method is used to query the status of remittance request transaction. Encrypted Transaction Reference is parsed into the IMTOsTransactionStatus method.

For example,

{baseUrl}/api/IMTOsTransactionStatus?TransactionReference=e7kut80+e60SsshrTDLOPA== 

An encrypted response is provided. When this is decrypted, it will return a string as
“SUCCESS|MXXX|234567”.

Validate BVN

This method is used to validate supplied BVN with NIBSS. OTP is sent to customer email and phone number if the BVN validation is successful. The sent OTP will have a validity of 15 minutes.

The BVN will be encrypted and will be formatted as below:

Unencrypyted Request: 
{
 "BVN": "22XXXXXXX",
 "DOB": "21-Apr-98"
 } 

Sample encrypted payload:

The response will be formatted as below as JSON string;

{
 "ResponseCode":"00",
 "ResponseMessage":"Successful",
 "DOMAccountNo":""
 } 

Encrypted Response: wT2NIs+6uQTEgGIXpD7VDGTFR+vgkgL78pSA9K685QQCDAmSl4QI0v5EpU+igohpT idIupokRYD2JCWAXXP79p1UygXwKgWVYjM4dmQ9RcA=

Open Domiciliary Account

This method is used to open domiciliary account for an existing Wema and non-existing customer using BVN.

Unencrypted Request:
 {
 "BVN": "22XXXXXXX",
 "OTP": "546365"
 } 

Sample Encrypted request:

The response will be formatted as below as JSON string.

{
 "ResponseCode":"00",
 "ResponseMessage":"Successful",
 "DOMAccountNo":"0625656646"
 } 

Encrypted Response: wT2NIs+6uQTEgGIXpD7VDGTFR+vgkgL78pSA9K685QQCDAmSl4QI0v5EpU+igohpT idIupokRYD2JCWAXXP79p1UygXwKgWVYjM4dmQ9RcA=

Security

The requests and responses are encrypted with AES(AES/CBC/PKCS5Padding) algorithm. The connecting IMTO is expected encrypt their request and decrypt response from our end. The below keys should be used in encrypting and decrypting subsequent requests and responses on a test environment.

EncryptionKey = ")KCSWITHC%^$$%@H"; 
EncrytionIV = "#$%#^%KCSWITC945"; 
cipherMode = "CBC";

HTTP Response Code

Find in the table below the response codes and their respective descriptions: This API conforms to Standard HTTP Response Code. As such if anything goes wrong the response will be depicted as below:

NIP Response Codes

Find in the table below the response codes and their respective descriptions:

Exceptions:

• Requested Service not found.

• Unauthorized access to this service

• Invalid Account Number

• Source account cannot be validated.

• Transaction Reference already exist.

• Expectation Failed