C2B / Payins Callback Overview

For Express Requests / C2B, the merchant will provide a callback URL for us to configure.

This is where Koba will POST the final status.

**DISCLAIMER: Kindly note that for C2B, TWO callbacks will be sent for Safaricom Requests.

🔔 C2B Callback Configuration

One callback URL is passed by the merchant in their Express Deposit request payload.

The second callback URL is configured by our team on the merchant’s Collection Account.

The merchant may either:

Use one callback URL to receive and process both callbacks; or

Use two separate callback URLs to differentiate and process each callback independently

Callback #1 – Final Transaction Status
Callback #1 contains the final status of the Express Deposit request, including the relevant transaction details and parameters from the original request. Integrators MUST rely on this callback to finalize the transaction and complete the checkout flow.

Callback #2 – Reconciliation and Transaction Logging
Callback #2 is intended for reconciliation and transaction logging. It may arrive later or may not be received at all. It is not required to complete the transaction.

**Important: Receiving only Callback #1 is expected behavior. **Integrators MUST NOT wait for Callback #2 to complete a transaction.

Rely on resultCode to determine the transaction outcome. A value of 0 indicates Success and corresponds to the payment outcome reported through Callback #1.
Callback #2 is not required to confirm payment success or complete the checkout process.

Please find the 2 sample C2B Callbacks below.

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
      }
}

🔔 C2B Callback Configuration#

Sample Successful FIRST C2B Callback Response:#

Sample Successful SECOND /FINAL C2B callback response:#

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

🔔 C2B Callback Configuration

Sample Successful FIRST C2B Callback Response:

Sample Successful SECOND /FINAL C2B callback response:

Sample Failed callback response (For the First Callback):