NCBA
NCBA Third Party Validation and Push Notification
Service
Technical Document
NCBA
18/11/2022
Revision Date Name Description
v1.0 18/11/202 NCBA First Edition
2
1
Table of contents
Table of contents 2
Introduction 3
About this Guide 3
Intended Audience 3
Security Considerations 3
Sample Java code for Hashing 3
THIRD PARTY VALIDATION 4
Overview 4
XML Validation 5
SAMPLE REQUEST 5
SUCCESS RESPONSE 5
JSON Validation 6
SAMPLE JSON REQUEST 6
SUCCESS RESPONSE 6
PUSH NOTIFICATION 7
Overview 7
XML PUSH NOTIFICATION 7
XML REQUEST 7
SUCCESS RESPONSE 8
FAILED RESPONSE 8
JSON PUSH NOTIFICATION 8
JSON REQUEST 8
2
Introduction
About this Guide
This guide provides technical information about integrating and configuring the NCBA Instant
Payment Notification Push Service.
Intended Audience
This document is written for developers who are implementing solutions using the NCBA Payment
Notification service.
Security Considerations
For 3rd Parties that opt to use our push service via the open web and have provided an https
endpoint the following details are required:
1. UserName to be used while pushing the notification to the 3rd Party endpoint
2. Password to be used while pushing the notification to the 3rd Party endpoint
3. Secret Key to be used while hashing the notification
Sample Java code for Hashing
public String hashPushRequest(String SecretKey) {
try {
//Concatenate all values together to form a string
String hashString =” “;
String sha256hex = Hashing.sha256().hashString(hashString,StandardCharsets.UTF_8).toString();
byte[] bytesEncodedHash = Base64.encodeBase64(sha256hex.getBytes());
return new String(bytesEncodedHash);
} catch (Exception e) {
return null;
}
}
3
THIRD PARTY VALIDATION
Overview
The PUSH notification will be sent as an XML tagged messenger Json request to the Third Party’s URL.
Below are descriptions of the fields.
Parameter Remarks Example
Username Username provided by the 3rd party apiuser
Password Password provided by the 3rd Party Password123#
Hash The hash value is created using SHA- YTAyMTEyZTNiN2U5MGQ1MGMyNj
256 hashing
dmMzllY2FiOWFhMzYxZjM4ZDgyYT
algorithm and then returned as
Base64 string RjNDkzMWQ3NjlkYzY4NWMyNjE4M
of that hash value.
WEwZg==
The 3rd Party will provide a Secret Key
which will be
appended to the hash
String hash = SecretKey + TransType +
TransID + TransTime + TransAmount +
BillRefNumber + Mobile() + Name;
BASE64(SHA-256(hash))
TransType Transaction type TILLNUMBER
TransID Transaction Reference number QKH44J2LB2
TransTime Transaction date and time 20221117152005
(YYYYMMDDhhmmss)
TransAmount Transaction amount 100.00
BusinessShortCode Business Short Code 4074583
BillRefNumber Bill reference number A1
Mobile Customer mobile number 2547123456789
Name Customer Name JOHN DOE
4
XML Validation
SAMPLE REQUEST
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ValidationRequest>
<Username>test</Username>
<Password>test</Password>
<Hash>YTAyMTEyZTNiN2U5MGQ1MGMyNjdmMzllY2FiOWFhMzYxZjM4ZDgyYTRjNDkzMWQ3NjlkYzY4NWMyNjE4MWEwZg==</Ha
sh>
<TransType>Pay Bill</TransType>
<TransID>QKH44J2LB2</TransID>
<TransTime>20221117152005</TransTime>
<TransAmount>1</TransAmount>
<BusinessShortCode>4074583</BusinessShortCode>
<BillRefNumber>1</BillRefNumber>
<Mobile>2547123456789</Mobile>
<Name>JOHN DOE </Name>
</ValidationRequest>
SUCCESS RESPONSE
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ValidationResponse>
<STATUS>1 </STATUS>
<DESCRIPTION>QRDFEG1L</DESCRIPTION>
</ValidationResponse>
FAILED RESPONSE
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ValidationResponse>
<STATUS>0 </STATUS>
<DESCRIPTION>INVALID ACCOUNT</DESCRIPTION>
</ValidationResponse>
5
JSON Validation
SAMPLE JSON REQUEST
{
"TransType": "Pay Bill",
"TransID": "QKH14I7HIR",
"TransTime": "20221117150856",
"TransAmount": "1",
"BusinessShortCode": "4074583",
"BillRefNumber": "1",
"Mobile": "254711173533",
"Name": "JOHN WAKAHIU MUNDIA ",
"created_at": "2022-11-17 15:03:20.0",
"Username": "test",
"Password": "test",
"Hash":
"NTkxMjdkZGYxZjUwNjcxYmExZTRjNTkzMDU3ZjQ2NGU1YjY4OTU0M2I1ZGVlYjIzZThmYjI0NWU4ZTg5ZDA2MQ\u003d\u003d"
}
SUCCESS RESPONSE
{
"STATUS": "1",
"DESCRIPTION": "Test API Response"
}
FAILED RESPONSE
{
"STATUS": "0",
"DESCRIPTION": "Failed API Response"
}
6
PUSH NOTIFICATION
Overview
This module posts C2B confirmation notification to a third party API as an XML tagged messenger or
Json request.
XML PUSH NOTIFICATION
XML REQUEST
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<NCBAPaymentNotificationRequest>
<User>test</User>
<Password>test</Password>
<HashVal>YjVmODRlYWNlMmFmNThmY2UzNTI3ODE1ODc3ZmJjMjgyNmFhNjY3M2E5OTFjMGRlODM0NzYwNDlhMDQ1ZGQ0Zg
==</HashVal>
<TransType>C2B_AGGREGATED</TransType>
<TransID>QKH54LUBSB</TransID>
<TransTime>20221117155456</TransTime>
<TransAmount>1.0</TransAmount>
<AccountNr>5344380012</AccountNr>
<Narrative>1</Narrative>
<PhoneNr>254711173533</PhoneNr>
<CustomerName>JOHN WAKAHIU MUNDIA </CustomerName>
<Status>1</Status>
</NCBAPaymentNotificationRequest>
</soapenv:Body>
</soapenv:Envelope>
7
SUCCESS RESPONSE
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<NCBAPaymentNotificationResult>
<Result>OK</Result>
</NCBAPaymentNotificationResult>
</soapenv:Body>
</soapenv:Envelope>
FAILED RESPONSE
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<NCBAPaymentNotificationResult>
<Result>FAIL</Result>
</NCBAPaymentNotificationResult>
</soapenv:Body>
</soapenv:Envelope>
JSON PUSH NOTIFICATION
JSON REQUEST
{
"TransType": "C2B_AGGREGATED",
"TransID": "QKH74MR5AT",
"TransTime": "20221117160612",
"TransAmount": "1.0",
"BusinessShortCode": "4074583",
"BillRefNumber": "1",
"Mobile": "254711173533",
"name": "JOHN WAKAHIU MUNDIA ",
"created_at": "2022-11-17 16:00:36.0",
"Username": "test",
"Password": "test",
"Hash":
"MWRjZDYyOGM2NzBhMjllZDU1NDk4NWVhM2RiMjc5Y2RjZjgwMDkyMDY4NWE0MzA0MzU5YTkwMDNjMTFiYjA0NQ\u003d\u003
d"
}
8
SUCCESS RESPONSE
{
"ResultCode": "0",
"ResultDesc": "Test API Response"
}
FAILED RESPONSE
{
"ResultCode": "1",
"ResultDesc": "Failed Test API Response"
}
