Merchant - Payout API

Introduction

1. This API is to afford the merchant the ability to carry out fund transfer services.

2. The service is a Restful service, and this is to be consumed by prospective merchant in line with CBN guidelines regarding remittances.

Specification Details

This service supports only REST requests.

Go to API Reference.

Security Header

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.

Sample Request

 {
   "username": "centrikgateway",
   "password": "test12345"
 } 

{baseUrl}/api/Authentication/authenticate

{
   "id": 9,
   "firstName": null, 
   "lastName": null,
   "username": "smallworld",
   "password": null,
   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IjkiLCJuYmYiOjE2MDc3MDk1MTQsImV4cCI6MTYwNzc5NTkxNCwiaWF0IjoxNjA3NzA5NTE0fQ.DaRnbL4nrFayyVxIjrdNn02qoEvm_TzZW9PQcRM0bUg",
   "refreshToken": "2EeYyuJa3FkRGiS6JGnQsBgnKdd9INg6JpSsQK/+VbPGA9i/GdTrGdvAX4LhDAPzuL7M9cDtDVil3pFrkpyEGudeDoCBUiQPLldyoZyPyHtu2GI6EXaZZ9h72MX0d4zsjM6G6HnWRuusUzXd8CHPyQct5wB3PWYsA58OLbg rY7wXK8IPBmuZ4pOQtcMXvd/+Q/TK7AdsICAACUdXX3tvGuc3hso4VbsErF8MV8Yti0ryW6e8SJLQjrVD88dl2bSkA7aV9 L/yJf2ueIGyxJjjGmvJDrfqVRP4k7qJZKBXG3npwHF1PiZk4xrgiy4E2ZNITuqozHrkB42cW01lGzHVzQ==",
   "refreshTokenExpires": "12/18/2020 5:58:34 PM"
}

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 24hours.

Sample Request

{baseUrl}/api/Authentication/RefreshToken

{
 "refreshToken": "LJY34Fnyd/H5ssh7hY20QE3RjIDoVlbzAfy0BGhOGUo7ruVvF8FMX3scHeHCcSMiuYCH13fjx3TOlyaHdcDCBrfsGWBly1YXXGDbWssVF9laYHdWWzpPTb5fZ/8qC3kmce8ca 3zHcrmzAVyqMdmtusjg7Vz8q5L8mJIDIjVH7XKF4hdCf+EsrEyGGXbaees9KzelHO/jeF2pQ2RH53 EqSdRMvSoqMUVTi3NSarSgzpatCu0bUzDCuzQWcGkhcWW9P945iGhIz7oOQUYy91rhFvfK3S0RnmO 0xV7m2nV8dL3mUWTZLqjUW2ztyFIzOSrfOwW3Zj3PX7Ss4WW9w6DTxg==" 
}

Get List of NIP Banks

This is a GET request used to retrieve a list of all banks and their associated bank codes.

{baseUrl}/api/WMServices/GetNIPBanks

NIP Name Enquiry

This method is used to carry out name enquiry against banks.

{ 
  "myDestinationBankCode": "000013", 
  "myDestinationAccountNumber": "0011678314"
} 

Sample Request:

{baseUrl}/api/WMServices/NIPNameEnquiry

{
 "NameEnquiryRequest": "yVrDSbH12HOPcVJW0Sc6AwBtnejpy46h+xLTN2KK0vg01wfl3b6PJI/2iauU1rl0mRxdEPtOtVDWoTEk9LxPamXR/ OE8EtVJCQ7m1jhNx58NsbBFUILaQle3veTJLtbb" 
}

Sample Response:

The response to this call will return name on the account. e:g
00|Salami Muritala Olayiwola

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

NIP Fund Transfer

This is used to send fund transfer request in order for the debit and credit to be applied on respective accounts.

{
 "myDestinationBankCode": "000013",
 "myDestinationAccountNumber": "0011678314",
 "myAccountName": "SALAMI MURITALA OLAYIWOLA",
 "myOriginatorName": " my self",
 "myNarration": "This is test transaction",
 "myPaymentReference": "123075949",
 "myAmount": 10000,
 "sourceAccountNo": "1300005957"
 }

N:B- Please note that Payment Reference is unique per transaction.

Sample Request

/api/WMServices/NIPFundTransfer

{
 "FundTransferRequest": "L/k80Lb3FyfEgdujMIfbTsz2gX992N26Y3u4ef4eTX7C8QY1HMvYQzEWFt65c8kAv419GIecnVK9pP8eMDpSjSQEO fYT7tDOyzpv3LoKHjdjDjPGCBJJYhKu/WRb68Drie/Uf9HBnq7BO4nlCH6kC9/p35pBkFQrvhw0XgfIDn3KAF28Je/ 1jkSIz9701gPrk93YYFbc+dT7W7VzRQubBO4Lrb43XEfT3EFyMX9HU5H6cY1k3aWovYBJR1tTaOhy+0qKpGVjUJy7q 1MkbJOTr4MCzVGV+RW4cwjpvOLg4cBdGegRgDXasR68lawPcObgn1izZ7RcfQUcuoQL2kj1SsOgubHnsM1aM0D8ELD EsDIm97JBuesyh3vDcKUVbd7SiPXXYCRsX0TVPee3QY3ZoqYP0QgK+B5LH7O9HmrKnroIU2jaaQ4uUbqZwSZay1uv"
}

Sample Response:

The response to this call will return e.g.
00|12345678904563456346

Get Transaction Status

This method is used to query the status of fund transfer request.

Encrypted Transaction Reference is parsed into the GetTransaction Status Method e.g

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

Get Balance

This method is used to get balance on the collection account(s) profiled for a merchant.

Encrypted Account number is parsed into the GetBalance Method.

Sample Account: 1300005957

Sample Request:

{baseUrl}/api/GetTransactionStatus?AccountNumber=AAhrwIPHc4OaYbtoB1S5fQ==

The response will return in string the balance on the account. The response will also come encrypted.

Sample Response:
eJ/b5zcHpwm5u4/kvTBkPw==

When decrypted response should show account balance in figures.

Get Statement

This method is used to get statement on the account(s) profiled for a merchant.

Sample request in clear text is as

{
   "AccountNumber": "1300005957",
   "StartDate": "01/01/2021",
   "EndDate": "01/30/2021” 
} 

The request will be sent to the service as encrypted with example below.

Sample request

{
 "accountStatementRequest": "N5zH64wykUOhQE6+GTBLrec3MVZS2Q2Y/oiva9YdWvcuwvvyVse2eLZDA0gWxY3Id U496kcEMVYalN1xYJU4Go/EONvwFNn5p7Yk7C6oydTK3s/UZcLBbuQ43cI1TckS8YC2 hVyveO3h92LKoUV6IA==" 
} 

Sample response:

The response will be an encrypted a JSON string.

Security

The requests and responses are encrypted with AES(AES/CBC/PKCS5Padding) algorithm. The connecting merchant is expected to 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"; 

Sample Credentials:

VendorID: Centrik 
username: centrikgateway 
Password test12345

HTTP Response Codes

Kindly refer to the HTTP Response and NIP Response Codes on the IMTO documentation.