API Reference

API Reference

Complete reference for all Betavend API endpoints. All requests require a Bearer token. Base URL: https://api.betavend.com

💡

Include X-Idempotency-Key: unique-id on all POST requests to safely retry on network failures without risk of duplicate transactions.

Account

GET /v1/account Get account details

Returns the authenticated user's account information including tier, KYC level, and registration details.

Requestcurl
curl https://api.betavend.com/v1/account \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Shuaib Akanbi",
    "email": "you@example.com",
    "phone": "+2347012345678",
    "tier": "pro",
    "kyc_level": 2,
    "created_at": "2026-01-01T00:00:00.000000Z"
  },
  "request_id": "2d37ae02-a43d-4e85-8e59-8cbf3c2e49e5"
}

Wallet

GET /v1/wallet Get wallet balance

Returns the current wallet balance and bonus balance. All amounts are in Nigerian Naira (NGN).

Requestcurl
curl https://api.betavend.com/v1/wallet \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "data": {
    "balance": 5000.00,
    "bonus_balance": 0.00,
    "currency": "NGN"
  },
  "request_id": "abc-123"
}
GET /v1/wallet/transactions Wallet transaction history

Returns paginated wallet credits and debits including funding, purchases, and reversals.

Query Parameters

ParameterTypeDescription
per_pageoptionalintegerResults per page. Default: 20. Max: 100.
pageoptionalintegerPage number. Default: 1.
Request
curl "https://api.betavend.com/v1/wallet/transactions?per_page=20&page=1" \
  -H "Authorization: Bearer bv_live_your_key"

Data Plans

GET /v1/services/data/plans List available data plans

Returns all enabled data plans. Filter by network to get plans for a specific carrier.

Query Parameters

ParameterTypeDescription
networkoptionalstringmtn · airtel · glo · 9mobile
Request
curl "https://api.betavend.com/v1/services/data/plans?network=mtn" \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "data": {
    "plans": [
      {
        "plan_id": "mtn-1gb-30days",
        "name": "1GB — 30 Days",
        "network": "mtn",
        "amount": 550,
        "validity": "30 Days"
      }
    ]
  },
  "request_id": "abc-123"
}
POST /v1/services/data/purchase Purchase a data bundle

Purchase a data bundle for any Nigerian mobile number. Deducts from your wallet balance. Always include an idempotency key.

Request Body

FieldTypeDescription
networkrequiredstringmtn · airtel · glo · 9mobile
plan_coderequiredstringPlan ID from GET /v1/services/data/plans
phonerequiredstringRecipient phone number in format 08012345678
amountrequirednumberAmount in NGN — must match the plan price
pinrequiredstringYour 5-digit transaction PIN
Requestcurl
curl -X POST https://api.betavend.com/v1/services/data/purchase \
  -H "Authorization: Bearer bv_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-request-id-001" \
  -d '{
    "network": "mtn",
    "plan_code": "mtn-1gb-30days",
    "phone": "08012345678",
    "amount": 550,
    "pin": "12345"
  }'
201 Created
{
  "success": true,
  "message": "Data purchased successfully",
  "data": {
    "reference": "BV-20260502-XXXX",
    "status": "delivered",
    "network": "mtn",
    "phone": "08012345678",
    "plan": "1GB — 30 Days",
    "amount": 550,
    "wallet_balance_after": 4450.00,
    "delivered_at": "2026-05-02T14:00:05Z"
  },
  "request_id": "abc-123"
}

Airtime

POST /v1/services/airtime Purchase airtime

Purchase airtime for any Nigerian mobile number. Minimum ₦50, maximum ₦50,000 per transaction.

Request Body

FieldTypeDescription
networkrequiredstringmtn · airtel · glo · 9mobile
phonerequiredstringRecipient phone number
amountrequirednumberAmount in NGN. Min: 50. Max: 50000.
pinrequiredstringYour 5-digit transaction PIN
Request
curl -X POST https://api.betavend.com/v1/services/airtime \
  -H "Authorization: Bearer bv_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-airtime-001" \
  -d '{
    "network": "mtn",
    "phone": "08012345678",
    "amount": 500,
    "pin": "12345"
  }'
201 Created
{
  "success": true,
  "message": "Airtime purchased successfully",
  "data": {
    "reference": "BV-20260502-AIRTIME-001",
    "status": "delivered",
    "network": "mtn",
    "phone": "08012345678",
    "amount": 500,
    "wallet_balance_after": 4000.00
  },
  "request_id": "abc-456"
}

Electricity

POST /v1/services/electricity Pay electricity bill

Pay electricity bills for prepaid and postpaid meters across all Nigerian DISCOs. Returns a token for prepaid meters.

