Orders

Place an order

POSThttps://stagingapi.getelectric.ng/api/v2/reseller/orders

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.

Request
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"
}'
Body
{
  "reference": "alpha-2026-11-18-0001",
  "service": "electricity",
  "meter_number": "11111111111",
  "disco_code": "IKEDC",
  "amount": 5000,
  "access_code": "sbx_4f1c9a2b7e6d3085a1b4c7d2",
  "phone_number": "08031234567"
}
Response
// 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

Authorizationstringheaderrequired

Your reseller API key, as Bearer <key>.

Body

Electricity

referencestringrequired

Your 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

servicestring

Left out, electricity is assumed.

Always electricity · Defaults to electricity

meter_numberstringrequired
disco_codestringrequired
amountnumberrequired

Naira.

Greater than 0

access_codestringrequired

From verifyMeter. In test mode it is checked, so you cannot skip the verify step.

At most 100 characters

phone_numberstring

Optional. Echoed back on the order, not validated.

Airtime, data or cable TV

referencestringrequired

Your own unique reference. Required on every order.

At most 120 characters

servicestringrequired

cable-tv and cabletv are accepted too, and case does not matter.

One of airtime, data, cable_tv

provider_idintegerrequired

From listProviders.

1 or more

targetstringrequired

The phone number or smartcard being paid for.

At most 64 characters

amountnumber

For anything priced by amount. Send this or plan_id.

Greater than 0

plan_idinteger

From listPlans, for anything sold as a plan. Send this or amount.

1 or more

phone_numberstring

Optional. Echoed back on the order, not validated.

lookupobject

What 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_namestring
customer_numberstring
invoice_periodinteger

Only sent on when greater than 0.

package_namestring

Response 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.

successbooleanrequired
statusstringrequired
codeintegerrequired
messagestringrequired
dataobjectrequired

Every field is always present. An empty string or a zero id comes back as null rather than being left out.

Show child attributes
referencestringrequired

Your reference, as you sent it.

At most 120 characters

modestringrequired

One of live, test

servicestringrequired

One of electricity, airtime, data, cable_tv

statestringrequired

delivered, failed and refunded are terminal. accepted and processing are not: keep polling, or wait for the webhook.

One of accepted, processing, delivered, failed, refunded

settledbooleanrequired

True once the state is terminal and the money has stopped moving.

meter_numberstringnullablerequired
disco_codestringnullablerequired
targetstringnullablerequired

The phone or smartcard number, for anything that is not electricity.

At most 64 characters

provider_idintegernullablerequired
plan_idintegernullablerequired
amountnumberrequired

Naira.

messagestringrequired

Plain words about where the order stands. For people, not for branching on.

transactionstringnullablerequired

Our transaction reference, once there is one.

tokenstringnullablerequired

The electricity token, once delivered. Never set for anything but electricity.

token_unitsnumbernullablerequired

Units the token carries, in kWh.

placed_atstringrequired

Always 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_atstringrequired

UTC with no offset, written 2026-11-18T09:14:22Z.

phone_numberstringnullablerequired

Whatever 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.