Sell data and airtime from your own app.

Quickstart

Base URL — every path ends in a slash:

https://billbytes.ng/api/v1/

Check you can reach us — no key needed:

# 1. are we up?curl https://billbytes.ng/api/v1/ping/ # 2. what can I sell?curl https://billbytes.ng/api/v1/bundles/?network=MTN \-H "Authorization: Bearer bb_live_your_key" # 3. sell somethingcurl -X POST https://billbytes.ng/api/v1/bundles/purchase/ \-H "Authorization: Bearer bb_live_your_key" \-H "Content-Type: application/json" \-H "Idempotency-Key: $(uuidgen)" \-d '{"plan_id": 173, "phone": "08031234567"}'

Need a key? Email support@billbytes.ng with your business name and what you are building. Test keys are issued the same day; live keys after a short review.

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer bb_live_9f3c1a2b4d5e6f708192a3b4c5d6e7f8a9b0c1d2

Keys look like bb_live_… in production and bb_test_… in the sandbox. We store only a hash of your key, so we cannot recover it for you — if you lose it, we rotate it and the old one is revoked.

Wallet & pricing

The API is prepaid. Every purchase debits your wallet; a rejected order is refunded automatically. Top up by bank transfer to your Billbytes account and support credits the wallet against your transfer reference.

The price returned by GET /api/v1/bundles/ is exactly what your wallet is debited — quote it to your own customers and keep the difference. Prices move when the networks move theirs, so read the catalogue rather than hard-coding it.

Sample live prices

Read live from the catalogue at 3 Nov 2026, 16:17 WAT.

Catalogue coverage

Idempotency

Every purchase requires an Idempotency-Key header. Any unique string works — a UUID is ideal. It is the difference between a safe retry and a double charge.

If your request times out you genuinely do not know whether the bundle was delivered. Retry with the same key and you get the original result back, marked "replayed": true. No second purchase, no second debit.

// first attempt — connection drops, you never see a response
POST /api/v1/bundles/purchase/   Idempotency-Key: 8f14e45f-ea2b

// safe retry, same key
POST /api/v1/bundles/purchase/   Idempotency-Key: 8f14e45f-ea2b

{
  "status": true,
  "transaction": {
    "reference": "bb_tx_6a7b5ffa48948afd1431",
    "status": "success",
    "replayed": true
  }
}

Order lifecycle

Sandbox

A bb_test_ key never reaches the network and never touches your wallet. Everything else is real: the same endpoints, the same validation, the same ledger entries and the same webhooks, so a sandbox order records a debit and a refund exactly as a live one does — against the key's own journal rather than your balance. You can leave a sandbox loop running on an empty wallet.

The outcome is chosen by the recipient number, so you can exercise every branch without spending anything:

Endpoints

Liveness and whether purchases are currently enabled.

Supported networks and how many data plans each currently has.

The full sellable data catalogue. Optional ?network=MTN|AIRTEL|GLO|9MOBILE.

{
  "status": true,
  "count": 89,
  "bundles": [
    {
      "plan_id": 173,
      "network": "MTN",
      "name": "1GB Share",
      "label": "1GB Share · 30 days",   // ready to drop in a <select>
      "volume": "1GB",
      "validity": "30 days",
      "type": "Share",
      "price": 578,
      "currency": "NGN"
    }
  ]
}

plan_id is ours and stable. Pass it straight to the purchase endpoint.

Buy a data bundle. Requires Idempotency-Key.

{
  "status": true,
  "transaction": {
    "reference": "bb_tx_6a7b5ffa48948afd1431",
    "status": "success",
    "service": "data",
    "network": "MTN",
    "phone": "08031234567",
    "amount": 578,
    "plan": "1GB Share",
    "completed_at": "2026-07-30T10:18:18+01:00"
  },
  "request_id": "req_341b85b47355ec3cdba007f3"
}

Buy airtime. Requires Idempotency-Key.

Wallet balance and the limits on your key.

{
  "status": true,
  "balance": 2000,
  "currency": "NGN",
  "limits": {
    "requests_per_minute": 60,
    "daily_spend_cap": 200000,
    "spent_today": 853
  }
}

One order by reference, or your recent history.

The reference is a query parameter, not a path segment — /transactions/?reference=bb_tx_…

Webhooks

Give support an HTTPS endpoint and we will POST to it when an order settles. Events: transaction.success, transaction.failed, transaction.refunded. The body is the same transaction object the API returns.

Verifying a delivery

Each delivery carries a timestamp and an HMAC-SHA256 signature over "<timestamp>.<raw body>", keyed with your webhook secret:

X-Billbytes-Event: transaction.success
X-Billbytes-Timestamp: 1753876800
X-Billbytes-Signature: sha256=4f2c…

// PHP — verify before trusting anything in the body
$raw       = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_BILLBYTES_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_BILLBYTES_SIGNATURE'] ?? '';

// reject replays of an old, validly-signed delivery
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(400); exit;
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $raw, $yourWebhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401); exit;
}

http_response_code(200); // ack quickly, then process

Errors

Failures are always shaped the same way, with a stable machine-readable code. Branch on the code, not the message — messages get reworded.

{
  "status": false,
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient API wallet balance. This purchase costs NGN 578.00, your balance is NGN 120.00.",
    "details": { "required": 578, "balance": 120 }
  },
  "request_id": "req_341b85b47355ec3cdba007f3"
}

Rate limits

Default 60 requests per minute per key; every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Need more throughput? Ask — the limit is per key and we can raise it.

Machine-readable index: /api/v1/