Skip to navigation
VTUAgent Consumable APIData

Purchase Data Bundle

View as Markdown

Purchase a mobile data bundle using a plan_id from GET /v1/data/plans. The amount is taken from your account-tier price — you do not send it.

Your wallet is debited immediately and the purchase is queued. The request long-polls for up to 15 seconds; if the provider has not answered you receive 202 with status: "pending". Track it with POST /v1/transaction/status or via your webhook.

HTTPstatusstatus_codeMeaning
200successful200Bundle delivered
202pending202Still processing after 15 s
400error—Bad payload, unknown/unsupported plan, 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: data.purchase.success, data.purchase.failed (none while pending).

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
plan_idstringRequired

From GET /v1/data/plans.

phonestringRequired
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

Bundle 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