VTUmerce API

Integrate airtime, data and bill payments directly into your own application. All endpoints are versioned under /v1 and return JSON.

Base URL

https://api.azmerce.com/api/v1

Authentication

Generate an API key from your account's Developer API page, then send it as a Bearer token on every request:

Authorization: Bearer YOUR_API_KEY

API keys are separate from your login session - your app token cannot be used here, and revoking an API key never logs you out of the app. Requests are rate-limited to 60 per minute per key.

Wallet

GET/wallet

Get your current wallet balance.

Response

{
  "balance": "705.00",
  "commission_balance": "0.00"
}

Airtime

GET/airtime/networks

List supported networks and their IDs.

Response

[
  { "id": 1, "name": "MTN", "airtime_enabled": true }
]

POST/airtime/buy

Purchase airtime. Requires your account's wallet PIN.

Request body

{
  "network_id": 1,
  "phone": "08031234567",
  "amount": 500,
  "pin": "1234"
}

Response

{
  "transaction": { "reference": "TXN-...", "status": "successful", ... },
  "message": "Airtime purchase successful."
}

Data

GET/data/plans?network_id=1

List available data plans for a network.

Response

[
  { "id": 12, "plan_name": "1GB - 30 days (SME)", "customer_price": "350.00" }
]

POST/data/buy

Purchase a data plan. Requires your account's wallet PIN.

Request body

{
  "network_id": 1,
  "plan_id": 12,
  "phone": "08031234567",
  "pin": "1234"
}

Response

{
  "transaction": { "reference": "TXN-...", "status": "successful", ... },
  "message": "Data purchase successful."
}

Electricity

GET/bills/electricity/providers

List electricity discos.

Response

[ { "id": 1, "name": "Ikeja Electric" } ]

POST/bills/electricity/validate

Validate a meter number before purchase.

Request body

{ "provider_id": 1, "meter_number": "12345678901", "meter_type": "prepaid" }

Response

{ "customer_name": "JOHN DOE" }

POST/bills/electricity/buy

Pay an electricity bill. Requires your account's wallet PIN.

Request body

{
  "provider_id": 1,
  "meter_number": "12345678901",
  "meter_type": "prepaid",
  "amount": 5000,
  "pin": "1234"
}

Response

{
  "transaction": { "reference": "TXN-...", "status": "successful", ... },
  "message": "Electricity purchase successful."
}

Cable TV

GET/bills/cable/providers

List cable TV providers (DSTV, GOTV, etc.).

Response

[ { "id": 1, "name": "DSTV" } ]

GET/bills/cable/providers/1/packages

List subscription packages for a provider.

Response

[ { "id": 5, "package_name": "Compact", "customer_price": "9000.00" } ]

POST/bills/cable/validate

Validate a smartcard number before purchase.

Request body

{ "provider_id": 1, "smartcard_number": "1234567890" }

Response

{ "customer_name": "JOHN DOE" }

POST/bills/cable/buy

Purchase a cable subscription. Requires your account's wallet PIN.

Request body

{
  "provider_id": 1,
  "package_id": 5,
  "smartcard_number": "1234567890",
  "pin": "1234"
}

Response

{
  "transaction": { "reference": "TXN-...", "status": "successful", ... },
  "message": "Cable purchase successful."
}

Transactions

GET/transactions/{reference}

Look up the status of a transaction by its reference.

Response

{ "reference": "TXN-...", "status": "successful", "selling_price": "500.00" }

Errors

Errors return a non-2xx status with a JSON body containing a message field.401 means a missing/invalid API key, 422 means validation failed or the wallet PIN was wrong, 429means you've exceeded the rate limit.