Skip to navigation
VTUAgent Consumable APIElectricity

Purchase Electricity Units

View as Markdown

Buys prepaid electricity units (returns a token) or settles a postpaid bill.

Before calling: verify the meter with POST /v1/electricity/verify.

Your wallet is debited immediately, then the disco is called synchronously. This endpoint does not long-poll or send a webhook — the HTTP response is final unless it is 202 pending, in which case resolve it with POST /v1/transaction/status.

token and units are populated only for successful prepaid purchases; otherwise they are "" / null.

HTTPstatusstatus_codeMeaning
200successful200Purchase completed — token returned for prepaid
202pending202Disco still processing — poll /v1/transaction/status
400error—Bad payload, validation failure, insufficient balance, or duplicate request_ref
401——Missing, invalid or revoked API key
424failed424Disco rejected the purchase — wallet refunded
500error—Provider unreachable

Authentication

AuthorizationBearer

API key issued from the VTUAgent dashboard, sent as Authorization: Bearer {your_api_key}.

Request

This endpoint expects an object.
discoenumRequired
meter_numberstringRequired
meter_typeenumRequired
Allowed values:
amountdouble or stringRequired

Naira. Minimums vary by disco (typically 1000).

phonestringRequired
The prepaid token is also sent here by SMS.
request_refstringRequired<=50 characters

Your unique reference for this transaction, max 50 characters. A UUID is recommended. Re-using one is rejected with 400.

Response

Purchase completed — token returned for prepaid

statusenum
Allowed values:
status_codeenum
Always equals the HTTP status.
Allowed values:
messagestring
referencestringOptional

Echo of your request_ref.

datamap from strings to anyOptional

Product-specific details; see the endpoint examples.

Errors

400
Bad Request Error
401
Unauthorized Error
424
Failed Dependency Error
500
Internal Server Error