Environments
Live and test
There is a single base URL for all traffic:
https://api.subthingy.io/v1All paths in this documentation are relative to that base, for example:
https://api.subthingy.io/v1/transactions/airtime/syncLive and test are not separate hosts. Every merchant profile is provisioned with two credential pairs — one live, one test — both valid against the same base URL:
| Credential | Purpose |
|---|---|
Test X-Merchant-Key / X-Merchant-Secret | Integration testing, UAT, and credential validation |
Live X-Merchant-Key / X-Merchant-Secret | Real customer traffic |
Which environment a request runs in is resolved from the credential pair you send — not from the URL. Contact your account manager to receive your live and test API keys during onboarding.
Do not use your live credentials for integration testing (or your test credentials for real traffic). Keys issued for one environment are not valid for the other, even though the URL is identical.
Test bill payments
On test credentials, only the identifiers below are accepted. Verify and purchase return the same success envelope as a live payment (response_code 00, response_message Successful) and are simulated. Any other ID is rejected.
| Product | Example (msisdn) | Mock success extras |
|---|---|---|
| Prepaid electricity | 10000000001 | Purchase: token 47861234567890123456, units 10.00 kWh (Ikeja Electric) when plan_code 1001; verify: customer_address Ikeja Electric - Test Address |
| Postpaid electricity | 10000000002 | customer_name Test Customer (no token) |
| DStv | 10000000010 | Verify: bouquet DStv Compact |
| GOtv | 10000000020 | Verify: bouquet GOtv Smallie |
| StarTimes | 10000000030 | Verify: bouquet StarTimes Classic |
| Betting | TESTBET001 | Verify: customer_username test_user |
Use POST /v1/transactions/verify with the same test credentials to pre-check a meter or smartcard — see Bill payments.
Test eSIM
On test credentials, any active catalog plan_id is accepted. Purchase runs catalog + wallet validation, then returns a simulated success (response_code 00) with install fields. Invalid plan_id values are still rejected.
On test credentials, catalog ngn_price, quote ngn_amount, and order amount all use the curated catalog cost (same FX). Live credentials refresh cost from the live offer when available so those three stay aligned on current pricing.
Live credentials always go to the real biller.
Test gift cards
On test credentials, any active catalog plan_id is accepted. Availability returns in-stock, and purchase runs catalog + wallet validation, then returns a simulated success (response_code 00) with placeholder card fields. No live stock check or fulfillment call is made.
Invalid / unknown plan_id or price outside the catalog range is still rejected.
Live credentials perform a real purchase and require products that are currently in stock.
IP whitelisting (production)
Production access requires your outbound IP addresses to be whitelisted before go-live.
- Collect the public egress IPs used by your servers, jobs, or integration platform.
- Send the list to your account manager.
- Wait for confirmation that whitelisting is active before switching live traffic.
Requests using live credentials from non-whitelisted IPs are rejected. Test-credential traffic may use a separate policy — confirm with your account manager during onboarding.
Reconciliation reporting
Transaction reconciliation reports are delivered by email on a T+1 schedule: reports for a given calendar day are sent on the next business day.
To receive reports, provide one or more reconciliation email addresses to your account manager, for example:
recon@yourcompany.comfinance@yourcompany.com
Include:
- Primary recipient(s) for daily files
- Optional CC addresses for your finance or operations team
- Any naming convention you need in the email subject (if supported for your merchant)
Reports typically cover settled transactions, totals by product, and status breakdowns. Contact your account manager if you need a custom format or additional delivery schedule.