Callbacks Overview

For Collections/C2B, the client will provide a callback URL where ZamuPay can POST the final status.

DISCLAIMER: Kindly note that for C2B, TWO callbacks will be sent for Safaricom Requests. ONLY rely on the second callback **for the final status of the transaction. DO NOT rely on the first one.

Please find the 2 sample C2B Callbacks below.

Note: The callback payload is similar to the Transaction Status Check response. For every transaction that reaches a final status, a Callback will be sent to the configured endpoint.

For Disbursements/B2C, please follow this guide to setup the Webhook:

🔔 Payouts/Disbursements Callback Configuration

Navigate to Settings then Company Settings

Switch to the Webhook Settings tab.

Check the Enable Transaction Webhooks? checkbox.

Provide your callbackUrl in the Url input box. This is where ZamuPay will send the response.

Optional: Check Is Secure? to set authentication (Username and Password) for the URL.

Set the format of the callback payload by selecting either JSON or XML.

Flow Diagram

🔔 Sample Payment Order / Disbursement (B2C) Callback (JSON)

This payload is sent by the ZamuPay system to the configured callbackUrl for a Payment Order request.

{
    "id": "fb4fac4a-7fc7-8e5d-982f-019f65ebc21a",
    "conversationId": "01000000-0031-0a00-b7c4-08dee27340ef",
    "originatorConversationId": "a759078e-a271-4987-83ca-e8d6291e82da",
    "remarks": "AfriPay Mpesa B2C Test",
    "isProcessed": true,
    "orderLines": [
        {
            "remitter": {
                "name": "John Doe",
                "address": "GREAT BRITAIN",
                "emailAddress": "",
                "phoneNumber": "+44784367263",
                "idType": "NATIONAL ID",
                "idIssuePlace": null,
                "idNumber": "142424152",
                "idIssueDate": null,
                "idExpiryDate": null,
                "nationality": "GB",
                "country": "GB",
                "ccy": "826",
                "amount": 0.0,
                "financialInstitution": "TTS",
                "institutionIdentifier": null,
                "primaryAccountNumber": null,
                "sourceOfFunds": "Business",
                "principalActivity": "Family",
                "dateOfBirth": null,
                "state": null,
                "city": null,
                "postalCode": null,
                "occupation": null,
                "profession": null,
                "relationship": null,
                "fxRate": 0.0
            },
            "recipient": {
                "name": "Jane Doe",
                "address": "Kenya",
                "emailAddress": "",
                "phoneNumber": "+254717265442",
                "mccmnc": "63902",
                "idType": null,
                "idNumber": "123352325",
                "financialInstitution": null,
                "institutionIdentifier": "00000",
                "primaryAccountNumber": "+254717265442",
                "ccy": 404,
                "amount": 0.0,
                "purpose": "Family",
                "country": "KE",
                "creditCustomerAccountId": null,
                "state": null,
                "city": null,
                "postalCode": null,
                "nationality": null,
                "dateOfBirth": null,
                "occupation": null,
                "profession": null,
                "relationship": null
            },
            "transaction": {
                "routeId": "b1d92ea1-5751-8fa4-8217-019ed12ba5bf",
                "amount": 350.00,
                "reference": "AfriPay Mpesa Test",
                "systemTraceAuditNumber": "1a06c4d0-4c98-40d4-bf48-4a3a51184213",
                "type": 0,
                "channelType": 1,
                "customerAccountNo": null,
                "routeTransactionTypeId": "a0d6b5a4-3b6b-821d-8035-019ed12ba61e"
            },
            "transactionOutcome": {
                "id": "6fa47b48-7b92-8234-937b-019f65ebc21b",
                "paymentAmount": 350.00,
                "feeAmount": 20.00,
                "trackingNumber": "AGFI8FYP9",
                "transactionStatus": 4,
                "transactionStatusDescription": "Completed",
                "workingAccountAvailableFunds": 100000.00,
                "utilityAccountAvailableFunds": 50000.00,
                "walletBalance": 0.00,
                "transactionDate": "15.07.2026 16:16:19",
                "transactionCreditParty": "254717265442",
                "resultCode": "0",
                "resultCodeDescription": "The service request is processed successfully.",
                "thirdPartyPayload": {
                    "thirdPartyResponseCode": "0",
                    "thirdPartyResponseCodeDescription": "Accept the service request successfully.",
                    "thirdPartyResultCode": "0",
                    "thirdPartyResultCodeDescription": "The service request is processed successfully.",
                    "thirdPartyReceiptNumber": "9A7792AB53"
                }
            }
        }
    ]
}

Sample Successful FIRST C2B Callback Response:

{
    "Body": {
        "StkCallback": {
            "MerchantRequestID": "59675-2838158-2",
            "CheckoutRequestID": "ws_CO_110520211915044651",
            "OriginatorConversationId": "2134568790",
            "SystemConversationId": "456575345435",
            "ResultCode": 0,
            "ResultDesc": "The service request is processed successfully.",
            "CallbackMetadata": {
                "Item": [
                    {
                        "Name": "Amount",
                        "Value": 1
                    },
                    {
                        "Name": "MpesaReceiptNumber",
                        "Value": "PEB0U5YIQ2"
                    },
                    {
                        "Name": "Balance"
                    },
                    {
                        "Name": "TransactionDate",
                        "Value": 20210511191517
                    },
                    {
                        "Name": "PhoneNumber",
                        "Value": 254799182092
                    }
                ]
            }
        }
    }
}

Sample successful SECOND /FINAL C2B callback response:

{
    "Id": "51539fcd-0b8e-eb11-826b-062ab3a3eac8",
    "CollectionType": "Mpesa",
    "PrimaryAccountNumber": "9abd2ba6fa3bf4847ba638040947a0945c3a4279effc96d8a6fe0db10ec76ccd",
    "InstitutionIdentifier": "301174",
    "InvoiceNumber": null,
    "Thirdpartyreceiptnumber": "PCQ1490463",
    "PaymentAmount": "1.00",
    "ThirdPartyTransID": null,
    "Payeeaccountnumber": "1",
    "Createddate": "2021-08-06T06:43:31.97",
    "Thirdpartypayload": null,
    "Payeename": "JOHN DOE"
}

Sample failed callback response (For the First Callback):

{
    "Body": {
      "StkCallback": {
        "MerchantRequestID": "14237-1707571-2",
        "CheckoutRequestID": "ws_CO_210520211255325781",
        "ResultCode": "1032",
        "ResultDesc": "Request cancelled by user",
        "OriginatorConversationId": "F1002939292022",
        "SystemConversationId": "7f520000-0e89-0ee0-ea10-08d91c3e9181",
        "CallbackMetadata": null
      }
}

🔔 Payouts/Disbursements Callback Configuration#

🔔 Sample Payment Order / Disbursement (B2C) Callback (JSON)#

Sample Successful FIRST C2B Callback Response:#

Sample successful SECOND /FINAL C2B callback response:#

Sample failed callback response (For the First Callback):#

🔔 Payouts/Disbursements Callback Configuration

🔔 Sample Payment Order / Disbursement (B2C) Callback (JSON)

Sample Successful FIRST C2B Callback Response:

Sample successful SECOND /FINAL C2B callback response:

Sample failed callback response (For the First Callback):