Skip to navigation
VTUAgent Consumable APIAirtime

Purchase Airtime

View as Markdown

Purchase airtime for a Nigerian mobile number.

Your wallet is debited immediately and the purchase is queued to the network provider. The request then long-polls for up to 15 seconds for the provider’s result. If the provider has not answered by then you receive 202 with status: "pending" — the transaction is still in flight, not lost. Track it with POST /v1/transaction/status or via your webhook.

HTTPstatusstatus_codeMeaning
200successful200Airtime delivered
202pending202Still processing after 15 s
400error—Bad payload, validation failure, insufficient balance, or duplicate request_ref
401——Missing, invalid or revoked API key
424failed424Provider rejected the purchase — wallet already refunded
500error—Internal error; wallet is rolled back

Webhook events: airtime.purchase.success, airtime.purchase.failed, airtime.purchase.pending.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
networkenumRequired
Provider service ID, forwarded verbatim.
Allowed values:
phonestringRequired
Recipient number in local format.
amountdouble or stringRequired

Naira. Accepted as a JSON number or a numeric string; always returned as a string.

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

Airtime delivered
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