Developer Portal

RapidBills API Reseller Documentation

Authenticate with your API key, fetch balances and catalogs, and process data, airtime, power, cable, exam, and gift card actions from one consistent reseller API.

Base URL https://www.rapidbills.ng/api/reseller/v1
Auth Authorization: Bearer YOUR_API_KEY
Fallback X-API-Key: YOUR_API_KEY
Quick Start

Start With Two Things

Every protected request needs your API key, and every purchase-style POST should include a unique Idempotency-Key so retries never double-charge the same logical action.

Base URL https://www.rapidbills.ng/api/reseller/v1
Authorization Authorization: Bearer YOUR_API_KEY
Alternative Header X-API-Key: YOUR_API_KEY
Retry Safety Idempotency-Key: uuid-v4-value
Common Format

Common Response Shape

Idempotency: send a unique Idempotency-Key header on every POST purchase/reset call.

If the same key is retried with the same payload, the API replays the original response. If payload changes, API returns 409.

{
  "status": "true|false",
  "message": "Human readable message",
  "data": {}
}
Retry Control

Idempotency-Key Guide

Idempotency-Key prevents duplicate charges when clients retry due to timeout or network errors.

  • Generate one key per logical action, such as one purchase click.
  • Reuse the same key only when retrying that exact same request.
  • If payload changes, generate a new key.
  • UUID v4 is recommended.
const idemKey = crypto.randomUUID();
import uuid
idem_key = str(uuid.uuid4())
$idemKey = bin2hex(random_bytes(16));
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Endpoint 1

Get User Balance

GET https://www.rapidbills.ng/api/reseller/v1/user-balance/
Expected Success Response
{
  "status": "true",
  "message": "Balance fetched successfully.",
  "data": {
    "main_balance": "4500.00",
    "cashback_balance": "120.00",
    "funding_accounts": [
      {
        "account_name": "John Doe",
        "account_number": "1234567890",
        "bank_name": "Wema Bank",
        "is_primary": true,
        "active": true
      }
    ]
  }
}
const axios = require("axios");
const API_KEY = "YOUR_API_KEY";
const BASE = "https://www.rapidbills.ng/api/reseller/v1";

