Refund Webhooks
Handle partial and full refund notifications for a payment.
Refund notifications use webhook_type: "refund". Before processing them, follow the shared signature verification and delivery-handling rules.
Identify refund events
Refunds are reported as payment lifecycle events. Their event names retain the payment. prefix even though webhook_type is refund.
| Webhook type | Event | Status |
|---|---|---|
refund | payment.partially_refunded | partially_refunded |
refund | payment.fully_refunded | fully_refunded |
Route these notifications by webhook_type, then handle the event name. Do not treat a refund event as a new successful payment or fulfill the original order again.
Refund fields
| Field | Type | Meaning |
|---|---|---|
amount | string | Original payment amount in cents |
refunded_amount | string | Refunded amount reported by the event, in cents |
merchant_reference | string | Merchant reference for the payment |
chapa_reference | string | Chapa reference reported in the notification |
payment_type | string | Original payment flow |
service_fee | string | Fee reported in the notification |
customer | object | Customer details, when included |
For a full refund, the example reports refunded_amount equal to amount. Keep refund records separate from the original receipt and process each event idempotently.
To reconcile a refund through the API, use the refund reference returned by refund creation with Verify Refund. Do not assume the payment reference in a lifecycle notification is interchangeable with the refund reference.
Event payloads
Additional field: refunded_amount
{
"webhook_type": "refund",
"event": "payment.partially_refunded",
"status": "partially_refunded",
"mode": "live",
"payment_type": "API",
"currency": "ETB",
"amount": "40000",
"refunded_amount": "15000",
"service_fee": "0",
"merchant_reference": "TXN123PARTIALREFUND",
"chapa_reference": "CHREF123",
"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
- Create Refund: request a full or partial refund.
- Verify Refund: retrieve refund state by its refund reference.
- List Refunds: reconcile refund history.