Bills PaymentsOverview

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 - discount

The 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

StatusHTTP statusMeaningWhat to do
delivered200The provider confirmed delivery.Treat the purchase as successful.
pending202The provider result is not final.Do not retry the purchase. Query the existing reference.
failed422The 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

  1. Fetch the supported provider and product/package lists.
  2. Validate the customer identifier for TV or electricity where required.
  3. Send the purchase once with a unique reference.
  4. Accept 200 as delivered and 202 as pending.
  5. For pending or ambiguous outcomes, query the existing reference instead of submitting another purchase.