FinalDataSub Merchant API
One REST API for data, airtime, electricity, cable TV, exam PINs, betting, internet, voice, bulk SMS, recharge card PINs, gift cards and eSIMs. Every request is authenticated with your secret API key and charged to your FinalDataSub wallet at your API pricing.
Quick start
1. Build against the sandbox
Create a sandbox key (ds_test_…) in Dashboard → Developer. It works straight away with test money, so you can build and test everything before you are approved. See Sandbox & testing.
2. Get API access approved and create a live key
Request API access from Dashboard → API access. Once approved, create a live key (ds_live_…). The full key is shown only once, so copy it into a secret store straight away. You can have up to 5 active live keys and 5 sandbox keys.
3. Call the API from your server
Send Authorization: Bearer ds_live_YOUR_KEY on every request. Keep the key on your server — never call the API from a browser or mobile app.
4. Send a unique reference with every purchase
Your reference is the idempotency key: retrying with the same reference returns the original transaction and never charges twice.
5. Treat pending as “wait”, never “retry”
Purchases return successful, pending or failed. When pending, wait for the webhook or requery GET /transactions/{reference}. Failed purchases are refunded automatically.
At a glance
| Item | Value |
|---|---|
| Base URL | https://finaldatasub.com/api/v1/merchant |
| Authentication | Authorization: Bearer ds_live_YOUR_KEY |
| Sandbox | Same base URL with a ds_test_ key (test money, nothing is sent) |
| Format | JSON request and response bodies |
| Rate limit | 120 requests / minute per API key |
| Purchase statuses | successful · pending · failed |
Quick test — check your wallet balance
curl -X GET "https://finaldatasub.com/api/v1/merchant/wallet/balance" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Accept: application/json"What the API covers
API products covered in this documentation. Categories your account cannot use are hidden from List billers.
Wallet & catalog
Wallet balance, billers, plans and your effective API prices.
GET /wallet/balance · GET /billers · GET /billers/{slug}/products
Data & airtime
Single purchases plus bulk orders to many numbers with per-number results.
POST /data/purchase · /airtime/purchase · /data/bulk · /airtime/bulk
Electricity & cable TV
Verify meters and smartcards, then vend prepaid tokens or pay bouquets.
POST /electricity/verify · /electricity/purchase · /cable/verify · /cable/purchase
Exam PINs, gift cards & eSIM
Result checker PINs, digital gift cards and travel eSIMs with codes in the response.
POST /education/purchase · /giftcard/purchase · /esim/purchase
Betting, internet, voice & SMS
Betting wallet funding, ISP bundles, voice plans and bulk SMS.
POST /betting/fund · /internet/purchase · /voice/purchase · /sms/send
Recharge card PINs
Printable PINs from stock with serials and load codes.
GET /recharge-pin/denominations · POST /recharge-pin/purchase
Beneficiaries
Save and reuse customer numbers, meters and smartcards.
GET · POST /beneficiaries · PUT · DELETE /beneficiaries/{id}
Transactions & webhooks
Requery by reference, receive signed status callbacks and inspect deliveries.
GET /transactions/{reference} · PUT /webhook · GET /webhook/deliveries
Legacy MSORG / Adex endpoints
Drop-in /api/data, /api/topup and /api/user for existing integrations.
Authorization: Token ds_live_…