Webhooks

LIVE
Setting Up

Your webhook URL is configured on your API key. Go to your dashboard to set or update it.

Delivery

Webhooks are sent as POST requests with a JSON body. Expect a response time of under 10 seconds.

Webhook Format

All webhooks follow a standard structure. The plan or item field depends on the purchase type.

Successful Purchase 
{
  "event": "data.purchase",
  "reference_code": "TRXDATA20260615100238ONI",
  "status": "successful",
  "message": "Data purchase completed.",
  "plan": "MTN 1GB Monthly",
  "recipient": "08031234567",
  "amount": 500.00,
  "completed_at": "2026-06-15T10:05:00+01:00"
}
Failed Purchase 
{
  "event": "data.purchase",
  "reference_code": "TRXDATA20260615100238ONI",
  "status": "failed",
  "message": "Transaction failed. Your wallet has been refunded.",
  "plan": "MTN 1GB Monthly",
  "recipient": "08031234567",
  "amount": 500.00,
  "completed_at": "2026-06-15T10:05:00+01:00"
}
With Token or Pin

For electricity and exam purchases, a pin field is included when the token or pin is generated: 

{
  "event": "electricity.purchase",
  "reference_code": "TRXEE20260615104818CQ3",
  "status": "successful",
  "message": "Electricity purchase completed.",
  "item": "Ikeja Electricity - IKEDC (PHCN)",
  "recipient": "1234567890",
  "amount": 5000.00,
  "pin": "1234-5678-9012-3456-7890",
  "completed_at": "2026-06-15T10:05:00+01:00"
}
Webhook Fields
Field Type Description
event string Purchase event (e.g. data.purchase)
reference_code string Your transaction reference for status checks
status string successful or failed
message string Human-readable status description
plan string Plan name (for data and tv purchases)
item string Item name (for airtime, electricity, bet, and education purchases)
recipient string Phone number, smartcard, meter number, or customer ID
amount float Amount charged
pin string Token or exam pin (electricity and education only)
completed_at string Timestamp when the transaction was finalised
Retry Policy

If your server does not return a 2xx response, we retry:

Attempt Delay
1st 5 seconds
2nd 15 seconds
3rd 60 seconds

After 3 failed attempts, the webhook is dropped and logged.

Verifying Webhooks

Use the reference_code to fetch the full transaction status from GET /transaction/status . This serves as a backup if a webhook is missed.