Payment Webhooks
Handle payment lifecycle events and recognize successful payment notifications.
Payment events use webhook_type: "payment". Before processing them, follow the shared signature verification and delivery-handling rules.
Recognize a successful payment
After authenticating the webhook, check its top-level fields together:
const isSuccessfulPayment =
webhook.webhook_type === "payment" &&
webhook.event === "payment.success" &&
webhook.status === "success";The success example below also includes mode: "live" and payment_type: "Event". mode identifies the environment; payment_type identifies the payment flow and is not a completion check.
Webhook success is lowercase webhook.status === "success". The payment verification API reports completion as data.status === "SUCCESS". Use the webhook to trigger server-side verification, then match the expected amount, currency, and merchant reference before fulfilling the order.
Events
| Event | Status | Meaning |
|---|---|---|
payment.success | success | Payment completed |
payment.failed | failed | Payment failed; inspect reason |
payment.cancelled | cancelled | Payment cancelled; inspect cancelled_by |
payment.incomplete | incomplete | Payment timed out or was abandoned |
payment.auth_needed | auth_needed | Customer authorization is required |
payment.blocked | blocked | Payment blocked; inspect reason |
Refund notifications have webhook_type: "refund" and are documented under Refund Webhooks.
Payment fields
| Field | Type | Meaning |
|---|---|---|
payment_type | string | Payment flow, such as API, Event, Donation, or Direct charge |
payment_method | string | Payment method, when included |
service_fee | string | Processing fee in cents |
customer | object | Customer details, when included |
reason | string | Failure, incomplete, or block reason |
cancelled_by | string | USER or SYSTEM, for cancellation events |
auth_type | string | Required authorization method |
expires_at | string | Authorization expiry timestamp, when included |
The customer object can include first_name, last_name, email, and phone_number.
Event payloads
{
"webhook_type": "payment",
"event": "payment.success",
"status": "success",
"mode": "live",
"payment_type": "Event",
"currency": "ETB",
"amount": "40000",
"service_fee": "1200",
"merchant_reference": "TXN123SUCCESS",
"chapa_reference": "CHREF123",
"payment_method": "telebirr",
"customer": {
"first_name": "Abebe",
"last_name": "Bikila",
"email": "abebebikila@chapa.co",
"phone_number": "+251960724272"
},
"meta": {
"order_id": "ORD-99821"
},
"created_at": "2025-11-07T13:00:00Z",
"updated_at": "2025-11-07T13:00:00Z"
}Next steps
- Verify Payments: confirm payment state before fulfillment.
- Payment Receipts: generate receipts from verified payment data.
- Refund Webhooks: handle partial and full refunds.