Purchase airtime

X-API-Key

POST/airtime/purchase

Send face value in amount (NGN). Wallet debit = face × charge_percent / 100. Success: 200 · pending: 201 · failed/refunded: 400. Poll like cable.

Language

curl -X POST "https://api.vendpower.ng/api/v1/airtime/purchase" \
  -H "X-API-Key: YOUR_X_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "biller_code": "MTN",
    "phone": "08031234567",
    "amount": 1000,
    "idempotency_key": "VP_AIRTIME_001"
  }'

Authentication

Send your approved API key on every request. Keep it on your server only.

Header	Value	Required
X-API-Key	YOUR_X_API_KEY	Yes
Content-Type	application/json	Yes
Accept	application/json	Recommended

Authentication failures (401 / 403 / 429) are listed in Authentication.

Parameters

Body parameters

Name	Type	Required	Description
biller_code	string	Yes	`MTN` \| `GLO` \| `AIRTEL` \| `9MOBILE`
phone	string	Yes	Nigerian MSISDN, e.g. `08031234567` (11 digits). Must match the network for airtime and data.
amount	number	Yes	Face airtime amount in NGN
idempotency_key	string	Yes	Your unique purchase key (recommended `VP…`). Re-sending the same key returns `409` with the original transaction — never charges twice.

Responses

200 OK — Delivered · 201 Created — Pending

{
  "success": true,
  "message": "Airtime delivered successfully.",
  "data": {
    "id": 88001,
    "reference": "VP_AIRTIME_001",
    "idempotency_key": "VP_AIRTIME_001",
    "status": "success",
    "category": "airtime",
    "amount": 1000,
    "charge": 1000,
    "biller_name": "MTN",
    "customer_phone": "08031234567",
    "metadata": {
      "phone": "08031234567",
      "network": "MTN",
      "biller_code": "MTN"
    }
  }
}

Errors

Errors specific to this endpoint, in addition to common authentication and validation failures.

Code	HTTP	When
VALIDATION_ERROR	422	Request body failed validation or business rules.
INSUFFICIENT_BALANCE	400 / 402	Wallet balance is too low for this purchase.
DUPLICATE_IDEMPOTENCY	409	This `idempotency_key` was already used — requery the returned transaction.
SERVICE_UNAVAILABLE	503	Upstream provider or service is temporarily unavailable.

Notes

Pending (201): poll GET /transactions/{id or reference} and POST /transactions/{id}/requery until terminal.
For T2 (9mobile), send biller_code: "9MOBILE".