Public integration documentation

BillXpress Vendor API Documentation

Integrate wallet-funded airtime, data, cable TV, and electricity services into external apps using one vendor API key and predictable JSON responses.

Production Base URL
https://api.billxpress.co
Vendor Prefix
/api/v1/vendor
Authentication
Authorization: YOUR_VENDOR_API_KEY

Overview

The Vendor API is designed for approved BillXpress vendors who want to resell services from their own website, mobile app, agent system, or backend.

Vendor requests are authenticated with a vendor API key. The API uses the vendor wallet balance, applies vendor pricing, records transactions, and returns references that vendors can store in their own system.

This page documents the public vendor-facing API contract. These routes live under /api/v1/vendor and do not require customer JWT tokens or transaction PINs.
Airtime Data Cable TV Electricity Wallet Transactions

Quickstart

1
Get approved
Create a BillXpress account and request vendor approval from an admin.
2
Receive API key
After approval, the admin dashboard returns a unique vendor API key.
3
Fund wallet
Keep enough balance in the vendor wallet before placing orders.
4
Start requests
Send your API key in the Authorization header and store every reference.
Minimal Request 
curl -X GET "https://api.billxpress.co/api/v1/vendor/me" \
  -H "Authorization: YOUR_VENDOR_API_KEY"

Authentication

Send the vendor API key directly in the Authorization header. Do not prefix vendor keys with Bearer.

Correct 
Authorization: bxp_vendor_live_xxxxxxxxxxxxx
Incorrect 
Authorization: Bearer bxp_vendor_live_xxxxxxxxxxxxx

Authentication Rules

Rule Requirement
Account role The account must have role: "vendor".
Vendor status The account must have isVendorActive: true.
Header Use Authorization: YOUR_VENDOR_API_KEY.
Secret handling Keep API keys on backend servers only. Do not expose them in browser JavaScript or mobile app bundles.

Response Format

Public responses should use one predictable envelope so vendors can integrate once and handle all services consistently.

Success 
{
  "success": true,
  "message": "Request completed successfully",
  "data": {}
}
Error 
{
  "success": false,
  "message": "Insufficient wallet balance",
  "code": "INSUFFICIENT_BALANCE"
}

Account

GET /api/v1/vendor/me
Vendor API key required

Returns the authenticated vendor profile, active status, and wallet summary.

Response 
{
  "success": true,
  "message": "Vendor profile fetched successfully",
  "data": {
    "vendor": {
      "id": "665f...",
      "businessName": "Example Vendor",
      "email": "vendor@example.com",
      "role": "vendor",
      "isVendorActive": true,
      "vendorApprovedAt": "2026-06-11T10:00:00.000Z"
    },
    "wallet": {
      "currency": "NGN",
      "mainBalance": 25000
    }
  }
}

Wallet

GET /api/v1/vendor/wallet
Read balance

Returns the vendor wallet balance. Purchases are debited from this wallet.

GET /api/v1/vendor/transactions?limit=50
Transaction history

Returns recent transactions for the vendor account. Use this for reconciliation and customer support.

Query Type Description
limit number Optional. Maximum number of transactions to return. Recommended max is 100.
service string Optional. Filter by airtime, data, cable_tv, or electricity.
status string Optional. Filter by successful, failed, or reversed.

Data

GET /api/v1/vendor/data/plans
Live plans

Returns available data plans with vendor pricing already applied. Use the returned id or planId when purchasing.

Query Type Description
network string Optional. Filter plans by network, for example MTN, Airtel, Glo, or 9mobile.
dataType string Optional. Filter by plan type when available.
isHot boolean Optional. Send true to return plans marked as hot.
category string Optional. Send hot as another way to fetch hot plans.
Plan names, validity, type, and notes are customer-facing display fields. Purchase requests still use the returned plan identifier.
POST /api/v1/vendor/data/purchase
Debits wallet

Purchases a data plan for a customer phone number.

Request Body

JSON 
{
  "planId": "MTN_1GB_30DAYS",
  "phone": "08012345678",
  "customerReference": "vendor-data-0001"
}

Success Response

JSON 
{
  "success": true,
  "message": "Data purchase successful",
  "data": {
    "reference": "DATA_LX9K...",
    "customerReference": "vendor-data-0001",
    "status": "successful",
    "service": "data",
    "amount": 1500,
    "phone": "08012345678"
  }
}
GET /api/v1/vendor/data/purchase/:reference
Lookup

Checks a data purchase by BillXpress transaction reference or vendor customerReference.

Airtime

GET /api/v1/vendor/airtime/networks
Network list

Returns supported airtime networks and current vendor pricing rules.

POST /api/v1/vendor/airtime/quote
Price preview
Request 
{
  "amount": 500
}
POST /api/v1/vendor/airtime/purchase
Debits wallet

Request Body

JSON 
{
  "network": "MTN",
  "phone": "08012345678",
  "amount": 500,
  "customerReference": "vendor-airtime-0001"
}

Success Response

