← Home
Choplife Developer API
Sell airtime, data, electricity, TV and exam PINs from your own app with one simple API.
Quick start
- Sign in to Choplife and open Developers.
- Create a test key. It is shown once, so save it on your server. Never put a key in a website or mobile app.
- Try any request in the portal's API console, or run one of these examples. Each reads your balance and places a free test order.
PHP
<?php
// Run: CHOPLIFE_KEY=cl_test_... php quickstart.php
$base = getenv('CHOPLIFE_URL') ?: 'https://choplife.co';
function choplife(string $method, string $path, ?array $body = null, array $headers = []): array
{
global $base;
$curl = curl_init("{$base}/api/developer/v1{$path}");
curl_setopt_array($curl, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('CHOPLIFE_KEY'), 'Accept: application/json', 'Content-Type: application/json', ...$headers],
CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
]);
$answer = json_decode((string) curl_exec($curl), true);
if (isset($answer['error']) || ! isset($answer['data'])) {
throw new RuntimeException($answer['error']['code'] ?? 'network_error');
}
return $answer['data'];
}
$balance = choplife('GET', '/balance');
echo "Balance: {$balance['balance']} kobo\n";
// Save this key with your own order, and reuse it if you retry.
$reference = 'demo-'.bin2hex(random_bytes(8));
$order = choplife('POST', '/orders', ['product' => 'mtn-airtime', 'amount' => 10000, 'recipient' => '08031234567'], ["Idempotency-Key: {$reference}"]);
echo "Order {$order['id']}: {$order['status']}\n";
Node.js
// Run: CHOPLIFE_KEY=cl_test_... node quickstart.mjs (Node 18+)
import { randomBytes } from 'node:crypto';
const base = process.env.CHOPLIFE_URL || 'https://choplife.co';
async function choplife(method, path, body, headers = {}) {
const response = await fetch(`${base}/api/developer/v1${path}`, {
method,
signal: AbortSignal.timeout(60_000),
headers: { Authorization: `Bearer ${process.env.CHOPLIFE_KEY}`, Accept: 'application/json', 'Content-Type': 'application/json', ...headers },
body: body ? JSON.stringify(body) : undefined,
});
const answer = await response.json();
if (answer.error || !answer.data) {
throw new Error(answer.error?.code ?? 'network_error');
}
return answer.data;
}
const balance = await choplife('GET', '/balance');
console.log(`Balance: ${balance.balance} kobo`);
// Save this key with your own order, and reuse it if you retry.
const reference = `demo-${randomBytes(8).toString('hex')}`;
const order = await choplife('POST', '/orders', { product: 'mtn-airtime', amount: 10000, recipient: '08031234567' }, { 'Idempotency-Key': reference });
console.log(`Order ${order.id}: ${order.status}`);
Python
# Run: CHOPLIFE_KEY=cl_test_... python3 quickstart.py
import json
import os
import secrets
import urllib.error
import urllib.request
BASE = os.environ.get("CHOPLIFE_URL") or "https://choplife.co"
def choplife(method, path, body=None, headers=None):
request = urllib.request.Request(
f"{BASE}/api/developer/v1{path}",
method=method,
data=json.dumps(body).encode() if body else None,
headers={"Authorization": f"Bearer {os.environ['CHOPLIFE_KEY']}", "Accept": "application/json", "Content-Type": "application/json", "User-Agent": "choplife-example", **(headers or {})},
)
try:
with urllib.request.urlopen(request, timeout=60) as response:
answer = json.load(response)
except urllib.error.HTTPError as error:
answer = json.load(error)
if "data" not in answer:
raise RuntimeError(answer.get("error", {}).get("code", "network_error"))
return answer["data"]
balance = choplife("GET", "/balance")
print(f"Balance: {balance['balance']} kobo")
# Save this key with your own order, and reuse it if you retry.
reference = f"demo-{secrets.token_hex(8)}"
order = choplife("POST", "/orders", {"product": "mtn-airtime", "amount": 10000, "recipient": "08031234567"}, {"Idempotency-Key": reference})
print(f"Order {order['id']}: {order['status']}")
Basics
- Base address:
https://choplife.co/api/developer/v1 - Sign in: send
Authorization: Bearer YOUR_KEY. Keys start withcl_test_orcl_live_. - Money: every amount is in kobo. ₦100 is
10000. Amounts must be whole naira. - Prepaid: live orders are paid from your Choplife wallet. There is no credit.
- Limit: 120 requests a minute per key. Over that you get
429with aRetry-Afterheader. - Live keys: your account must be verified with BVN or NIN.
Test mode
Test keys use a pretend balance. No money moves and nothing is delivered. The end of the recipient decides the result:
| Recipient ends in | Result |
|---|---|
0000 | Fails |
1111 | Stays pending for about a minute, then succeeds and sends your webhook |
| Anything else | Succeeds at once |
Endpoints
| Request | What it does |
|---|---|
GET /products | Lists products. Filter with ?service=airtime|data|power|tv|exam and ?biller=mtn. |
POST /quotes | Today's price. Send product, and amount for airtime and power. |
POST /customers/verify | Checks a meter, smartcard or JAMB profile. Send product, recipient, and meter_type for power. |
GET /balance | Wallet balance, this month's volume and your discount. |
POST /orders | Places an order. Needs an Idempotency-Key header. |
GET /orders | Your orders, newest first. Use ?limit= (up to 100) and ?cursor= from next_cursor. |
GET /orders/{id} | One order. |
POST /orders/{id}/webhook | Sends a finished order's webhook again. |
GET /webhook | Your webhook address. |
PUT /webhook | Sets it. Send url, and rotate_secret: true for a new secret. |
Orders
POST /orders
Idempotency-Key: your-unique-order-id
{
"product": "ikeja-power",
"amount": 500000,
"recipient": "12345678901",
"meter_type": "prepaid",
"max_total": 510000
}
- Retries are safe. The same
Idempotency-Keyreturns the first order and never charges twice. Using it for a different order returns409 idempotency_conflict. - Lock the price. With
max_total, the order is refused with409 price_changedif the price has gone above it. - Status is
pending,successorfailed. A failed live order refunds your wallet in full. - Tokens. Power tokens and exam PINs are in
tokenonce the order succeeds. - Recipient: an 11-digit phone for airtime and data, a meter number for power, a smartcard number for TV, and a profile code for JAMB. Other exam PINs need none.
Webhooks
When an order finishes we POST order.success or order.failed to your HTTPS address on port 443. Answer with any 2xx status within 5 seconds. If you don't, we retry after 1, 5, 30, 120, 360 and 1440 minutes. Handle repeats using the Choplife-Delivery header. The portal can send a signed ping event to test your address, and shows every delivery.
{
"id": "evt_...",
"type": "order.success",
"created_at": "2026-11-22T12:00:00+00:00",
"data": { "id": "ord_...", "status": "success", "reference": "your-unique-order-id", "total": 500000 }
}
Always check the Choplife-Signature header, t=TIMESTAMP,v1=HMAC. The HMAC is SHA-256 of TIMESTAMP.RAW_BODY using your webhook secret.
PHP
<?php
// Pass the raw request body, before any JSON parsing.
function choplife_webhook_is_valid(string $rawBody, string $header, string $secret, int $toleranceSeconds = 300): bool
{
if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $parts) || abs(time() - (int) $parts[1]) > $toleranceSeconds) {
return false;
}
return hash_equals(hash_hmac('sha256', "{$parts[1]}.{$rawBody}", $secret), $parts[2]);
}
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
// Pass the raw request body, before any JSON parsing.
export function choplifeWebhookIsValid(rawBody, header, secret, toleranceSeconds = 300) {
const parts = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!parts || Math.abs(Date.now() / 1000 - Number(parts[1])) > toleranceSeconds) {
return false;
}
const expected = createHmac('sha256', secret).update(`${parts[1]}.${rawBody}`).digest();
return timingSafeEqual(expected, Buffer.from(parts[2], 'hex'));
}
Python
import hashlib
import hmac
import re
import time
# Pass the raw request body as bytes, before any JSON parsing.
def choplife_webhook_is_valid(raw_body, header, secret, tolerance_seconds=300):
parts = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", header or "")
if not parts or abs(time.time() - int(parts[1])) > tolerance_seconds:
return False
expected = hmac.new(secret.encode(), parts[1].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts[2])
Errors
{ "error": { "code": "insufficient_balance", "message": "...", "fields": {} } }
| Status | Code | What to do |
|---|---|---|
| 400 | idempotency_key_required | Send the header. |
| 401 | invalid_key | Check the key, or make a new one. |
| 402 | insufficient_balance | Fund your wallet and retry with the same key. |
| 403 | kyc_required, live_not_open, account_closed, api_blocked, ip_not_allowed, funds_on_hold, daily_limit_reached | Read the message. For a paused account or a limit review, open a ticket in Choplife Help. |
| 404 | product_not_found, not_found | Use an ID from GET /products. |
| 409 | price_changed, idempotency_conflict, request_in_progress, order_not_finished, webhook_not_set | Read the message. For request_in_progress, retry shortly. |
| 422 | validation_failed, invalid_amount, invalid_recipient, invalid_meter_type, invalid_webhook_url | Fix the field named in fields. |
| 429 | rate_limited | Wait for Retry-After. |
| 500, 503 | server_error, product_unavailable | Retry later with the same key. |
Account safety
- Daily limit: live orders start at ₦100,000 a day per account. Choplife can raise it after review.
- New card money: card top-ups can't be spent through the live API for a few days. Bank transfers are not held.
- IP lock: lock any live key to your server addresses in the portal.
- Unusual activity: sudden spikes or many orders to one number pause the account until our team reviews it.
Pricing
- Power: a flat ₦100 fee per order. The full amount goes to the meter.
- Volume: 0.5% off from ₦1,000,000 of API spend in a calendar month.
- Higher volume: 1% off from ₦5,000,000.
- Discounts depend on the product's margin, so always read the price from
POST /quotes. API orders don't earn points.