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:00

Verify 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 2xx response promptly after accepting the webhook.
  • Process repeated events idempotently using data.reference and data.status.
  • Do not initiate another purchase after receiving a pending response.
  • If a webhook is delayed, retrieve the latest state from Status and reconciliation.