Skip to main content
POST
Purchase Bill / Vend Token
Executes an end-to-end bill payment or utility token purchase.

Transaction Lifecycle

  1. Mandate Check & Direct Debit: Handle checks the user’s active bank account mandate and initiates direct settlement via OnePipe.
  2. Provider Dispatch: Once debit succeeds, the request is sent to the primary provider (Remita / Kuda).
  3. Resilient Failover: If the primary provider fails, Handle automatically shifts fulfillment to a secondary provider without double-debiting the user.
  4. Token Delivery: The generated 20-digit token (for prepaid power), PIN (for exams), or confirmation receipt is returned immediately.

Sample Success Response

Authorizations

Authorization
string
header
default:sk_test_handle_master_key
required

Supply your secret API key (e.g. sk_live_... or sk_test_...) in the Authorization header.

Body

application/json
category
enum<string>
default:ELECTRICITY
required
Available options:
GOVERNMENT,
ELECTRICITY,
AIRTIME,
DATA,
INTERNET,
CABLE_TV,
UTILITIES,
EDUCATION,
FLIGHTS,
BETTING,
GAMING,
SOLAR,
TRANSPORT,
ESIM,
TAXES,
HOSPITALS,
INSURANCE,
RELIGIOUS,
ASSOCIATIONS,
FINANCIAL_SERVICES,
CREDIT_LOANS,
MICRO_PENSIONS,
INVOICE,
GIFT_CARDS,
SHOPPING,
FOOD_DINING,
LIFESTYLE_BEAUTY,
HOME_LIVING
Example:

"ELECTRICITY"

billerCode
string
default:AEDC
required
Example:

"AEDC"

recipientId
string
default:0219927013063
required
Example:

"0219927013063"

amount
number
default:1000
required
Example:

1000

canonicalKey
string
default:electricity:aedc:prepaid
Example:

"electricity:aedc:prepaid"

metadata
object

Response

200 - application/json

Vend receipt, token, and transaction reference

success
boolean
Example:

true

status
string
Example:

"COMPLETED"

reference
string
Example:

"HDL-BILL-1727788412991-842"

providerCode
string
Example:

"KUDA"

providerReference
string
Example:

"KD-TX-9847120938"

token
string
Example:

"4819-2049-1829-4019-3382"

units
string
Example:

"34.5 kWh"

message
string
Example:

"Transaction Successful"

amount
number
Example:

1000

recipientId
string
Example:

"0219927013063"