Order states

Three of the five are the end of the story.

stateTerminalWhat it means
acceptednoThe reference is claimed. Nothing has been bought yet.
processingnoWe are buying it. Keep watching.
deliveredyesBought. For prepaid electricity, there is a token.
failedyesIt did not complete.
refundedyesIt did not complete and the money came back to you.

settled is true exactly when the state is terminal and the money has stopped moving. Reading settled is the simplest way to ask "is this finished?" without listing states.

Important

Do not give your customer value on accepted or processing. Wait for delivered. For prepaid electricity, wait for the token.

How an order usually moves

The happy pathtext
accepted -> processing -> delivered

Most orders are processing when POST /reseller/orders returns, and settle within seconds. Some settle before the response is even written, which is why you may see delivered straight away. Both are normal and your code should handle either.

The otherstext
accepted -> processing -> failed
accepted -> processing -> refunded

failed and refunded are not the same

refunded is the better outcome: the order did not happen and your balance was put back. failed means it did not complete, and whether anything was charged depends on where it broke.

Warning

If you have to pick one thing to get right in your error handling, make it this: on a terminal non-delivery, read state rather than assuming. Telling a customer their money is coming back when the state says failed, or holding onto a refund that already landed, are both worse than saying "we are checking".

A refund amount appears on the webhook as refund_amount. The order object does not carry one.

Finding out it changed

Two ways, and you want both.

Webhooks, for ordinary operation. We call you once, when the order reaches a terminal state. See Webhooks.

Polling, for recovery. Get an order by your reference, any time.

Pollbash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders/alpha-000147 \
  -H 'Authorization: Bearer <your-key>'

Tip

Do not build on webhooks alone. An endpoint that was down for an hour, a deploy that dropped a request, a signature check you got wrong on your first day: all of them end with an order you never heard about. A reconciliation pass that polls anything still non-terminal after a few minutes costs little and catches all of it.

Poll with a bit of patience rather than in a tight loop. A second or two between attempts is plenty, and remember that polls share your in-flight budget with everything except placing orders. See Concurrency limits.

The inline failure

POST /reseller/orders can come back success: false with a 422 and the order in data, already terminal. That is an order that failed immediately rather than one that was rejected before it started.

Failed on arrivaljson
{
  "success": false,
  "status": "failed",
  "code": 422,
  "message": "The provider refused this meter.",
  "data": { "reference": "alpha-000160", "state": "refunded", "settled": true }
}

There is no webhook for this one, because the order was already settled when you were told about it. Read data.state and you have your answer.

Note

In the sandbox, the reserved meter 22222222222 produces this shape with state: "refunded". The live path produces the same shape with state: "failed". They genuinely differ, so handle both rather than matching one.

Tokens

token and token_units are set for prepaid electricity once delivered, and are null everywhere else, including on postpaid meters where there is nothing to type in. In the sandbox the token is made up and the units come from a flat 70 naira per kWh.