Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clickpesa.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks are HTTP POST callbacks that deliver notification messages for events. ClickPesa uses webhooks to inform your systems when transactional events occur. This way, your servers are always up to date with transaction information.
Webhook events are published from actions in any of the ClickPesa products, including the ClickPesa Dashboard, Hosted Integrations, Embedded Solutions and APIs.

​
Webhook Levels

ClickPesa supports webhooks at two levels:
LevelScopeWhen Used
Merchant webhooksAll transactions for the merchantDashboard payments and other activity not linked to a specific application
Application webhooksTransactions for a specific applicationCollection API, Disbursement API, BillPay API, and hosted checkout or payout links
For payments and payouts tied to an application (including USSD push and card payments via the Collection API, BillPay control numbers created via API, and Hosted Checkout links), if the application has a webhook URL configured for the event, the callback is sent to the application webhook only — the merchant webhook is not used. If the application has no webhook for the event, the merchant webhook is used instead.

​
Webhook Events

​
PAYMENT RECEIVED

When a payment is received successfully, this event is triggered. This event provides you with key information about the payment, including identifiers, amounts, and customer details.
  • Description - This event is triggered whenever a customer makes a successful payment. The webhook will send details of the transaction, including the amount, payer information, and transaction status.
  • Sample Payload Data 
{
  "event": "PAYMENT RECEIVED",
  "data": {
    "id": "ORD123456LCP7890",
    "status": "SUCCESS",
    "paymentReference": "abc123def456ghi789",
    "orderReference": "ORD123456",
    "collectedAmount": "10000",
    "collectedCurrency": "TZS",
    "message": "success",
    "channel": "CRDB DIRECT DEBIT MANDATE",
    "updatedAt": "2024-04-10T18:22:56.153Z",
    "createdAt": "2024-04-10T18:22:16.949Z",
    "customer": {
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "customerPhoneNumber": "255700000000"
    }
  }
}
For PAYMENT RECEIVED webhooks, the collectedAmount field is always zero or more. If our internal calculation ever ends up with a negative value, we send "0" instead so that you never receive a negative collected amount.

​
PAYMENT FAILED

  • Description - This event is triggered when a payment attempt fails. The webhook will include information about the failure reason, the attempted transaction, and any relevant error codes.
  • Sample Payload Data 
{
  "event": "PAYMENT FAILED",
  "data": {
    "id": "ORD123456LCP7890",
    "status": "FAILED",
    "channel": "CRDB DIRECT DEBIT MANDATE",
    "orderReference": "ORD123456",
    "message": "Insufficient balance",
    "updatedAt": "2024-04-11T04:58:31.036Z",
    "createdAt": "2024-04-11T04:58:31.036Z",
    "clientId": "ID1234XHYAJK"
  }
}

​
PAYOUT INITIATED

  • Description - This event is triggered when a payout process is initiated. The webhook will provide details such as the payout amount, recipient information, and the initial status of the payout.
  • Sample Payload Data 
{
  "event": "PAYOUT INITIATED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "SUCCESS",
    "channel": "BANK TRANSFER", // or MOBILE MONEY
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}

​
PAYOUT REFUNDED

  • Description - This event occurs when a payout is refunded, due to an issue with the payout process. The webhook will include the refund details and the original payout information.
  • Sample Payload Data 
{
  "event": "PAYOUT REFUNDED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "REFUNDED",
    "channel": "BANK TRANSFER", // or MOBILE MONEY
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "refund": {
      // reverse details
      "message": "The payout was refunded due to insufficient balance.",
      "refundedAt": "2024-09-02T09:30:00.000Z"
    },
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}

​
PAYOUT REVERSED

  • Description: This event is triggered when a payout is reversed, typically due to an error or a dispute. The webhook will contain details about the reversal, the original payout, and any related information.
  • Sample Payload Data 
{
  "event": "PAYOUT REVERSED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "REVERSED",
    "channel": "BANK TRANSFER", // or MOBILE MONEY
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "reverse": {
      // reverse details
      "message": "The payout was reversed due to invalid account information.",
      "reversedAt": "2024-09-02T09:30:00.000Z",
      "reversedWithFee": true // whether funds were returned with fee or not
    },
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}

​
DEPOSIT RECEIVED

  • Description: This event is triggered when a deposit is received. The webhook will contain details about the deposit and any related information.
  • Sample Payload Data 
{
  "event": "DEPOSIT RECEIVED",
  "data": {
    "id": "DEP17C9LPL",
    "status": "SUCCESS",
    "paymentReference": "1982813f15938863",
    "orderReference": "DEP17C9LPL",
    "depositAmount": "2000",
    "depositCurrency": "TZS",
    "channel": "CRDB COLLECTION",
    "updatedAt": "2025-07-20T13:44:22.902Z",
    "createdAt": "2025-07-20T13:44:13.893Z",
    "message": "Payment from Payclick Co Ltd",
  }
}

​
Setting Up Webhooks

​
Merchant-Level Webhooks

Merchant webhooks apply to all transactions unless an application webhook is used (see below).
  1. Access webhook settings
    • Log in to your ClickPesa Dashboard
    • Navigate to Settings → Developers
    • Locate the Webhooks section
  2. Add webhook URLs
    • Select event types: PAYOUT INITIATED, PAYOUT REVERSED, PAYOUT REFUNDED, PAYMENT RECEIVED, PAYMENT FAILED, or DEPOSIT RECEIVED
    • Set the webhook URL for each event

​
Application-Level Webhooks

Application webhooks let you receive events per application for transactions tied to that application. This includes:
  • Collection API — USSD push, card, and other payments you initiate through the API
  • Disbursement API — mobile money and bank payouts you create through the API
  • BillPay API — when a customer pays against an order or customer control number you created through the API
  • Hosted integrations — payments and payouts through hosted links for your application, such as Hosted Checkout
Use application webhooks when you have multiple applications (e.g. different apps or environments) and want separate webhook endpoints per application.
Application webhooks do not apply to offline BillPay references that were not created through the BillPay API. Payments made only from the dashboard use merchant webhooks instead.
An optional callbackUrl on Generate Checkout Link is separate from application webhooks. Application webhooks are configured in the dashboard and apply to all qualifying payments for that application, whether or not you also set callbackUrl on a link.
Supported events: PAYMENT RECEIVED, PAYMENT FAILED, PAYOUT INITIATED, PAYOUT REFUNDED, PAYOUT REVERSED
DEPOSIT RECEIVED is only available at the merchant level.
  1. Access application settings
    • Log in to your ClickPesa Dashboard
    • Navigate to Settings → Developers
    • Click on an application to open its details
  2. Configure application webhooks
    • In the Application Webhooks section, add webhook URLs for the events you need
    • Each application can have its own URLs per event

​
Receiving Webhook Calls

  • The gateway sends HTTP POST requests to the provided URL upon an event
  • Your system should respond with a 2xx HTTP status code to acknowledge receipt
  • Payloads can include a checksum and checksumMethod for verification (see Checksum documentation)
This status code only indicates receipt, not successful processing.
Extra data in the response is ignored.