Order states
Three of the five are the end of the story.
state | Terminal | What it means |
|---|---|---|
accepted | no | The reference is claimed. Nothing has been bought yet. |
processing | no | We are buying it. Keep watching. |
delivered | yes | Bought. For prepaid electricity, there is a token. |
failed | yes | It did not complete. |
refunded | yes | It 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
accepted -> processing -> deliveredMost 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.
accepted -> processing -> failed
accepted -> processing -> refundedfailed 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.
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.
{
"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.