Paystack

Collect payments with Paystack

PAYSTACK uses a hosted checkout: Centipid Billing initializes a transaction, sends the payer’s browser to Paystack’s authorization page, and verifies the result against Paystack before crediting anything.

Offered in the country catalog for Kenya, Rwanda, Ghana, Côte d’Ivoire, South Africa, Egypt, and Nigeria.

Before you start

1. Complete Paystack merchant onboarding in an account owned by the ISP, and have the business verified so live keys are issued.
2. From the Paystack dashboard collect the live secret key (sk_live_…) and the live public key (pk_live_…).
3. Plan the walled garden: the payer’s browser must reach Paystack’s checkout page, so a Hotspot subscriber who is not yet online cannot pay unless Paystack is reachable pre-authentication.

Configure the gateway

1. Open Settings → Payments → Paystack

   Select Paystack from the payment marketplace.

2. Enter the secret key

   Secret key (required) starts with sk_live_. It is stored as a secret and is not echoed back into the form after saving.

3. Enter the public key

   Public key (required) starts with pk_live_.

4. Allow Paystack through the captive walled garden

   Add Paystack’s checkout domain to the walled garden on every Hotspot router, then confirm from a device that is not yet authenticated. See Captive portal.

5. Run a controlled test payment

   Pay a small amount from the captive portal on a real unauthenticated device, and confirm the payment reaches the ledger with method Paystack.

Credentials

Field	Required	Notes
Secret key	Yes	Secret. The form expects a live key (sk_live_…).
Public key	Yes	The form expects a live key (pk_live_…).

Caution

This form is for live keys. Do not paste test keys into it — a sk_test_… secret initializes transactions that never move real money, and the mismatch is easy to miss because checkout still appears to work.

Callback URLs

Settings → Payments shows https://<your-host>/tenant/paystack/callback, which is where Paystack returns the payer after checkout.

What the payer must provide

Whatever Paystack’s own checkout page asks for — card details, mobile money, or a bank transfer, depending on what Paystack has enabled for your account. The amount and reference are fixed before the payer arrives.

How a payment completes

1. Initialize

   Centipid Billing calls https://api.paystack.co/transaction/initialize and receives an authorization URL, then stores the local transaction against the reference.

2. Payment

   The payer’s browser is sent to Paystack and the payment is completed there.

3. Verification

   On return, the reference is verified against Paystack. Only a verified successful transaction records a payment and applies the package — the return itself proves nothing.

A repeated verification of an already-settled reference is rejected as a duplicate rather than credited twice.

Troubleshooting

Symptom	What it means	What to do
“Payment initiation failed: Paystack secret key not configured…”	No secret key is saved.	Enter it in Settings → Payments.
“Payment initiation failed: Paystack API request failed with status: 401…”	Paystack rejected the secret key.	Re-copy it. Confirm the business is verified and the key is live.
“…Payment authorization URL not found in Paystack response”	Paystack accepted the request but returned no checkout URL.	Retry, then raise the reference with Paystack.
The checkout page never loads on a Hotspot device	The walled garden does not allow Paystack.	Allow Paystack’s checkout domain pre-authentication — see Captive device cannot reach checkout.
“Payment not successful”	The transaction verified, but Paystack did not report it as successful.	Have the payer check with their bank or wallet. Nothing is credited.
“Payment reference not found”	The reference verified at Paystack has no matching local checkout.	Raise it with support with the Paystack reference.
Money in Paystack, not in the bank	Paystack settles on its own schedule.	Reconcile against the Paystack settlement report, not only the ledger.

For every gateway’s fields in one place, see the credential reference.