Skip to main content
POST
Make a Purchase

Request

string
required
Your API secret key. Format: Bearer <api-key>
string
required
Must be application/json
string
required
Transaction type. One of: airtime, data, cable_tv, electricity
string
required
Network or provider ID from the /services/* endpoints.
  • Airtime: mtn, airtel, glo, 9mobile
  • Data: mtn-data, airtel-data, glo-data, 9mobile-data
  • Cable TV: dstv, gotv, startimes
  • Electricity: ikeja-electric, eko-electric, ibadan-electric, etc.
string
required
  • Airtime/Data: 11-digit Nigerian phone number (e.g. 08012345678)
  • Cable TV: 10-digit smartcard number
  • Electricity: Meter number
number
Amount in NGN. Required for airtime only. Minimum: 50
string
Network name. Required for airtime/data. E.g. mtn, airtel, glo, 9mobile
string
Plan or meter type code. Required for data, cable TV, and electricity. Get valid codes from the /services/* endpoints (e.g. rapid_data_001, rapid_cable_001). For electricity: prepaid or postpaid.
string
required
A unique merchant transaction reference string (UUID or timestamped code) to prevent duplicate charges.
string
An optional unique idempotency key to prevent double-charging on network retries. Can also be passed via the Idempotency-Key HTTP header. Supported in both Live and Sandbox modes.

Examples


Responses

A 200 OK HTTP status means we successfully received and processed your request — not that the top-up was delivered. Always check the data.status field inside the JSON response body: it can be success, pending, or failed. A pending status means the upstream carrier is still processing — use POST /requery to check for the final outcome.
string
success or error
object
✅ Success 200:
❌ Insufficient Balance 422:
For Cable TV and Electricity purchases, you must call GET /services/verify first to validate the account and display the customer name to your user. Skipping this step can result in irreversible charges to the wrong account.