Bill Payments
SaySwitch bill-payment APIs let your server purchase airtime and data, pay TV subscriptions, and vend electricity through an NGN wallet.
Base URL
https://backendapi.sayswitchgroup.com/api/v1
Authentication and environment
Send your SaySwitch secret key on every request:
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json- A test key (
sk_test_...) uses your test wallet and the provider sandbox. - A live key (
sk_live_...) uses your live wallet and the live provider. - Keep secret keys on your server. Never expose them in browser or mobile-app code.
- Live bill-payment requests are subject to your configured IP whitelist.
Pricing and wallet debit
Pricing is configured by SaySwitch for the service, provider, environment, and, where applicable, your business. The amount removed from your wallet is:
totalDebited = amount + fee - discountThe purchase response includes the authoritative amount, fee, discount, and totalDebited. Do not calculate or assume the final wallet debit independently.
Your reference
Every purchase requires a unique reference. The same reference cannot be used for another bill-payment order in the same environment. Store both:
reference: your reference supplied in the request.orderNo: the SaySwitch order number used for provider reconciliation.
Purchase statuses
| Status | HTTP status | Meaning | What to do |
|---|---|---|---|
delivered | 200 | The provider confirmed delivery. | Treat the purchase as successful. |
pending | 202 | The provider result is not final. | Do not retry the purchase. Query the existing reference. |
failed | 422 | The purchase failed and the wallet debit is reversed when applicable. | Show the failure and do not treat value as delivered. |
Network errors and timeouts are ambiguous. Before creating another purchase, query the original reference using the Status and reconciliation endpoint.
Webhooks
When a purchase initially returns pending, SaySwitch sends its final delivered or failed result to your configured merchant webhook URL. See Bill-payment webhooks for the payload and signature headers.
You can also use Status and reconciliation while waiting for the final update.
Purchase response fields
All purchase endpoints return this common financial and status information:
{
"success": true,
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"orderNo": "2026111318502144124979",
"reference": "merchant-order-10001",
"status": "delivered",
"errorMsg": "TRANSACTION SUCCESSFUL",
"amount": 1000,
"discount": 0,
"fee": 0,
"totalDebited": 1000
}
}TV and electricity responses can also contain purchased_code; electricity can additionally contain units.
Safe integration flow
- Fetch the supported provider and product/package lists.
- Validate the customer identifier for TV or electricity where required.
- Send the purchase once with a unique reference.
- Accept
200as delivered and202as pending. - For pending or ambiguous outcomes, query the existing reference instead of submitting another purchase.