1.0 Introduction
There is a growing need for Electronic Payments and with the recent circular from the Central Bank on Cash Policy banks are providing different infrastructures to meet the specific needs and requirements of their teeming billers and Customers. It is desirable to have a solution that will make Bill payments seamless without the added overhead of paying at specific physical locations. NIBSS e-BillsPay is an account-number-based, online real-time Credit Transfer product that enables customers to make payments by leveraging the security provided by the banks. It enables banks to provide electronic bills payment services through Payment Channels such as Branch Tellers, Internet Banking, Mobile Banking and Kiosk, etc. while leveraging on the security measures provided by these channels with a view to making payments to signed-up billers. The requirements of the signed-up billers differ. Some billers require the paying customers to be validated and also notification of successful payments sent to them hence this specification. This document is a specification of the format of validation and notification request/response and mode of communication between billers and NIBSS.
2.0 General Flow
This interface is implemented as a REST web service. The biller is expected to expose a REST web service. The web service must expose the following methods:
- VALIDATION – This method will be called by NIBSS passing an encrypted request payload that contains biller product and payment details to be validated.
- NOTIFICATION – This method will be called by NIBSS to notify the Biller of the of payment or transaction status.
The data exchanged during the calls is an encrypted payload which is to be decrypted by the biller, the result of the decryption produces a payload in a JSON format.
The image below depicts the communication between clients and NIBSS.
3.0 SPECIFICATION DETAILS
This is a REST web service and therefore supports only REST requests.
METHODS
3.1 Validation (Encrypted JSON):
This method takes an encrypted payload as an input and returns an encrypted payload as response. The request payload would contain an array field called “Params” which is an array of keys and values of biller’s custom fields which is to be validated by the biller.
URL
HTTP method – POST
Header
Content type – text/plain
Accept – application/json
Note: The sample payload below which will be encrypted with an iv key and secret will be sent as a request payload to the biller’s validation endpoint, decrypting the request payload produces a JSON object, sample format below. See section 5.0 for IV key and Secret.
SAMPLE DECRYPTED JSON REQUEST
{
"SourceBankCode": "567899",
"SourceBankName": "Zenith Bank",
"InstitutionCode": "00123",
"ChannelCode": "2345",
"BillerId": "0BB98A28-F30B-D385-F3BF-39FF3BAB24BA", 6
"BillerName": "ZAMFARA STATE INTERNAL REVENUE SERVICE",
"ProductID": "C1ACE7B4-8EC0-63F2-7C98-39FF3BA4D42F",
"ProductName": "TAX COLLECTION",
"Amount": 0.00,
"Params": {
"ReferenceNumber": "192036198284",
“Phone”:”1234566”
}
}
Payload Datatype:
Amount – decimal;
BillerId – Guid;
BillerName – Guid;
ProductID – Guid;
SAMPLE ENCRYPTED PAYLOAD
6d6d39ccc785cc80f60de5f3951ed2ef98b8c885e61c745fe0136e549628730ee037e3af20aee6
42b9240563d7f679cefa3bf39324b88d13f4256a1102baf16472f0b78acf617bce9e1f72355799
5ae53b881983fac6926f727a51e76581341a3dcaed578e573ac63875b25112279756449492928
74109d5eb1ba9d0affaaf1140eea2c725b198ddefa9f1130b83e2f501f796cc38cee450e8b554d
b947436865b7426989d6aa8cada069b900e6eb0ffc185c25bf47742ca770a2860b32009f52030
4adbdf191be8119b774eaebbca2ca9d0a00d4265e4f1523c949948e46e2ef9a6d438a2c06174
7c2ab2570050ccdd6cea9c8f880c254f2a0f4cfa73aed9e8
JSON Response
The response from validation must be an encrypted JSON, the JSON structure prior to encryption is specified below, where HasError is either true or false, ErrorMessages is an array of string that would contain error(s) if any and Amount for returning the amount for the product to be paid for where it was not configured on the EbillsPay portal.
SAMPLE DECRYPTED NOTIFICATION RESPONSE PAYLOAD |
|
{ |
|
“Message” : “string”, |
|
“Amount” : 24000, |
|
“HasError” : false, |
|
"Params": { |
|
"ReferenceNumber": "192036198284", |
|
“Phone”:”1234566” | 7 |
},
“ErrorMessages” : []
}
SAMPLE ENCRYPTED NOTIFICATION RESPONSE PAYLOAD:
e50dfd5aecad8266376b0c3cbe416ae3b3c6eb7d1f37074fe66f00191692e16fa79e5c710c8 5351285e97d6c5170a6f48c81b35449de796f6d10d6757e1ded3f2420f6c86c25b83f307663 7fe30d976a
3.2 NOTIFICATION (Encrypted JSON)
This method takes an encrypted JSON payload as an input and returns a JSON response.
URL
HTTP method – POST
Header
Content type – text/plain
Accept – application/json
Note: The sample payload below which will be encrypted with an iv key and secret will be sent as a request payload to the biller’s notification endpoint, decrypting the request payload produces a JSON object, sample format below. See section 5.0 for IV key and Secret.
SAMPLE DECRYPTED JSON REQUEST
{
"SessionId": "C1ACE7B4-8EC0-63F2-7C98-39FF3BA4D42F",
"TransactionDate": "06/10/11",
"TransactionTime": "15:24:16",
"Amount": 100,
"ChannelCode": "USSD",
"BankName": "Zenith Bank",
"BranchName": "Ikeja",
"BillerId": "0BB98A28-F30B-D385-F3BF-39FF3BAB24BA",
"BillerName": "Bet9ja",
"Params": { 8
"ReferenceNumber": "192036198284",
“Phone”:”1234566”
}
}
SAMPLE ENCRYPTED PAYLOAD
6d6d39ccc785cc80f60de5f3951ed2efdd4f6aa6e55b4db63338b4e0ed0b28d890a8f179
3c574b84ca4dd285a2f8057557ad8ae8366f674d47eab9c116f82dfe827584bc5841894e
503d040a5ec989d493eddfaae5a0c4ebed0f3f32e94b218c077d5023aa86aec7110b3cd
b3ac60dbfad4fad66bf909daa22aff04137a49ef0fd45f9bc4f42d54b8b3e08bc4c3a6441
6faa649cd82af681b6ed5a2af02bd3c1dbc2710b1f86b5e602fa93e3c98a15b187a309d0
711b2bbdb1811f06dedbedd67aa2d9a557fa958b2a11251c82b8d233ba00d64f40ae92
e16ba82b6393b502c987c74b97197c50a00e9a278b38745168dc27ccc66addc05e1d8c4
2c467bb6c92db8c2a34a69b2aece513090dca7c5f8b4f864563b11b0313db78afb8ac5c2
d74e736ffec45524923f315f6fac37f9029e85280d58159b1017465fbe13482ffca224d425
7dbb80148d6707583c935153f9e6274e91eb18d2bffd83b9866e5e6e58b2d35a791ce9c
11a486186b56df9a8511b8211c3d25b828c70cdb5f9ae413bd21242608ee4b94e93c06d
0d59c679f75bad465bfe9276cf6b288f34bd9fb1b43
JSON Response
The response should be an encrypted JSON of the below parameters where
HasError is either true or false, ErrorMessages is an array of string that would
contain error(s) if any.
{
“Message” : “string”,
“HasError” : false,
“ErrorMessages” : []
}
ChannelCode Values
Branch= 0, POS = 1, Web = 2, APP = 3, USSD = 4, ATM = 5, Others = 6, ALL = 7, BANK_TELLER = 8, INTERNET_BANKING = 9, MOBILE_PHONES = 10, THIRDPARTY_PAYMENT_PLATFORM = 11
4.0 FIELD DESCRIPTION
5.0 SECURITY GUIDELINES FOR BILLER INTEGRATED PLATFORM.
The following below are guidelines the information security team will adopt when integrating with Complex Biller integrated API’s
- The billers are to serve their API’s(endpoints) over HTPPS
- We will be using a request header called SIGNATURE:
“yyyymmddsecret”. The SHA256 will be calculated and sent as the signature
- The hash of the json request will be calculated and sent as a request header. The hashing algorithm used will be HMAC
- For authorization we will be using base64 of billername (without white spaces in between or at the end and all in lower case)
- The encryption standard to be adopted is AES/CBC/PKCS5Padding (IV, SECRET KEY), key length, 128 (AES-128-CBC)
- Billers are to provide a reset endpoint that will send the IV and SECRET to an email provided by NIBSS. These keys should be used in encrypting and decrypting subsequent requests and responses. These security tokens can be changed anytime by calling /Reset.
S/N | HEADERS | DESCRIPTION |
|
|
|
1 | SIGNATURE | SHA 256 of yyyymmddsecret |
|
|
|
2 | SIGNATURE_METH | SHA 256 |
|
|
|
3 | Authorization | Base 64 of biller name |
|
|
|
4 | HASH | HMAC of the json request |
|
|
|
In this regard the validation and notification endpoints would receive the HASH string as its payload.