๐ฎ Betting API
Fund betting wallets for major Nigerian betting platforms instantly. Supports Bet9ja, BetKing, NairaBet, 1xBet, BetWay and more. Always verify the customer account before charging to avoid funding the wrong betting wallet.
๐ Quick Overview
13 Platforms
All major supported Nigerian betting platforms in one endpoint
Verify First
Confirm customer name before any wallet deduction
โฆ100 โ โฆ100,000
Flexible funding amount per transaction
Webhook Updates
Track final status reliably with transaction webhooks
๐ฐ Commission & Charges
| Field | Meaning | Example |
|---|---|---|
amount |
The full amount the betting account will receive | โฆ1,000 |
discount |
Your savings / commission on the transaction | โฆ15.00 |
amount_charged |
The actual amount deducted from your wallet | โฆ985.00 |
| Betting account credited | The user still receives the full requested funding amount | โฆ1,000 |
๐ How It Works
Verify Account
Call POST /devapi/v1/verify-customer
with the betting account ID and betting platform.
The API checks if the account exists and returns the account holder name.
No wallet charge happens in this step.
Confirm With User
Show the returned customer name to the user before charging. Example: โFund Bet9ja for John Doe โ โฆ1,000?โ This helps prevent wrong-account funding.
Fund Betting Wallet
After the user confirms, call
POST /devapi/v1/betting
with a unique request_id, account ID, platform and amount.
Track Final Status
Listen for webhook event
transaction.status_changed.
If status is completed-api, the funding succeeded.
If status is refunded-api, the wallet has been restored.
processing
until your webhook confirms the final result.
๐ฏ Supported Betting Platforms
| Platform | service_id | Also Accepted As |
|---|---|---|
| 1xBet | 1xBet | 1xbet |
| BangBet | BangBet | bangbet |
| Bet9ja | Bet9ja | bet9ja |
| BetKing | BetKing | betking |
| BetLand | BetLand | betland |
| BetLion | BetLion | betlion |
| BetWay | BetWay | betway |
| CloudBet | CloudBet | cloudbet |
| LiveScoreBet | LiveScoreBet | livescorebet |
| MerryBet | MerryBet | merrybet |
| NaijaBet | NaijaBet | naijabet |
| NairaBet | NairaBet | nairabet |
| SupaBet | SupaBet | supabet |
Bet9ja, bet9ja
and BET9JA are treated the same.
๐๏ธ All Endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /devapi/v1/verify-customer |
Required | Verify betting account and return customer name |
| POST | /devapi/v1/betting |
Required | Fund betting account after verification / confirmation |
๐ Step 1 โ POST /verify-customer
Verify a betting account before funding it. This confirms the account exists on the selected platform and returns the customer name. No wallet charge is made during verification.
Request Body
| Field | Type | Required | Accepted Aliases | Description |
|---|---|---|---|---|
customer_id |
string | Yes | account_id, user_id | The betting account ID or username from the user's betting app profile |
service_id |
string | Yes | provider, platform | The betting platform to verify against |
curl -X POST "https://iacafe.com.ng/devapi/v1/verify-customer" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "12345678",
"service_id": "Bet9ja"
}'
{
"success": true,
"code": "success",
"message": "Bet9ja customer verified",
"service_type": "betting",
"service_id": "Bet9ja",
"service_name": "Bet9ja",
"data": {
"customer_id": "12345678",
"customer_name": "John Doe",
"customer_address": null,
"customer_phone": null,
"extra": {}
}
}
{
"success": false,
"error": {
"code": "customer_not_found",
"message": "Betting account ID not found. Please check and retry."
},
"customer_id": "12345678",
"service_id": "Bet9ja",
"hint": "Double-check your betting account ID. It is usually found in your betting app profile."
}
customer_not_found,
stop there and ask the user to check the account ID in their betting app.
๐ธ Step 2 โ POST /betting
Fund a betting account after successful verification and user confirmation.
Use a unique request_id for every transaction.
Request Body
| Field | Type | Required | Aliases | Description |
|---|---|---|---|---|
request_id |
string | Yes | requestId, ref | Your unique transaction reference. Maximum 50 characters. Must not be reused. |
customer_id |
string | Yes | customerId, user_id, account_id, betting_id | The betting account ID or username to fund. Minimum 3 characters. |
service_id |
string | Yes | serviceId, provider, platform | The betting platform to fund |
amount |
number | Yes | amt | Funding amount in Naira. Minimum โฆ100, maximum โฆ100,000. |
skip_verify |
boolean | Optional | โ | Set to true only if you already verified separately. Not recommended for normal use. |
request_id:
This must be unique per transaction.
If you reuse an old value, the API will return
409 duplicate_transaction
and the new request will not be processed.
curl -X POST "https://iacafe.com.ng/devapi/v1/betting" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "bet_20240101_abc123",
"customer_id": "12345678",
"service_id": "Bet9ja",
"amount": 1000
}'
const response = await fetch('https://iacafe.com.ng/devapi/v1/betting', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
request_id: 'bet_20240101_abc123',
customer_id: '12345678',
service_id: 'Bet9ja',
amount: 1000
})
});
const data = await response.json();
console.log(data);
{
"success": true,
"status": "completed",
"message": "ORDER COMPLETED",
"data": {
"order_id": 12349,
"customer_id": "12345678",
"customer_name": "John Doe",
"betting_platform": "Bet9ja",
"amount": 1000,
"amount_charged": "985.00",
"discount": "15.00",
"initial_balance": "5000.00",
"final_balance": "4015.00",
"request_id": "bet_20240101_abc123"
}
}
{
"success": true,
"status": "processing",
"message": "Transaction is being processed",
"data": {
"order_id": 12349,
"customer_id": "12345678",
"betting_platform": "Bet9ja",
"amount": 1000,
"amount_charged": "985.00",
"request_id": "bet_20240101_abc123",
"note": "You will be notified via webhook once confirmed. Do NOT retry."
}
}
{
"success": false,
"error": {
"code": "provider_failed",
"message": "Provider declined the transaction"
},
"order_id": 12349,
"request_id": "bet_20240101_abc123",
"refunded": true,
"hint": "Check your betting account ID and try again"
}
๐ Webhook Events
Betting transactions emit the same webhook events as other IA-Cafรฉ services. Webhooks are the most reliable way to track the final outcome.
transaction.created
{
"event": "transaction.created",
"order_id": 12349,
"request_id": "bet_20240101_abc123",
"category": "betting",
"service_id": "Bet9ja",
"product_name": "Betting",
"customer_id": "12345678",
"amount": 1000,
"amount_charged": 985,
"discount": 15,
"balance_before": 5000,
"balance_after": 4015,
"timestamp": "2024-01-01T00:00:00.000Z"
}
transaction.status_changed
| Status | Meaning | Wallet |
|---|---|---|
processing-api |
Transaction submitted and awaiting provider confirmation | โณ Held |
completed-api |
Betting account funded successfully | โ Deducted |
refunded-api |
Funding failed and wallet has been restored | โฉ๏ธ Restored |
{
"event": "transaction.status_changed",
"order_id": 12349,
"request_id": "bet_20240101_abc123",
"status": "completed-api",
"category": "betting",
"service_id": "Bet9ja",
"customer_id": "12345678",
"amount": 1000,
"amount_charged": 985,
"discount": 15,
"provider": "vtu",
"timestamp": "2024-01-01T00:00:05.000Z"
}
{
"event": "transaction.status_changed",
"order_id": 12349,
"request_id": "bet_20240101_abc123",
"status": "refunded-api",
"category": "betting",
"service_id": "Bet9ja",
"customer_id": "12345678",
"amount": 1000,
"amount_charged": 985,
"refund_reason": "provider_failed",
"refunded_amount": 985,
"balance_before_refund": 4015,
"balance_after_refund": 5000,
"timestamp": "2024-01-01T00:00:08.000Z"
}
โ ๏ธ Error Codes & What They Mean
processing while final confirmation is being checked.
Do not retry while it is pending.
๐ด Validation Errors (Your Request)
| HTTP | error.code | What it means | How to fix |
|---|---|---|---|
400 | missing_fields | Required field(s) not sent | Check request body and include all required fields |
400 | invalid_service_id | Platform not recognised | Use one of the supported betting platform IDs |
400 | invalid_amount | Amount is not a valid positive number | Send a numeric value such as 1000 |
400 | below_minimum_amount | Amount is less than โฆ100 | Use at least โฆ100 |
400 | above_maximum_amount | Amount exceeds โฆ100,000 | Use โฆ100,000 or less |
400 | invalid_customer_id | Betting account ID is too short | Use a valid account ID or username with at least 3 characters |
404 | customer_not_found | Account does not exist on that platform | Ask the user to check their account ID in the betting app |
409 | duplicate_transaction | request_id already used | Generate a new unique request ID |
๐ Provider / Transaction Outcome Errors
| HTTP | error.code | What it means | What to do |
|---|---|---|---|
202 | provider_timeout | Provider response is unclear and transaction is being verified | Do not retry. Wait for the webhook result. |
422 | provider_failed | Provider clearly declined the transaction | Wallet is refunded. Ask user to check details and retry if needed. |
503 | provider_unavailable | Provider is not configured or unavailable | Try later or contact IA-Cafรฉ support |
๐ Authentication & Server Errors
| HTTP | error.code | What it means | How to fix |
|---|---|---|---|
401 | unauthorized | Missing or invalid API key | Add Authorization: Bearer YOUR_API_KEY header |
402 | insufficient_balance | Not enough wallet balance | Top up your IA-Cafรฉ wallet first |
500 | server_error | Unexpected internal error | Retry once. If it persists, contact support with your request_id |
Error Response Format
{
"success": false,
"error": {
"code": "provider_failed",
"message": "Provider declined the transaction"
},
"order_id": 12349,
"request_id": "bet_20240101_abc123",
"refunded": true
}
๐ Important Notes
processing or
provider_timeout, the transaction is still being checked.
Do not retry while waiting for the webhook result.
request_id.
Reusing an old request ID returns duplicate_transaction
and prevents accidental double funding.
๐จ Complete Flow Example (JavaScript)
const BASE = 'https://iacafe.com.ng/devapi/v1';
const API_KEY = 'YOUR_API_KEY';
async function post(path, body) {
const res = await fetch(`${BASE}${path}`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
});
return res.json();
}
async function verifyBettingAccount(customerId, platform) {
return post('/verify-customer', {
customer_id: customerId,
service_id: platform
});
}
async function fundBettingAccount(requestId, customerId, platform, amount) {
return post('/betting', {
request_id: requestId,
customer_id: customerId,
service_id: platform,
amount
});
}
async function main() {
const customerId = '12345678';
const platform = 'Bet9ja';
const amount = 1000;
// Step 1: Verify account
const verify = await verifyBettingAccount(customerId, platform);
if (!verify.success) {
console.error(`โ ${verify.error.code}: ${verify.error.message}`);
return;
}
const customerName = verify.data.customer_name;
console.log(`โ
Verified account name: ${customerName}`);
console.log(`Show user: Fund ${platform} for ${customerName} โ โฆ${amount}?`);
// Step 2: After user confirms, fund the betting wallet
const requestId = `bet_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
const result = await fundBettingAccount(requestId, customerId, platform, amount);
if (result.success && result.status === 'completed') {
const d = result.data;
console.log(`โ
Funding successful for ${d.customer_name}`);
console.log(`Amount funded: โฆ${d.amount}`);
console.log(`Wallet charged: โฆ${d.amount_charged}`);
console.log(`Discount: โฆ${d.discount}`);
console.log(`Balance: โฆ${d.initial_balance} โ โฆ${d.final_balance}`);
} else if (result.success && result.status === 'processing') {
console.log('โณ Transaction is processing. Do NOT retry. Wait for webhook confirmation.');
} else {
console.error(`โ ${result.error.code}: ${result.error.message}`);
if (result.refunded) {
console.log('โฉ๏ธ Wallet has been refunded');
}
}
}
main();
๐ Complete Flow Example (PHP)
<?php
define('BASE', 'https://iacafe.com.ng/devapi/v1');
define('API_KEY', 'YOUR_API_KEY');
function apiPost($path, $body) {
$ch = curl_init(BASE . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($body),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . API_KEY,
'Content-Type: application/json'
]
]);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}
// Step 1: Verify account
$verify = apiPost('/verify-customer', [
'customer_id' => '12345678',
'service_id' => 'Bet9ja'
]);
if (!$verify['success']) {
echo "โ {$verify['error']['code']}: {$verify['error']['message']}\n";
exit;
}
echo "โ
Verified customer: {$verify['data']['customer_name']}\n";
// Show user confirmation here before continuing
// Step 2: Fund account
$requestId = 'bet_' . time();
$result = apiPost('/betting', [
'request_id' => $requestId,
'customer_id' => '12345678',
'service_id' => 'Bet9ja',
'amount' => 1000
]);
if (!empty($result['success']) && ($result['status'] ?? '') === 'completed') {
$d = $result['data'];
echo "โ
Funded successfully for {$d['customer_name']}\n";
echo "Amount funded: โฆ{$d['amount']}\n";
echo "Wallet charged: โฆ{$d['amount_charged']}\n";
echo "Balance: โฆ{$d['initial_balance']} โ โฆ{$d['final_balance']}\n";
} elseif (!empty($result['success']) && ($result['status'] ?? '') === 'processing') {
echo "โณ Processing. Do NOT retry. Wait for webhook confirmation.\n";
} else {
echo "โ {$result['error']['code']}: {$result['error']['message']}\n";
if (!empty($result['refunded'])) {
echo "โฉ๏ธ Wallet refunded\n";
}
}
?>