Scenarios (payins/payouts)

Transfers In

Upon successful receipt of funds into a Choice bank account active, you (the BaaS consumer) can receive instant payment notifications (IPNs) from Choice Bank's BaaS system to notify that money has been credited to a particular account under your BaaS channel.

These are the transaction types that apply for pay-ins:

TxTypes (pay-ins)
TTID0003 - Transfer In
TTID0007 - Refund
TTID0008 - FCY Deposit
TTID0011 - Reversal
TTID0023 - Cash Deposit

To track pay-ins, notification types 0003 will apply (or the merchant account equivalent: 0022). See in the following sub-section a template of what's returned in this callback notification:

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":"",// here
        "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
}

STK Push Deposits

For pay-ins done via our STK Push API, the transaction type TTID0003 still applies but works a bit differently. The transaction is initiated from Choice Bank's end to M-pesa, who then sends the STK prompt to the end-user.

Upon the end of the STK Push session (30 seconds), Choice Bank then (if the BaaS account was successfully credited) sends back a balance change notification (i.e., notificationType 0003) as well as a transaction result notification (i.e., notificationType 0002)

Please note that transaction result notification will be the one to alert on the final status of the transaction.

0002 - delivers transaction result of the STK Push transaction 0003 - received only upon successful credit of the BaaS account

Transfers Out

For payouts from a BaaS account, the same two notification types apply. These are some of the transaction types that apply for pay-outs:

TxTypes (pay-outs)
TTID0001 - Withdraw to M-PESA	TTID0024 - Cash Withdrawal
TTID0002 - Transfer Out	TTID0025 - Mpesa IMT
TTID0005 - M-PESA Paybill / Till	TTID0027 - CNY Transfer
TTID0006 - Utility Payment	TTID0009 - FCY Transfer Out

For payouts, callback type 0002, i.e., transaction result notification (or its merchant bulk transaction result notification 0004, as well as IMT Transfer notification 0027), will best track payouts done via API. See in the following sub-section a template of what's returned in this callback notification:

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
}

Delivery Schematic

0002 - delivers the payout transaction's result 0003 - received only upon successful debit of the BaaS account