Convert airtime to wallet

X-API-Key

POST/airtime-to-cash/convert

Transfers airtime from the customer's line and credits their VendPower wallet. amount is airtime face value; wallet credit = amount × convert_percent / 100. Response data.amount is the wallet credit. API keys do not send transaction_pin (app/Sanctum only).

Language

curl -X POST "https://api.vendpower.ng/api/v1/airtime-to-cash/convert" \
  -H "X-API-Key: YOUR_X_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "biller_code": "MTN",
    "session_id": "a2c_sess_abc123",
    "amount": 1000,
    "pin": "1234",
    "idempotency_key": "VP_A2C_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`
session_id	string	Yes	From verify OTP
amount	number	Yes	Airtime face amount (NGN)
pin	string	Yes	Network share & sell PIN
idempotency_key	string	No	Unique key; auto-generated if omitted. Recommended for all convert / purchase calls.
transaction_pin	string	App only	5-digit VendPower PIN (Sanctum) — not used with API keys

Responses

200 OK — Credited · 202 Accepted — Processing

{
  "success": true,
  "message": "Successful. Your wallet has been credited.",
  "data": {
    "id": 99050,
    "reference": "VP_A2C_001",
    "idempotency_key": "VP_A2C_001",
    "status": "success",
    "category": "airtime_to_cash",
    "amount": 850,
    "charge": 0,
    "receive_amount": 850,
    "face_amount": 1000,
    "service_fee": 150,
    "biller_name": "MTN · Vend Airtime to Cash",
    "customer_phone": "08031234567",
    "provider": "mtn_direct",
    "metadata": {
      "face_amount": 1000,
      "receive_amount": 850,
      "convert_percent": 85,
      "service_fee": 150,
      "platform_fee_percent": 15,
      "network": "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

Failed converts do not debit or credit the wallet.
Poll GET /transactions/{id} if status is processing.
Typical flow: billers → send OTP → verify OTP → (optional balance) → convert.