Bill-Payment Webhooks
When a bill-payment purchase initially returns pending, SaySwitch sends the final result to the webhook URL configured for your test or live account.
Successful delivery
{
"notify": "bill_payment",
"notifyType": "successful",
"data": {
"reference": "merchant-order-10001",
"orderNo": "SSW-BILL-10001",
"status": "delivered",
"serviceType": "airtime",
"provider": "MTN",
"recipient": "08012345678",
"amount": 1000,
"discount": 0,
"fee": 0,
"totalDebited": 1000,
"currency": "NGN",
"purchasedCode": null,
"units": null,
"message": "Transaction successful",
"domain": "live",
"finalizedAt": "2026-11-13T20:00:00+01:00"
}
}For a failed purchase, notifyType and data.status are failed. Any applicable wallet reversal is completed before the failed webhook is sent.
Signature headers
SaySwitch includes the standard webhook headers:
payloadSignature: HMAC_SHA512_OF_RAW_BODY
merchantSignature: MERCHANT_SIGNATURE
timestamp: 2026-11-13T20:00:00+01:00Verify signatures against the unmodified raw request body before processing the JSON. See the main Webhooks guide for signature verification and general delivery guidance.
Delivery handling
- Return an HTTP
2xxresponse promptly after accepting the webhook. - Process repeated events idempotently using
data.referenceanddata.status. - Do not initiate another purchase after receiving a
pendingresponse. - If a webhook is delayed, retrieve the latest state from Status and reconciliation.