Core VAS
Bill Payments & Digital VAS
Disburse Airtime, Internet Data bundles, Electricity meter tokens, Cable TV subscriptions, and Education exam registration PINs (WAEC, JAMB, NECO) with sub-second fulfillment.
Architecture & Integration Guidelines:
- Workflow: 1. Get Categories -> 2. Get Billers -> 3. Fetch Packages -> 4. Verify Customer -> 5. Purchase with PIN & Idempotency Key.
- Automated Refunds: If a transaction fails, the system automatically rolls back and refunds your wallet immediately.
- Tokens & PINs: Electricity prepaid tokens and WAEC/JAMB PINs are returned immediately in the purchase response.
POST
/api/v1/services/purchase5. Purchase Bill / Airtime / Data / PINs
Atomically debit wallet, disburse service, and receive tokens/PINs immediately with channel tracking.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Request Body
{
"category_slug": "electricity",
"biller_slug": "ikeja-electric",
"customer_id": "1111111111111",
"amount": 1000,
"transaction_pin": "1234",
"idempotency_key": "idem_order_8839102"
}Code Execution Playground
Request Snippet (CURL)
curl -X POST "https://backend.cbivas.com/api/v1/services/purchase" \
-H "Authorization: Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "X-Channel: api" \
-d '{"category_slug":"electricity","biller_slug":"ikeja-electric","customer_id":"1111111111111","amount":1000.00,"transaction_pin":"1234","idempotency_key":"idem_order_8839102"}'Success Response (200 OK)
{
"id": "3f4ec47e-8570-4abb-9d10-8b1e0a293810",
"reference": "BP-3F4EC47E85704ABB",
"category": "Electricity Bill",
"biller": "Ikeja Electric Payment - IKEDC",
"customer_id": "1111111111111",
"customer_name": "OBAFEMI AWOLOWO",
"amount": "1000.00",
"status": "completed",
"token": "Token : 26362054405982757802 | Units: 14.8 kWh",
"channel": "api",
"created_at": "2026-08-25T14:20:07.192341Z"
}Potential Error Responses
HTTP 400Invalid PIN / Insufficient Balance
{
"detail": "Invalid Transaction PIN."
}HTTP 409Concurrent Duplicate Request
{
"detail": "A payment is already being processed for this request. Please wait."
}