Placing an order

One endpoint for all four services, in two shapes.

Place an order is the only call that spends money. Everything else here is a read.

Electricity

Verify first, always. The access_code that comes back is required.

1. Verifybash
curl https://stagingapi.getelectric.ng/api/v2/reseller/meters/verify \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{ "meter_number": "11111111111", "disco_code": "IKEDC" }'

Show the customer the name and address you get back, and only then:

2. Orderbash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "alpha-000147",
    "service": "electricity",
    "meter_number": "11111111111",
    "disco_code": "IKEDC",
    "amount": 5000,
    "access_code": "sbx_4f1c9a2b7e6d3085a1b4c7d2",
    "phone_number": "08031234567"
  }'

service may be left out for electricity; it is the default. phone_number is optional, echoed back on the order, and not validated by us.

Airtime

No verification, no plan. A provider and a number.

Airtimebash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "alpha-000148",
    "service": "airtime",
    "provider_id": 3,
    "target": "08000000001",
    "amount": 500
  }'

Data

Send plan_id when the customer picked a bundle.

A data bundlebash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "alpha-000149",
    "service": "data",
    "provider_id": 3,
    "plan_id": 184,
    "target": "08000000001"
  }'

Cable TV

Verify the smartcard, then hand back what the lookup told you so the invoice matches what the customer was shown.

1. Verify the smartcardbash
curl https://stagingapi.getelectric.ng/api/v2/reseller/targets/verify \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{ "provider_id": 12, "target": "08000000001" }'
2. Order, carrying the lookupbash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "alpha-000150",
    "service": "cable_tv",
    "provider_id": 12,
    "plan_id": 902,
    "target": "08000000001",
    "lookup": {
      "customer_name": "Sandbox Customer",
      "customer_number": "08000000001",
      "package_name": "Sandbox Bouquet",
      "invoice_period": 1
    }
  }'

Note

Only customer_name, customer_number, invoice_period and package_name are forwarded. Anything else you put in lookup is dropped without complaint, so do not use it to carry your own metadata; it will not come back.

Which fields are required

FieldElectricityAirtime, data, cable TV
referencerequiredrequired
serviceoptional, defaults to electricityrequired
meter_numberrequirednot used
disco_coderequirednot used
access_coderequirednot used
provider_idnot usedrequired
targetnot usedrequired
amountrequiredrequired unless plan_id is sent
plan_idnot usedalternative to amount
phone_numberoptionaloptional
lookupnot usedcable TV only

Limits: reference 120 characters, access_code 100, target 64, and the whole body 64 KiB.

What comes back

A success is 202 with "Order accepted.", and the order is usually still processing. A repeat of a reference you have used is 200. Neither is 201.

202 Acceptedjson
{
  "success": true,
  "status": "success",
  "code": 202,
  "message": "Order accepted.",
  "data": {
    "reference": "alpha-000147",
    "mode": "test",
    "service": "electricity",
    "state": "processing",
    "settled": false,
    "amount": 5000,
    "token": null,
    "token_units": null,
    "placed_at": "2026-11-18T09:14:22Z"
  }
}

Every field on an order is always present. An empty string or a zero id comes back as null rather than being left out, so you can read a field without checking whether it exists.

Then follow it: Order states.