Overview
AfroPays sends a callback to your configured endpoint whenever a transaction status changes. Your endpoint should acknowledge the request quickly and then update your internal transaction record.
Handle final statuses carefully
Once a transaction reaches a final status such as SUCCESS, EXPIRED,UNAUTHORIZED, or CANCELED, do not move it back to a non-final state.
Callback Body
The callback body contains the transaction reference, current status, and contextual details you can use for reconciliation and internal updates.
{
"Amount": 1,
"Currency": "ETB",
"Phone": "251911111111",
"Refrence": "TXN202603281611151975522",
"MerchantOrderId": "AFSBX-1774714273345-906",
"PaymentMethod": "AWASHBIRR",
"Status": "FAILED",
"ProviderReference": "AWASHREFERENCE",
"WebhookSentAt": "2026-03-28T16:11:16.3384428+00:00"
}Possible Statuses
| Status | Meaning | Finality |
|---|---|---|
| PENDING | The transaction was created and is waiting for customer action. | Not final |
| PROCESSING | The provider is still working on the transaction. | Not final |
| SUCCESS | The payment completed successfully. | Final |
| FAILED | The transaction did not complete successfully. | Not Final |
| CANCELED | The transaction was canceled by the customer or the flow ended without completion. | Final |
| EXPIRED | The transaction has reached its lifetime. | Final |
| UNAUTHORIZED | The transaction was declined by the payment provider due to incorect pin/otp | Final |
Handling Guidance
- • Match callbacks using your transaction reference or merchant order id.
- • Verify the request source and any signature or authentication mechanism you use.
- • Keep processing idempotent so duplicate callbacks do not create duplicate business actions.
- • Ignore backward status changes after a final state has been stored.