Supported DISCOs

EKEDC · IKEDC · AEDC · IBEDC · PHED · KAEDCO · JEDC · KEDCO · BEDC

Request Body

FieldTypeDescription
discorequiredstringDISCO service ID e.g. ikeja-electric
meter_numberrequiredstring11 or 13 digit meter number
meter_typerequiredstringprepaid or postpaid
amountrequirednumberAmount in NGN. Minimum: 500.
pinrequiredstringYour 5-digit transaction PIN
Request
curl -X POST https://api.betavend.com/v1/services/electricity \
  -H "Authorization: Bearer bv_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: elec-pay-001" \
  -d '{
    "disco": "ikeja-electric",
    "meter_number": "12345678901",
    "meter_type": "prepaid",
    "amount": 5000,
    "pin": "12345"
  }'
201 Created
{
  "success": true,
  "data": {
    "reference": "BV-20260502-ELEC-001",
    "status": "delivered",
    "token": "1234-5678-9012-3456-7890",
    "units": "45.23 kWh",
    "meter_number": "12345678901",
    "amount": 5000
  },
  "request_id": "abc-789"
}

Cable TV

POST /v1/services/tv Renew cable TV subscription

Renew cable TV subscriptions for DSTV, GOtv, and StarTimes.

Request Body

FieldTypeDescription
providerrequiredstringdstv · gotv · startimes
smartcard_numberrequiredstringDecoder smartcard / IUC number
package_coderequiredstringSubscription package code
amountrequirednumberAmount in NGN
pinrequiredstringYour 5-digit transaction PIN
Request
curl -X POST https://api.betavend.com/v1/services/tv \
  -H "Authorization: Bearer bv_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: tv-pay-001" \
  -d '{
    "provider": "dstv",
    "smartcard_number": "1234567890",
    "package_code": "DSTV-COMPACT",
    "amount": 15600,
    "pin": "12345"
  }'

Transactions

GET /v1/transactions List all transactions

Returns paginated service order history (airtime, data, electricity, TV). Ordered newest first.

Query Parameters

ParameterTypeDescription
per_pageoptionalintegerDefault: 20. Max: 100.
pageoptionalintegerPage number. Default: 1.
Request
curl "https://api.betavend.com/v1/transactions?per_page=20" \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "data": {
    "transactions": [
      {
        "reference": "BV-20260502-001",
        "service_type": "data",
        "recipient": "08012345678",
        "amount": 550,
        "status": "successful",
        "created_at": "2026-05-02T14:00:00.000000Z"
      }
    ],
    "pagination": {
      "total": 200,
      "per_page": 20,
      "current_page": 1,
      "last_page": 10
    }
  },
  "request_id": "abc-123"
}
GET /v1/transactions/{reference} Get a single transaction

Returns full details for a single transaction by reference number.

Request
curl https://api.betavend.com/v1/transactions/BV-20260502-001 \
  -H "Authorization: Bearer bv_live_your_key"

API Keys

GET /v1/keys List your API keys

Returns all active API keys for your account. Secret values are never returned — only the key ID and metadata.

Request
curl https://api.betavend.com/v1/keys \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "data": {
    "keys": [
      {
        "id": 1,
        "name": "Production Key",
        "environment": "live",
        "last_used_at": "2026-05-02T14:00:00Z",
        "created_at": "2026-05-01T10:00:00Z"
      }
    ]
  },
  "request_id": "abc-123"
}
POST /v1/keys Create a new API key

Creates a new API key. The full key value is returned only in this response — store it immediately. Maximum 5 active keys per account.

Request Body

FieldTypeDescription
namerequiredstringA descriptive name for this key. Max 100 chars.
environmentoptionalstringlive (default) or test
Request
curl -X POST https://api.betavend.com/v1/keys \
  -H "Authorization: Bearer bv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Production Key", "environment": "live"}'
201 Created
{
  "success": true,
  "message": "API key created. Save the key now — it will not be shown again.",
  "data": {
    "id": 2,
    "name": "My Production Key",
    "api_key": "bv_live_abc123...",
    "environment": "live",
    "created_at": "2026-05-02T14:00:00Z"
  },
  "request_id": "abc-123"
}
DELETE /v1/keys/{id} Revoke an API key

Permanently revokes an API key. Any requests using the revoked key will immediately return 401 auth.key_not_found. This action cannot be undone.

Request
curl -X DELETE https://api.betavend.com/v1/keys/2 \
  -H "Authorization: Bearer bv_live_your_key"
200 OK
{
  "success": true,
  "message": "API key revoked successfully.",
  "data": null,
  "request_id": "abc-123"
}