Skip to content
HitchPay API Docs

Webhooks

Bill Payment Status Update

Bills payment transactions that start as pending are finalized asynchronously. Subscribe to these events in your webhook configuration to get notified of the final state, instead of polling.

Use webhooks to

  • Get notified the moment a pending transaction succeeds or fails
  • Avoid aggressive polling of Get Transaction Status
  • Confirm when a wallet auto-refund has happened after a failure

Events

Event Fired when
bill.success A pending (or synchronous) transaction completes successfully
bill.failed A pending (or synchronous) transaction fails — the wallet is auto-refunded

Payload

The data object mirrors the purchase response shape.

bill.success

{
  "event": "bill.success",
  "data": {
    "reference": "HTCHB…",
    "merchant_reference": "order-data-001",
    "product": "databundle",
    "provider": "MTN_NIGERIA",
    "amount": 500,
    "fee": 0,
    "amount_charged": 500,
    "recipient": "08012345678",
    "currency": "NGN",
    "status": "successful",
    "paid_at": "2026-07-02T10:20:00.000Z"
  }
}

bill.failed

{
  "event": "bill.failed",
  "data": {
    "reference": "HTCHB…",
    "merchant_reference": "order-data-001",
    "product": "databundle",
    "provider": "MTN_NIGERIA",
    "amount": 500,
    "recipient": "08012345678",
    "currency": "NGN",
    "status": "failed",
    "reason": "Provider declined the transaction",
    "refunded": true
  }
}

Fields

Field Type Description
reference string Our transaction id
merchant_reference string Your original reference
product string airtime, databundle, cable, or electricity
amount number Amount charged
status string successful or failed
token / units string Electricity only
reason string Present on bill.failed — why the provider declined
refunded boolean Present on bill.failed — whether the wallet was auto-refunded

Questions? Email [email protected]. Also on GitBook.