const res = await axios.get(`${BASE}/user-balance/`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
console.log(res.data);
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://www.rapidbills.ng/api/reseller/v1"

res = requests.get(
    f"{BASE}/user-balance/",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
print(res.json())
<?php
$apiKey = "YOUR_API_KEY";
$base = "https://www.rapidbills.ng/api/reseller/v1";

$ch = curl_init("$base/user-balance/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
curl --request GET "https://www.rapidbills.ng/api/reseller/v1/user-balance/" \
  --header "Authorization: Bearer YOUR_API_KEY"
Endpoint 2

Buy Data

POST https://www.rapidbills.ng/api/reseller/v1/buy-data/
Request Body
{
  "bundle_id": 1,
  "number": "08012345678",
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Data purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}
await axios.post(`${BASE}/buy-data/`, {
  bundle_id: 1,
  number: "08012345678",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-data/", json={
    "bundle_id": 1,
    "number": "08012345678",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "bundle_id" => 1,
  "number" => "08012345678",
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-data/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bundle_id":1,"number":"08012345678","wallet":"main"}'
Endpoint 3

Buy Airtime

POST https://www.rapidbills.ng/api/reseller/v1/buy-airtime/
Request Body
{
  "provider_id": 1,
  "number": "08012345678",
  "amount": 1000,
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Airtime purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}
await axios.post(`${BASE}/buy-airtime/`, {
  provider_id: 1,
  number: "08012345678",
  amount: 1000,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-airtime/", json={
    "provider_id": 1,
    "number": "08012345678",
    "amount": 1000,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "provider_id" => 1,
  "number" => "08012345678",
  "amount" => 1000,
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-airtime/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"provider_id":1,"number":"08012345678","amount":1000,"wallet":"main"}'
Endpoint 4

Buy Electricity

POST https://www.rapidbills.ng/api/reseller/v1/buy-power/
Request Body
{
  "provider_id": 1,
  "meter_number": "12345678901",
  "meter_type": 1,
  "amount": 2000,
  "phone_number": "08012345678",
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Electricity purchase successful.",
  "tx_ref": "AbCdEfGhIj",
  "token": "1234 5678 9012"
}
await axios.post(`${BASE}/buy-power/`, {
  provider_id: 1,
  meter_number: "12345678901",
  meter_type: 1,
  amount: 2000,
  phone_number: "08012345678",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-power/", json={
    "provider_id": 1,
    "meter_number": "12345678901",
    "meter_type": 1,
    "amount": 2000,
    "phone_number": "08012345678",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "provider_id" => 1,
  "meter_number" => "12345678901",
  "meter_type" => 1,
  "amount" => 2000,
  "phone_number" => "08012345678",
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-power/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"provider_id":1,"meter_number":"12345678901","meter_type":1,"amount":2000,"phone_number":"08012345678","wallet":"main"}'
Endpoint 5

Buy Cable

POST https://www.rapidbills.ng/api/reseller/v1/buy-cable/
Request Body
{
  "plan_id": 1,
  "card_number": "12345678901",
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Cable purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}
await axios.post(`${BASE}/buy-cable/`, {
  plan_id: 1,
  card_number: "12345678901",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-cable/", json={
    "plan_id": 1,
    "card_number": "12345678901",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "plan_id" => 1,
  "card_number" => "12345678901",
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-cable/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"plan_id":1,"card_number":"12345678901","wallet":"main"}'
Endpoint 6

Buy Exam Pin

POST https://www.rapidbills.ng/api/reseller/v1/buy-exam/
Request Body
{
  "exam_id": 1,
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Exam purchase successful.",
  "tx_ref": "AbCdEfGhIj",
  "pins": ["123456789012"]
}
await axios.post(`${BASE}/buy-exam/`, {
  exam_id: 1,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-exam/", json={
    "exam_id": 1,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "exam_id" => 1,
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-exam/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"exam_id":1,"wallet":"main"}'
Endpoint 7

Utility Endpoints

  • GET https://www.rapidbills.ng/api/reseller/v1/catalog/ - RapidBills product IDs for providers, bundles, cable plans, and exams.
  • GET https://www.rapidbills.ng/api/reseller/v1/pricing/ - RapidBills product IDs and visible tier pricing.
  • GET https://www.rapidbills.ng/api/reseller/v1/user-balance/ - main balance, cashback, and funding account numbers.
  • GET https://www.rapidbills.ng/api/reseller/v1/profile/ - current API profile + key prefix metadata.
  • POST https://www.rapidbills.ng/api/reseller/v1/reset-key/ - rotate API key and return new key once.
Endpoint 8

Buy Gift Card

POST https://www.rapidbills.ng/api/reseller/v1/buy-gift-card/
Request Body
{
  "amount": 1000,
  "wallet": "main"
}
Expected Success Response
{
  "status": "true",
  "message": "Gift card purchased successfully.",
  "data": {
    "code": "AB12CD34EF",
    "amount": "1000.00",
    "status": "valid",
    "expires_at": "2027-03-01T12:00:00Z"
  }
}
await axios.post(`${BASE}/buy-gift-card/`, {
  amount: 1000,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/buy-gift-card/", json={
    "amount": 1000,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "amount" => 1000,
  "wallet" => "main"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-gift-card/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"amount":1000,"wallet":"main"}'
Endpoint 9

Redeem Gift Card

POST https://www.rapidbills.ng/api/reseller/v1/redeem-gift-card/
Request Body
{
  "code": "AB12CD34EF"
}
Expected Success Response
{
  "status": "true",
  "message": "Gift card redeemed successfully.",
  "data": {
    "code": "AB12CD34EF",
    "amount": "1000.00",
    "status": "used"
  }
}
await axios.post(`${BASE}/redeem-gift-card/`, {
  code: "AB12CD34EF"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });
requests.post(f"{BASE}/redeem-gift-card/", json={
    "code": "AB12CD34EF"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
$payload = json_encode([
  "code" => "AB12CD34EF"
]);
curl --request POST "https://www.rapidbills.ng/api/reseller/v1/redeem-gift-card/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"code":"AB12CD34EF"}'
OpenAPI JSON OpenAPI YAML Join Reseller WhatsApp Group for Instant Updates

Frequently Asked Questions

How do I get a RapidBills reseller API key?
Create a RapidBills account, request API-tier access, then open the API credentials page to generate or rotate your API key.
Which authentication header should I use?
Use Authorization: Bearer YOUR_API_KEY. RapidBills also accepts X-API-Key as a fallback.
How does the Idempotency-Key header prevent duplicate charges?
Use one unique Idempotency-Key for each logical purchase. Retrying the same request with the same key replays the original result instead of charging again.
Which services are available through the RapidBills reseller API?
The API supports catalog and pricing access, balance checks, airtime, data, electricity, cable, exam pins, and RapidBills gift card actions.
What happens when an API purchase fails?
Purchase endpoints return a structured error response. Where a wallet debit occurred and the provider failed, the purchase flow handles refund behavior.