Create a purchase
POST
https://instantrecharge.com.ng/api/v1/transactionsCreates and delivers an order in one call. Most orders come back delivered; some come back pending while the provider confirms, so check them with Get a purchase.
Send a unique Idempotency-Key with every purchase. If a request times out, send it again with the same key: you get the original order back (replayed: true) instead of a second purchase.
Prices come from our catalogue, never from the request: for plan-priced products send variationCode, for amount-priced products send amount.
Requires your API key.
Headers
| Name | Type | Description |
|---|---|---|
Authorizationrequired | string | Bearer followed by your API key. |
Idempotency-Keyrequired | string | Your unique reference for this purchase, up to 100 characters. |
Request body
| Name | Type | Description |
|---|---|---|
serviceIDrequired | string | Product code from List products. |
recipientrequired | string | Phone (11 digits, e.g. 08031234567), meter, smartcard, JAMB profile ID or plate number. Not used for WAEC PINs. |
variationCode | string | Plan code from List plans. Required for plan-priced products. |
amount | number | Amount in naira. Required for amount-priced products (airtime, electricity). Minimum ₦50 for airtime, ₦500 for electricity. |
quantity | integer | How many PINs, 1–10, for products that allow it. Default 1. |
meterType | string | Electricity only. Default prepaid.One of: prepaid, postpaid |
customerPhone | string | Your customer's phone. Required for WAEC PINs (the PIN is tied to it). |
customerEmail | string | Required for international airtime and insurance. |
international | object | International airtime only. Codes come from List options. |
international.countryCoderequired | string | kind=countries |
international.productTypeIdrequired | string | kind=product-types |
international.operatorIdrequired | string | kind=operators |
insurance | object | Third-party motor insurance only: insuredName, chassisNumber, engineCapacity, vehicleMake, vehicleModel, vehicleColor, yearOfMake, state and lga. Codes come from List options (insurance-*). |
Responses
201Order created. Check status: delivered, pending or failed.
{
"data": {
"id": "IR7F3A9C21B0",
"reference": "inv-2026-000184",
"service": "MTN N100 100MB - 24 hrs",
"category": "Data",
"recipient": "08031234567",
"amount": 100,
"status": "delivered",
"paymentStatus": "paid",
"token": "4231 7718 0921 5530 1128",
"message": null,
"receiptUrl": "/api/v1/orders/IR7F3A9C21B0/receipt",
"addressProof": false,
"createdAt": "2026-11-15 14:09:31"
},
"replayed": false
}200Same Idempotency-Key as an earlier purchase: the original order, unchanged.
{
"data": {
"id": "IR7F3A9C21B0",
"reference": "inv-2026-000184",
"service": "MTN N100 100MB - 24 hrs",
"category": "Data",
"recipient": "08031234567",
"amount": 100,
"status": "delivered",
"paymentStatus": "paid",
"token": "4231 7718 0921 5530 1128",
"message": null,
"receiptUrl": "/api/v1/orders/IR7F3A9C21B0/receipt",
"addressProof": false,
"createdAt": "2026-11-15 14:09:31"
},
"replayed": true
}400Something in the request is missing or invalid.
{
"type": "order_error",
"message": "Enter a valid 11-digit Nigerian phone number"
}401Missing or wrong API key.
{
"type": "unauthorized",
"message": "A valid API key is required"
}503Purchases are paused for a few minutes. Retry later with the same Idempotency-Key.
{
"type": "order_error",
"message": "Purchases are paused for a few minutes while we top up. Please try again shortly."
}
