Payout & Bill Events

payout_initiated

Fires when a payout is requested (POST /v1/payouts): the merchant balance is debited and the bank transfer is queued.

{
  "id": "evt_01hkbz5poutini0000000000000",
  "type": "payout_initiated",
  "createdAt": "2026-06-29T14:00:00.000Z",
  "data": {
    "payoutId": "payout_01hkbz7p8o9i0u1y2t3r4e5w6q",
    "amount": 2500000,
    "bankCode": "058",
    "accountNumber": "0123456789",
    "reference": "DURO-POUT-3C7F91"
  }
}

payout_completed

Fires when the bank transfer is accepted. Carries the settled payout in full, including the nombaReference and completedAt.

{
  "id": "evt_01hkbz5poutcmp0000000000000",
  "type": "payout_completed",
  "createdAt": "2026-06-29T14:01:30.000Z",
  "data": {
    "payoutId": "payout_01hkbz7p8o9i0u1y2t3r4e5w6q",
    "amount": 2500000,
    "currency": "NGN",
    "bankCode": "058",
    "accountNumber": "0123456789",
    "accountName": "ADA LOVELACE",
    "reference": "DURO-POUT-3C7F91",
    "nombaReference": "3f7a9c21-8b4d-4e6f-9a0b-1c2d3e4f5a6b",
    "status": "completed",
    "completedAt": "2026-06-29T14:01:30.000Z"
  }
}

payout_failed

Fires when the transfer fails; the merchant balance is refunded. Carries the failure reason.

{
  "id": "evt_01hkbz5poutfal0000000000000",
  "type": "payout_failed",
  "createdAt": "2026-06-29T14:01:30.000Z",
  "data": {
    "payoutId": "payout_01hkbz7p8o9i0u1y2t3r4e5w6q",
    "amount": 2500000,
    "reason": "transfer rejected by bank"
  }
}

bill_payment_completed

Fires when a bill or VAS purchase (airtime, data, betting, cable TV, or electricity) completes. Carries the bill transaction with its category, provider, recipient, and provider meta (for example an electricity token).

{
  "id": "evt_01hkbz5billcmp0000000000000",
  "type": "bill_payment_completed",
  "createdAt": "2026-06-29T15:00:00.000Z",
  "data": {
    "billTransactionId": "billtransaction_01hkbz8b7c6d5e4f3g2h1j0k9l",
    "category": "electricity",
    "provider": "ikeja-electric",
    "recipient": "45300012345",
    "amount": 1000000,
    "currency": "NGN",
    "status": "successful",
    "reference": "DURO-BILL-9A2C41",
    "nombaReference": "7c1e9b3a-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
    "meta": { "token": "0123-4567-8901-2345-6789", "units": "213.5 kWh" }
  }
}