Orders
Place an order
Buy electricity, airtime, data or cable TV. This is the only endpoint that spends money.
Your reference is claimed before anything is charged, so sending the same reference twice can never vend twice: the second call returns the first order with a 200. A timed-out request is therefore safe to retry with the same reference, and that is the only safe way to retry.
A successful call answers 202, not 201, and the order is rarely terminal yet. Follow it with getOrder, or wait for the order.settled webhook.
May use your whole in-flight budget. Works with a live or test key.
curl -X POST 'https://stagingapi.getelectric.ng/api/v2/reseller/orders' \
-H 'Authorization: Bearer <your-test-key>' \
-H 'Content-Type: application/json' \
-d '{
"reference": "alpha-2026-11-18-0001",
"service": "electricity",
"meter_number": "11111111111",
"disco_code": "IKEDC",
"amount": 5000,
"access_code": "sbx_4f1c9a2b7e6d3085a1b4c7d2",
"phone_number": "08031234567"
}'{
"reference": "alpha-2026-11-18-0001",
"service": "electricity",
"meter_number": "11111111111",
"disco_code": "IKEDC",
"amount": 5000,
"access_code": "sbx_4f1c9a2b7e6d3085a1b4c7d2",
"phone_number": "08031234567"
}// This reference was used before, so nothing new was charged and the original order is returned. A retry landing here is the idempotency guarantee working.Authorization
AuthorizationstringheaderrequiredYour reseller API key, as Bearer <key>.
Body
Electricity
referencestringrequiredYour own unique reference. Required on every order. Retrying with the same one will not vend twice, which makes it the only safe way to retry.
At most 120 characters
servicestringLeft out, electricity is assumed.
Always electricity · Defaults to electricity
meter_numberstringrequireddisco_codestringrequiredamountnumberrequiredNaira.
Greater than 0
access_codestringrequiredFrom verifyMeter. In test mode it is checked, so you cannot skip the verify step.
At most 100 characters
phone_numberstringOptional. Echoed back on the order, not validated.
Airtime, data or cable TV
referencestringrequiredYour own unique reference. Required on every order.
At most 120 characters
servicestringrequiredcable-tv and cabletv are accepted too, and case does not matter.
One of airtime, data, cable_tv
provider_idintegerrequiredFrom listProviders.
1 or more
targetstringrequiredThe phone number or smartcard being paid for.
At most 64 characters
amountnumberFor anything priced by amount. Send this or plan_id.
Greater than 0
plan_idintegerFrom listPlans, for anything sold as a plan. Send this or amount.
1 or more
phone_numberstringOptional. Echoed back on the order, not validated.
lookupobjectWhat verifyTarget told you, handed back so the invoice matches what the customer was shown. Only these four keys are forwarded; anything else is dropped without complaint.
Show child attributes
customer_namestringcustomer_numberstringinvoice_periodintegerOnly sent on when greater than 0.
package_namestringResponse 200
This reference was used before, so nothing new was charged and the original order is returned. A retry landing here is the idempotency guarantee working.
successbooleanrequiredstatusstringrequiredcodeintegerrequiredmessagestringrequireddataobjectrequiredEvery field is always present. An empty string or a zero id comes back as null rather than being left out.
Show child attributes
referencestringrequiredYour reference, as you sent it.
At most 120 characters
modestringrequiredOne of live, test
servicestringrequiredOne of electricity, airtime, data, cable_tv
statestringrequireddelivered, failed and refunded are terminal. accepted and processing are not: keep polling, or wait for the webhook.
One of accepted, processing, delivered, failed, refunded
settledbooleanrequiredTrue once the state is terminal and the money has stopped moving.
meter_numberstringnullablerequireddisco_codestringnullablerequiredtargetstringnullablerequiredThe phone or smartcard number, for anything that is not electricity.
At most 64 characters
provider_idintegernullablerequiredplan_idintegernullablerequiredamountnumberrequiredNaira.
messagestringrequiredPlain words about where the order stands. For people, not for branching on.
transactionstringnullablerequiredOur transaction reference, once there is one.
tokenstringnullablerequiredThe electricity token, once delivered. Never set for anything but electricity.
token_unitsnumbernullablerequiredUnits the token carries, in kWh.
placed_atstringrequiredAlways UTC, written 2026-11-18T09:14:22Z with no offset. Note that the webhook uses a different format, so parse with a real RFC 3339 parser rather than a fixed pattern.
UTC with no offset, written 2026-11-18T09:14:22Z.
updated_atstringrequiredUTC with no offset, written 2026-11-18T09:14:22Z.
phone_numberstringnullablerequiredWhatever you sent, echoed back. We do not validate it.
Other responses
- 401
- No key, a malformed Authorization header, or a key that no longer exists.
- 403
- The key is real but may not do this. Three separate causes, and only the message tells them apart: the token cannot use the reseller API at all, the calling address is not on your allowlist, or the key carries both test and live access and must be reissued for one mode.
- 422
- Refused. Either the request was not valid, or the order failed outright. When the order itself failed, success is false and data still holds the order, which is the one place in this API where a failed response carries a body. Read data.state for what happened to the money: refunded means you were not charged in the end.
- 429
- You have too many requests open at once. This is a concurrency cap, not a rate limit: wait for your open requests to finish rather than backing off a fixed time. Retry-After is 1.
- 503
- We could not reach the provider. Safe to retry, and for an order you must retry with the same reference.