Choice Bank Notification Callback (0003 Balance Change example)

POST

http://localhost:8080/api/v3/waas/callbacks/choicebaas

POST

/api/v3/waas/callbacks/choicebaas

curl -X POST http://localhost:8080/api/v3/waas/callbacks/choicebaas \
     -H "Content-Type: application/json" \
     -d '{
  "requestId": "req-abc123",
  "sender": "choice-baas",
  "notificationType": "0003",
  "locale": "en",
  "timestamp": 1758100000000,
  "salt": "a1b2c3d4e5f6...",
  "signature": "base64-signature-over-canonicalized-payload",
  "params": {
    "txId": "TX123",
    "externalTxId": "MPESA-XYZ",
    "userId": "f5c1d4e5-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
    "accountId": "46012000068891",
    "accountName": "Sare Shop",
    "txType": "01",
    "oppoBankCode": "M-PESA",
    "oppoBankName": "M-PESA",
    "paymentChannel": "MPESA",
    "oppoAccountId": "254712345678",
    "oppoAccountName": "Jane Doe",
    "mpesaBusinessPayType": 0,
    "thirdPartyTxType": "Pay Bill",
    "currency": "KES",
    "amount": "500.00",
    "feeAmount": "0.00",
    "balance": "1250.50",
    "completeTime": 1758100000000,
    "extInfo": {
      "transactionNarrative": "Payment",
      "oppoPhoneNumber": "254712345678",
      "counterpartyName": "Jane Doe"
    }
  }
}'

200Waas_choiceBankNotificationCallback0003BalanceChangeExample_example

{}

Public (waas/callbacks/choicebaas whitelisted) - inbound webhook from Choice Bank. Authenticated via a signature/salt pair EMBEDDED IN THE JSON BODY (verified against the canonicalized payload), not an HTTP header. notificationType dispatches to a different params shape: 0001 PERSONAL_ONBOARDING_RESULT, 0002 TRANSACTION_RESULT, 0003 BALANCE_CHANGE (shown here), 0005 UPGRADE_WALLET_TO_CURRENT_ACCOUNT, 0006 SME_ONBOARDING_RESULT, 0021 ACCOUNT_STATUS_CHANGE, 0022 MERCHANT_BALANCE_CHANGE (same shape as 0003, for B002 merchant accounts).

Request

This endpoint expects an object.

requestIdstringOptional

senderstringOptional

notificationTypestringOptionalformat: "utc-millisec"

localestringOptional

timestampintegerOptional

saltstringOptional

signaturestringOptional

paramsobjectOptional

Response

200 OK - acknowledged