Webhooks

Voucher orders fire webhooks at terminal status transitions (order.delivered, order.partially_delivered, order.failed, order.cancelled) and wallet credits/debits.

For signing and verification mechanics (shared across all webhook types), see Signature Verification. For event delivery, retry policy, and headers, see the Webhooks overview.

For top-up and recharge events, see Topup Webhooks. For eSIM events, see eSIM Webhooks.

Order Events

Order webhooks notify you when an order's delivery status changes.

`order.delivered`

Triggered when all vouchers in an order have been successfully fulfilled.

{
  "id": "evt_abc123",
  "type": "order.delivered",
  "created_at": "2025-01-15T14:30:00Z",
  "data": {
    "id": 12345,
    "client_reference": "MY_ORDER_001",
    "status": "DELIVERED",
    "product_name": "Steam Wallet Card",
    "denomination": 50.00,
    "quantity": 5,
    "amount": 250.00,
    "delivered_quantity": 5,
    "delivered_on": "2025-01-15T14:30:00Z",
    "created_at": "2025-01-15T14:00:00Z"
  }
}

`order.partially_delivered`

Triggered when some vouchers in an order have been fulfilled but others are still pending or failed.

{
  "id": "evt_def456",
  "type": "order.partially_delivered",
  "created_at": "2025-01-15T14:35:00Z",
  "data": {
    "id": 12346,
    "client_reference": "BULK_ORDER_001",
    "status": "PARTIALLY_DELIVERED",
    "product_name": "Google Play Gift Card",
    "denomination": 25.00,
    "quantity": 100,
    "amount": 2500.00,
    "delivered_quantity": 87,
    "delivered_on": "2025-01-15T14:35:00Z",
    "created_at": "2025-01-15T13:00:00Z"
  }
}

`order.failed`

Triggered when an order could not be fulfilled.

{
  "id": "evt_fail789",
  "type": "order.failed",
  "created_at": "2025-01-15T15:00:00Z",
  "data": {
    "id": 12347,
    "client_reference": "MY_ORDER_003",
    "status": "FAILED",
    "product_name": "Free Fire Diamonds",
    "denomination": 100.00,
    "quantity": 10,
    "amount": 1000.00,
    "delivered_quantity": 0,
    "delivered_on": null,
    "created_at": "2025-01-15T14:50:00Z"
  }
}

`order.cancelled`

Triggered when an order is cancelled.

{
  "id": "evt_cancel012",
  "type": "order.cancelled",
  "created_at": "2025-01-15T15:10:00Z",
  "data": {
    "id": 12348,
    "client_reference": "MY_ORDER_004",
    "status": "CANCELLED",
    "product_name": "Xbox Gift Card",
    "denomination": 50.00,
    "quantity": 3,
    "amount": 150.00,
    "delivered_quantity": 0,
    "delivered_on": null,
    "created_at": "2025-01-15T15:00:00Z"
  }
}

Order Event Data Fields

Key	Type	Description
`id`	integer	Order ID
`client_reference`	string	Your reference code for the order (the value you supplied on order creation)
`status`	string	`DELIVERED` or `PARTIALLY_DELIVERED`
`product_name`	string	Name of the product ordered
`denomination`	number	Face value per voucher
`quantity`	integer	Total vouchers ordered
`amount`	number	Total face value of the order
`delivered_quantity`	integer	Number of vouchers successfully delivered
`delivered_on`	string	Timestamp of delivery (RFC 3339)
`created_at`	string	When the order was placed (RFC 3339)

After receiving an order.delivered or order.partially_delivered webhook, call GET /api/v1/orders/:id to retrieve the full order with voucher codes and PINs. The webhook payload confirms delivery but does not include the voucher codes themselves.

Wallet Events

Wallet webhooks notify you when funds are credited to or debited from your wallet.

`wallet.credited`

Triggered when funds are added to your wallet (e.g. a top-up by your account manager).

{
  "id": "evt_wal001",
  "type": "wallet.credited",
  "created_at": "2025-01-15T10:00:00Z",
  "data": {
    "wallet_id": 1,
    "ledger_id": 789,
    "amount": "1000.00",
    "currency": "USD",
    "reference_number": "TOPUP-2025-001",
    "remarks": "USD Wallet credited by amount 1000.00 - Monthly top-up"
  }
}

`wallet.debited`

Triggered when funds are deducted from your wallet (e.g. order settlement, payout, or manual adjustment).

{
  "id": "evt_wal002",
  "type": "wallet.debited",
  "created_at": "2025-01-15T14:30:00Z",
  "data": {
    "wallet_id": 1,
    "ledger_id": 790,
    "amount": "241.25",
    "currency": "USD",
    "reference_number": "MY_ORDER_001",
    "remarks": "USD Wallet deducted by amount 241.25 for order reference code MY_ORDER_001"
  }
}

Wallet Event Data Fields

Key	Type	Description
`wallet_id`	integer	Wallet that was credited or debited
`ledger_id`	integer	Internal ledger entry ID for audit trail
`amount`	string	Amount credited or debited (decimal string, e.g. `"1000.00"`)
`currency`	string	Currency code of the wallet (e.g. `USD`)
`reference_number`	string	Reference linking this to the originating operation (order ref, top-up ref, etc.)
`remarks`	string	Human-readable description of the transaction

Supported Events Summary

Event	Trigger
`order.delivered`	All vouchers in the order fulfilled
`order.partially_delivered`	Some vouchers fulfilled, others pending or failed
`order.failed`	Order could not be fulfilled
`order.cancelled`	Order was cancelled
`wallet.credited`	Funds added to wallet (top-up, refund)
`wallet.debited`	Funds deducted from wallet (order, payout, adjustment)

On this page