JSON 
{
  "success": true,
  "message": "Airtime purchase successful",
  "data": {
    "reference": "AIRTIME_LX9K...",
    "customerReference": "vendor-airtime-0001",
    "status": "successful",
    "service": "airtime",
    "amount": 500,
    "phone": "08012345678",
    "network": "MTN"
  }
}
GET /api/v1/vendor/airtime/purchase/:reference
Lookup

Checks an airtime purchase by BillXpress transaction reference, provider reference, or vendor customerReference.

Cable TV

GET /api/v1/vendor/cable-tv/providers
Provider list

Returns supported cable TV providers and current vendor pricing rules.

GET /api/v1/vendor/cable-tv/packages?provider=DSTV
Package list

Returns available packages for a cable provider. Send provider or tvProvider as the query parameter.

POST /api/v1/vendor/cable-tv/verify-smartcard
Customer check
Request 
{
  "provider": "DSTV",
  "smartcardNumber": "1234567890"
}
POST /api/v1/vendor/cable-tv/quote
Price preview
Request 
{
  "provider": "DSTV",
  "packageCode": "dstv-padi"
}
POST /api/v1/vendor/cable-tv/purchase
Debits wallet

Request Body

JSON 
{
  "provider": "DSTV",
  "smartcardNumber": "1234567890",
  "packageCode": "dstv-padi",
  "phone": "08012345678",
  "subscriptionType": "change",
  "customerReference": "vendor-cable-0001"
}

Success Response

JSON 
{
  "success": true,
  "message": "Cable TV purchase successful",
  "data": {
    "reference": "CABLE_LX9K...",
    "customerReference": "vendor-cable-0001",
    "status": "successful",
    "service": "cable_tv",
    "amount": 2950,
    "smartcardNumber": "1234567890"
  }
}
GET /api/v1/vendor/cable-tv/purchase/:reference
Lookup

Checks a cable TV purchase by BillXpress transaction reference, provider reference, or vendor customerReference.

Electricity

GET /api/v1/vendor/electricity/discos
Disco list

Returns supported electricity distribution companies, meter types, and current vendor pricing rules.

POST /api/v1/vendor/electricity/verify-meter
Meter check
Request 
{
  "disco": "IKEDC",
  "meterNumber": "12345678901",
  "meterType": "prepaid"
}
POST /api/v1/vendor/electricity/quote
Price preview
Request 
{
  "amount": 5000
}
POST /api/v1/vendor/electricity/purchase
Debits wallet

Request Body

JSON 
{
  "disco": "IKEDC",
  "meterNumber": "12345678901",
  "meterType": "prepaid",
  "phone": "08012345678",
  "amount": 5000,
  "customerReference": "vendor-electricity-0001"
}

Success Response

JSON 
{
  "success": true,
  "message": "Electricity purchase successful",
  "data": {
    "reference": "ELEC_LX9K...",
    "customerReference": "vendor-electricity-0001",
    "status": "successful",
    "service": "electricity",
    "amount": 5000,
    "token": "1234-5678-9012",
    "units": "62.4"
  }
}
GET /api/v1/vendor/electricity/purchase/:reference
Lookup

Checks an electricity purchase by BillXpress transaction reference, provider reference, or vendor customerReference.

References And Idempotency

Vendors should send a unique customerReference for every purchase. BillXpress should store it in transaction metadata and prevent duplicate charges for repeated requests with the same reference.

Reference Generated By Purpose
reference BillXpress Official transaction reference for wallet debit and support.
customerReference Vendor Vendor's own order ID for reconciliation and duplicate protection.
providerReference Provider External provider ID returned when the upstream provider supplies one.

Rate Limits

Vendor API traffic is rate limited to protect service reliability. The current limit is 120 requests per minute per endpoint/IP.

Rate Limit Response 
{
  "success": false,
  "message": "Too many vendor API requests, please try again shortly",
  "code": "RATE_LIMITED",
  "retryAfterSeconds": 30
}

Error Codes

HTTP Code Meaning
401 INVALID_API_KEY The vendor API key is missing, invalid, inactive, or belongs to a non-vendor account.
400 VALIDATION_ERROR A required field is missing or invalid.
400 INSUFFICIENT_BALANCE The vendor wallet balance is too low for the requested purchase.
409 DUPLICATE_REFERENCE The customerReference has already been used for this vendor.
503 SERVICE_UNAVAILABLE The selected service or provider is temporarily unavailable.
429 RATE_LIMITED The vendor made too many requests in a short period. Wait for retryAfterSeconds.

Security Guidelines

Treat every vendor API key like a password. A leaked key can spend the vendor's wallet balance.
Do Do Not
Store the API key in backend environment variables. Do not put the API key inside frontend JavaScript.
Use HTTPS for all requests. Do not send API requests over plain HTTP in production.
Send a unique customerReference for every purchase. Do not retry purchase requests without idempotency protection.
Log BillXpress references for support and reconciliation. Do not expose provider raw responses to end customers.