Callback Configuration

For notification of payments, onboarding results, and other operation results, our API gateway communicates through callback to registered URL of the BaaS Channel.

Setup your webhook

It is easy to set up the webhook.

Define the URL you wants Choice BaaS APIs to callback.
Contact your account manager to provide the url with the format below:

Webhook

Callback URL

myCompany Name Callback

https://yourdomainname.com/choicebaas/callBack

Our tech team will add the callback configuration to system.
The webhook will be active in 8-10 hours after step 3.

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
}

0020 - OTP Verification Notification

For the partner to receive this notification, whitelisting of the merchant must have been pre-arranged beforehand.

{
"requestId":"", //String, unique id of the notification which is generated by baas
"sender":"", //String, sender id/ Channel ID of partner
"locale":"en KE", //String, language config
"timestamp":"", //long, notification send time. UTC Unix timestamp in millisecond.
"notificationType":"0020", //String, notification type id for otp verification
"params": {
        "businessId":"", //String, Onboarding or Transaction ID
        "otpCode":"" //OTP verification code
},
 "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
}

0028 - CNY Transfer Notification

JSON
{
    "requestId":"", //String, unique id of the notification which is generated by baas
    "sender":"", //String, sender id of baas system
    "locale":"en_KE", //String, language config
    "timestamp": "",//long, notification send time. UTC Unix timestamp in millisecond.
    "notificationType":"0025", //String, notification type id
    "params": {
        "amount": "10.0000", // total amount
        "status": 2, // status CNY交易状态
        "currency": "CNY", // currency
        "errorMsg": "failureReason", // errormsg
        "externalTxId": "externalTxId", // externalTxId
        "applicationId": "CERI1680870648924160008212", // applicationId
        "completedTime": 1769848055000, // 1769848055000
        "payerAccountId": "46013000093962",// payer account
        "payerAccountName": "MYWAGEPAY Partner &Atwood",// payer account name
        "beneficiaryBankName": "安徽枞阳农村商业银行", // beneficiary Bank Name
        "beneficiaryAccountId": "1345634565", // beneficiary account id
        "beneficiaryAccountName": "beneficiaryName" // beneficiary account name
    },
    "salt":"", //String, salt
    "signature":"" //String, signature
}

PreviousApply for outbound external payment channel (RTGS, EFT)NextGet Enumerations

Last updated 1 day ago

hashtagSetup your webhook

hashtagTemplate

hashtagResponse to Notification

hashtagNotifications

hashtag0001 - Personal Onboarding Result Notification

hashtag0002 - Transaction Result Notification

hashtag0003 - Balance Change Notification

hashtag0004 - Merchant Bulk Fund Transfer Result Notification

hashtag0005 - Wallet Account Upgrade Result Notification

hashtag0006 - SME Account Opening Result Notification

hashtag0007 - Utility Payment Result Notification

hashtag0008 - Bulk Transfer Result Notification

hashtag0012 - Multiple Account Opening Result Notification

hashtag0013 - Foreign Exchange Result Notification

hashtag0014 - Bulk Airtime Purchase Notification

hashtag0015 - File Job Notification

hashtag0016 - Interest Disbursement Notification

hashtag0019 - Account Closure Notification

hashtag0020 - OTP Verification Notification

hashtag0021 - Account Status Change Notification

hashtag0022 - Merchant Balance Change Notification

hashtag0023 - Inter-bank Fund Transfer Result Notification

hashtag0024 - Profile Check Result Notification

hashtag0025 - Fixed Deposit Result Notification

hashtag0028 - CNY Transfer Notification

Setup your webhook

Template

Response to Notification

Notifications

0001 - Personal Onboarding Result Notification

0002 - Transaction Result Notification

0003 - Balance Change Notification

0004 - Merchant Bulk Fund Transfer Result Notification

0005 - Wallet Account Upgrade Result Notification

0006 - SME Account Opening Result Notification

0007 - Utility Payment Result Notification

0008 - Bulk Transfer Result Notification

0012 - Multiple Account Opening Result Notification

0013 - Foreign Exchange Result Notification

0014 - Bulk Airtime Purchase Notification

0015 - File Job Notification

0016 - Interest Disbursement Notification

0019 - Account Closure Notification

0020 - OTP Verification Notification

0021 - Account Status Change Notification

0022 - Merchant Balance Change Notification

0023 - Inter-bank Fund Transfer Result Notification

0024 - Profile Check Result Notification

0025 - Fixed Deposit Result Notification

0028 - CNY Transfer Notification