Webhooks
Payout Webhooks
Handle payout completion, failure, reversal, and authorization notifications.
Payout events use webhook_type: "payout". Before processing them, follow the shared signature verification and delivery-handling rules.
Recognize a successful payout
After authenticating the webhook, check its top-level webhook_type, event, and status together. A successful payout notification has webhook_type: "payout", event: "payout.success", and status: "success".
Payouts are asynchronous. Creation can return PENDING; use notifications and payout verification to reconcile the resulting state. Keep webhook processing idempotent so duplicate deliveries cannot trigger another disbursement.
Events
| Event | Status | Meaning |
|---|---|---|
payout.success | success | Funds delivered |
payout.failed | failed | Payout failed; inspect reason |
payout.reversed | reversed | Funds reversed; inspect reason |
payout.blocked | blocked | Payout blocked; inspect reason |
payout.auth_needed | auth_needed | Additional authorization required |
payout.otp_needed | otp_needed | OTP verification required; inspect otp_channel |
payout.otp_failed | otp_failed | OTP verification failed; inspect otp_attempts |
Payout fields
| Field | Type | Meaning |
|---|---|---|
payout_type | string | customer_payout, merchant_payout, or bulk_payout |
service_fee | string | Processing fee in cents |
processor_reference | string | Bank or payment-provider reference, when included |
account | object | Destination account details |
reason | string | Failure, block, or reversal reason |
auth_type | string | Required authorization method |
otp_channel | array | Available OTP delivery channels |
otp_attempts | number | OTP attempt count |
The account object includes account_name, account_number, bank_slug, and bank_name in the examples below.
Event payloads
{
"webhook_type": "payout",
"event": "payout.success",
"status": "success",
"payout_type": "customer_payout",
"currency": "ETB",
"amount": "200000",
"service_fee": "6000",
"merchant_reference": "PAYOUT123SUCCESS",
"chapa_reference": "CHP123SUCCESS",
"processor_reference": "BANKREF123",
"account": {
"account_name": "Abebe Bikila",
"account_number": "123567890987",
"bank_slug": "cbe",
"bank_name": "Commercial Bank of Ethiopia"
},
"meta": {
"order_id": "ORD-99821"
},
"created_at": "2025-11-07T13:00:00Z",
"updated_at": "2025-11-07T13:00:00Z"
}Next steps
- Verify Payout: reconcile payout state.
- Create Payout: initiate a disbursement.
- Bulk Payout: send multiple payouts.