Callbacks Overview

For Collections/C2B, the client will provide a callback URL where Monexia 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 Monexia 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 Monexia system to the configured callbackUrl for a Payment Order request.

{
  "id": "0c16c3a6-56a7-ec11-ab96-0ee00e897f52",
  "customerId": "a393c67c-158b-ec11-ab86-0ee00e897f52",
  "isEnabled": true,
  "remarks": "ERTU67897RQQEQ",
  "conversationId": "908cb9a6-56a7-ec11-ab96-0ee00e897f52",
  "originatorConversationId": "8f8cb9a6-56a7-ec11-ab96-0ee00e897f52",
  "dueDate": "2022-03-21T00:00:00",
  "dateApproved": null,
  "dateRejected": null,
  "isProcessed": true,
  "dateProcessed": "2022-03-19T07:32:04.3",
  "recordStatus": 2,
  "createdBy": "Flavian",
  "createdDate": "2022-03-19T07:31:55.85",
  "orderLines": [
    {
      "remitter": {
        "name": "John Gram",
        "address": "USA",
        "phoneNumber": "1-900-99398333",
        "idType": "National ID",
        "idNumber": "2000000",
        "country": "USA",
        "ccy": 404,
        "financialInstitution": "Bank",
        "sourceOfFunds": "Business",
        "principalActivity": "Business"
      },
      "recipient": {
        "name": "John Doe",
        "address": "Nyati",
        "emailAddress": "jjdoe@gmail.com",
        "phoneNumber": "",
        "idType": "National ID",
        "idNumber": "2000000",
        "financialInstitution": "Mpesa",
        "primaryAccountNumber": "+254714000000",
        "mccmnc": "63902",
        "ccy": 404,
        "country": "KE",
        "purpose": "TEST"
      },
      "transaction": {
        "routeId": "b1b67c98-84a6-ec11-ab96-0ee00e897f52",
        "amount": 10,
        "reference": "ERTU67897RQQEQ",
        "systemTraceAuditNumber": "0d4b10f3-e679-4a75-b737-11d7d8600fac",
        "type": 0,
        "channelType": 0,
        "customerAccountNo": null,
        "routeTransactionTypeId": "00000000-0000-0000-0000-000000000000"
      },
      "transactionOutcome": {
        "id": "0e16c3a6-56a7-ec11-ab96-0ee00e897f52",
        "paymentAmount": 10,
        "feeAmount": 2,
        "trackingNumber": "5O18CE9I",
        "transactionStatus": 4,
        "transactionStatusDescription": "Completed",
        "workingAccountAvailableFunds": 0,
        "utilityAccountAvailableFunds": 0,
        "transactionDate": "20220319073158",
        "transactionCreditParty": null,
        "resultCode": "0",
        "resultCodeDescription": "Success",
        "thirdPartyPayload": {
          "thirdPartyResultCode": "0",
          "thirdPartyResultCodeDescription": "Transaction processed successfully.",
          "thirdPartyReceiptNumber": null
        },
        "createdDate": "2022-03-19T07:31:55.85"
      }
    }
  ]
}

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):