Callback and IP Whitelisting
Convention
For notification of payments/onboarding results/other operation results, our API gateway communicates through callback to registered URL of the BaaS Channel.
Template
Fields
Description
Data Type
requestId
Request ID
String
sender
Sender ID of choice baas
String
notificationType
Indicate the type of the notification. Please refer to the notication code definition.
String
locale
General parameter of the request body. Choice API will decide the language of the response message according to this field. Place the "en_KE" by default.
String
timestamp
General parameter of the request body. The millisecond of UNIX time sending the request.
Long
salt
String to obscure the signature for every single request.
String
signature
Signature of the request. For method to sign the request message, please refer to Authentication
String
params
Actual request parameters of the notification. Please refer to the specific notification for details.
Object
Response to Notification
Please return the string 'ok' when you receive the callback. The notification callback will stop after it has been sent 5 times or after receiving the 'ok' response.
Notifications
0001 - Personal Onboarding Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond
"notificationType":"0001", //String, notification type
"params": {
"userId": "", //String, the unique string in your system to identify users
"onboardingRequestId": "", //String, The onboarding request ID
"status": , //Int, The onboarding status
// 0 - Not Submit
// 1 - Submitted
// 2 - Processing
// 3 - Passed
// 4 - Rejected
// 5 - Account Closed
// 6 - Waiting for account opening
// 7 - Account opened
// 8 - Failed to open account.
// 9 - Manual Reviewing
"accountId":"", //String, it's returned when the onboarding is successful
"accountType":"", //String, C001：current account，C002：wallet account
"completeTime": , //Long, UTC Unix timestamp in millisecond when the onboarding completed
"rejectionReasonIds": "", //String, code of the reject reason.
"rejectionReasonMsgs": "" //String, message of the reject reason.
},
"salt":"", //String, salt
"signature":"" //String, signature
}0002 - Transaction Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0002", //String, notification type
"params": {
"txId": "",
"txType": "",
"externalTxId": "", //External party(M-PESA/Pesalink) reference number
"accountId": "",
"accountName": "",
"accountType": "",
//C001-current account
//C002-wallet account
//B001-SME account
//B002-Merchant account
"oppoChannelId": "",
"oppoSubAccount": "", //M-PESA Paybill's sub-account number
"mpesaBusinessPayType": 1, //Int; 0-Paybill; 1-Till/BuyGoods>,
"oppoAccountId": "",
"oppoAccountName": "",
"oppoBankName": "",
"paymentChannel": "",
"thirdPartyTxType": "",
"currency": "",
"amount": "",
"feeAmount": "", //String, Transaction fee, 2 places decimal.
"txStatus": 8, //Int, transaction status.
"createTime": , //Long, Unix timestamp of the create time
"updateTime": , //Long, Unix timestamp of the last update time
"extInfo": {
"counterpartyName": "",
},
"errorCode": "", //String, error code
"errorMsg": "", //String, error message
},
"salt":"", //String, salt
"signature":"" //String, signature
}0003 - Balance Change Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0003", //String, notification type
"params": {
"txId":"",
"externalTxId":"",
"userId":"",
"accountId":"",
"accountName":"",
"txType":"",
"oppoBankCode":"",
"oppoAccountId":"",
"oppoAccountName":"",
"oppoSubAccount":"",
"thirdPartyTxType":"",
"mpesaBusinessPayType":0, //Int; 0-Paybill; 1-Till/BuyGoods>
"currency":"",
"amount":"",
"feeAmount":"", //Transaction fee
"balance":"", //Account balance after the transaction
"completeTime":, //Long, UNIX timestamp of the transction complete time
"extInfo": {
"transactionNarrative":"", //String
"oppoPhoneNumber":"", //String
"counterpartyName": "",
}
},
"salt":"", //String, salt
"signature":"" //String, signature
}0004 - Merchant Bulk Fund Transfer Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0004", //String, notification type
"params": {
"orderId":"", //String, order id generated by BaaS platform
"orgBatchId": "", //String, order id generated by BaaS partner
"resultArray": [
{
"payerAccountId": "",
"payerAccountName": "",
"merchantTxId": "", //Transaction ID generated by BaaS partner
"externalTxId": "", //External party (M-PESA/Pesalink) reference number
"payeeBankCode": "",
"payeeSubAccount": "",
"paymentChannel": "",
"payeeAccountId":"", //String, Payee account id
"payeeAccountName":"", //String, Payee account name
"payeeType":0, //Int; 0-Individual; 1-Business
"currency":"", //String currency
"amount":"", //String, transaction amount.
"txId":"", //String, choice transaction ID
"txStatus": , //Int, Transaction status. Please refer to the transaction status definition
"failedReason":"", //String, failure reason.
"completedTime": //Long, transactioncomplete time. In UTC Unix timestamp in millisecond.
}, {}
]
},
"salt":"", //String, salt
"signature":"" //String, signature
}0005 - Wallet Account Upgrade Result Notification
{
"requestId": "", //String, unique id of the notification generated by BaaS platform
"sender": "", //String, sender id of BaaS platform
"locale": "en_KE", //String, language config
"timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType": "0005", //String, notification type
"params": {
"userId": "", //String, the unique ID of the user in BaaS partner's system
"onboardingRequestId": "", //String, onboarding request ID
"status": 7, //Integer, status of the onboarding.
"accountId": "46123000000023",
"accountType": "", //String, Account type
//C001：current account
//C002：wallet account
"completeTime": 38276483274, //Long, request complete time. TC Unix timestamp in millisecond.
"rejectionReasonIds": [], //Array of String, the rejected reason id.
"rejectionReasonMsgs": [] //Array of String, reject reason description.
},
"salt": "", //String, salt
"signature": "" //String, signature
}0006 - SME Account Opening Result Notification
{
"requestId": "", //String, unique id of the notification generated by BaaS platform
"sender": "", //String, sender id of BaaS platform
"locale": "en_KE", //String, language config
"timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType": "0006", //String, notification type
"params": {
"userId": "", //String, the unique ID of the user in your end.
"onboardingRequestId": "", //String, onboarding request ID
"status": 7, //Integer, onboarding status
"accountId": "46123000000023", //String, account number will be returned when the onboarding is successful
"accountType": "", //B001-SME account
"completeTime": 38276483274, //Long, request complete time. TC Unix timestamp in millisecond.
"rejectionReasonIds": [], //Array of String, the rejected reason id.
"rejectionReasonMsgs": [], //Array of String, reject reason description.
"otherReasons": "", //other reject reasons
},
"salt": "", //String, salt
"signature": "" //String, signature
}0007 - Utility Payment Result Notification
{
"requestId": "", //String, unique id of the notification generated by BaaS platform
"sender": "", //String, sender id of BaaS platform
"locale": "en_KE", //String, language config
"timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType": "0007", //String, notification type
"params": {
"paymentId": "", //String, the payment ID
"payServiceCategory": "", //String, payment type
"subType": "", //String, utility payment vendor or airtime network
"orderNo": "", //String, the bill ID, for airtime, it's the phone number
"txId": "", //String, payment transaction ID
"refundTxId": "", //String, refund transaction ID when the payment is failed.
"amount": "", //String, amount
"status": "", //String, payment status
"errorCode": "",//String, error code
"errorMsg": "" //String, error reason
},
"salt": "", //String, salt
"signature": "" //String, signature
}0008 - Bulk Transfer Result Notification
{
"requestId": "", //String, unique id of the notification generated by BaaS platform
"sender": "", //String, sender id of BaaS platform
"locale": "en_KE", //String, language config
"timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType": "0008", //String, notification type
"params": {
"bulkPaymentOrderId": "", //String
"payerAccountId": "", //String, payer account Id
"txCount": "", //transfer count
"resultArray":[
{
"txId": "", //Choice Transaction ID
"txType": "", //String; B2C or B2B
"benificiaryName": "", //Beneficiary Account Name
"benificiaryAccount": "", //Beneficiary Account Id/Shortcode
"benificiarySubAccount": "", //M-PESA paybill's account number
"benificiaryBankCode": "", //Beneficiary bank code
"paymentChannel": "", //String,
"currency": "", //Currency
"amount": "", //Transaction Amount
"feeAmount": "", //Transaction Fee Amount
"externalTxId" : "", //External transaction reference number
"txStatus": 0, //Integer, Transaction Status
"errorCode": "", //Error code
"errorMsg": "", //Failure Reasion
"completedTime": "" //Transaction completed time，UTC Time Stamp
},
{}, ....
]
},
"salt": "", //String, salt
"signature": "" //String, signature
}0012 - Multiple Account Opening Result Notification
{
"requestId": "", //String, unique id of the notification generated by BaaS platform
"sender": "", //String, sender id of BaaS platform
"locale": "en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType": "0012", //String, notification type id
"params": {
"applicationId":"", //String, application Id
"accountId":"", //String, account id of the newly open account
"accountName":"", //String, account name
"currency":"", //String, currency of the newly open account.
"status": 3, //Int, status of the multiple account opening request. 3-successful; 4-failed
"errorCode":"", //String, error code
},
"salt":"", //String, salt
"signature":"" //String, signature
}0013 - Foreign Exchange Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0013", //String, notification type id
"params": {
"applicationId":"", //String, FX application id
"kesAccountId":"", //String, local currency account id
"fcAccountId":"", //String, foreign currency account id
"outTxId":"", //String, debit transaction id
"inTxId":"", //String, credit transaction id
"currency":"", //String, currency code of the trading foreign currency
"status":, //Int
"amount":"", //String, exchange amount of the foreign currency
"fxRate":"", //String, exchange rate
"operation":"", //String, operation on the foreign currency, buy or sell
"errorCode":"", //String, error code.
"errorMsg":"" //String, error message. please refer to FCY error code
},
"salt":"", //String, salt
"signature":"" //String, signature
}0014 - Bulk Airtime Purchase Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0014", //String, notification type id
"params": {
"bulkPaymentOrderId":"bulk payment id",
"payerAccountId":"payer account id",
"txCount":"number of the payment",
"resultArray":[
{
"paymentId": "", //String, payment id
"payServiceCategory": "", //String, pay service category
"subType": "", //String, airtime network
"orderNo": "", //String order id, for airtime, it's the phone number
"txId": "", //String, Choice bank transaction id
"refundTxId": "", //String, refund transaction id if payment fail
"amount": "", //String, payment amount
"status": "", //String, payment status
"errorCode": "", //String, error code
"errorMsg":"" //String, error message
},{}
]
},
"salt":"", //String, salt
"signature":"" //String, signature
}0015 - File Job Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0015", //String, notification type id
"params": {
"jobId":"jobId", //String, job id got when submit the job request.
"fileUrl":"" //String, url to downloan the account statement
},
"salt":"", //String, salt
"signature":"" //String, signature
}0016 - Interest Disbursement Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0016", //String, notification type id
"params": {
"date": "yyyy-mm-dd", //String, interest disbursing date
"annualIr": "", //String, annual interest rate, 4 places decimal
"interestDisbursementFequency": , //Integer, interest disbursement frequancy
"endUserDisbursedInterest": "", //String, total interest disbursed to end user
"endUserInterestTax": "", //String, tax of the interest of end user
"partnerDisbursedInterest": "", //String, total interest disbursed to baas partner
"partnerInterestTax": "", //String, tax of the interest of baas partner
"partnerBeneficiaryAccount": "" //String, baas partner beneficiary account
},
"salt":"", //String, salt
"signature":"" //String, signature
}0019 - Account Closure Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0019", //String, notification type id
"params": {
"requestId": "", //String, the account closing request id.
"accountId":"", //String, account number
"completeTime":"", //String, complete time.
"status":"", //String, 1-Account closed; 2-Request rejected
"rejectionReason":"" //String, reject reason
},
"salt":"", //String, salt
"signature":"" //String, signature
}0021 - Account Status Change Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0021", //String, notification type id
"params": {
"userId": "", //String
"accountId":"", //String
"type": 1, //Int; 1-freeze_status change; 2-dormant_status change
"status": 1, //Int; 1-Unfrozen or Active; 2-Frozen or Dormant
},
"salt":"", //String, salt
"signature":"" //String, signature
}0022 - Merchant Balance Change Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0022", //String, notification type id
"params": {
"txId": "",
"externalTxId": "", //External(Mpesa/Pesalink) reference number
"accountId": "",
"accountName": "",
"txType": "",
"oppoBankCode": "",
"oppoAccountId": "",
"oppoAccountName": "",
"oppoSubAccount": "", //For M-PESA paybill scenario
"thirdPartyTxType": "",
"mpesaBusinessPayType": 0, //Int; 0-Paybill; 1-Till/BuyGoods
"currency": "",
"amount": "",
"feeAmount": "",
"balance": "",
"completeTime": "",
"extInfo": {
"transactionNarrative": "",
"oppoPhoneNumber": "",
}
},
"salt":"", //String, salt
"signature":"" //String, signature
}0023 - Inter-bank Fund Transfer Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0023", //String, notification type id
"params": {
"applicationId": "",
"type": "", //Domestic Fund Transfer or Cross-border Fund Transfer
"debitAccountId": "",
"debitAccountCcy": "",
"beneficiaryBankName": "",
"beneficiaryBankCode": "",
"beneficiaryBranchCode": "",
"beneficiaryAccountName": "",
"beneficiaryAccountId": "",
"beneficiaryAccountCurr": "",
"requestAmtType": "", //Int;
//0-In debit account currency;
//1-In beneficiary account currency
"requestAmount": "",//The transfer amount in "requestAmtType" currency
"transferAmount": "", //The transfer amount in "debitAccountCcy" currency
"bankCharge": "", // bank charge amount
"debitAmount": "", //the total amount that the sender account was debited (including fee)
"chargeType": "", //SHA, BEN or OUR
"paymentChannel": "", //RTGS, EFT or SWIFT
"txId": "",
"refundTxId": "", //refund transaction ID when the payment fails
"status": "",
"createTime": "",
"errorCode": "",
"errorMsg": "",
"exchangeRate": "", //If debitAccountCcy is different from beneficiaryAccountCurr
//Choice automatically do exchange on behalf of end users
},
"salt":"", //String, salt
"signature":"" //String, signature
}0024 - Profile Check Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0024", //String, notification type id
"params": {
"profileCheckStatus": "", //Validated or Declined
"onboardingRequestId":"", //String
"resultCode": "", //Result code from Choice or Onboarding Vendor
"resultDescription": "", //Description for the result code
},
"salt":"", //String, salt
"signature":"" //String, signature
}0025 - Fixed Deposit Result Notification
{
"requestId":"", //String, unique id of the notification generated by BaaS platform
"sender":"", //String, sender id of BaaS platform
"locale":"en_KE", //String, language config
"timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0025", //String, notification type id
"params": {
"applicationId": "",
"depositAccountId":"",
"completeTime": "",
"status": "", //1-Submitted; 2-Processing; 3-Successful; 4-Failed
"errorMessage": "",
},
"salt":"", //String, salt
"signature":"" //String, signature
}Last updated