> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paystack

> Configure Paystack hosted checkout for cards, mobile money, and bank transfers.

# 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

<Steps>
  <Step title="Open Settings → Payments → Paystack">
    Select Paystack from the payment marketplace.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Enter the public key">
    **Public key** (required) starts with `pk_live_`.
  </Step>

  <Step title="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](/network/captive-portal).
  </Step>

  <Step title="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**.
  </Step>
</Steps>

## 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_…`).         |

<Warning>
  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.
</Warning>

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

<Steps>
  <Step title="Initialize">
    Centipid Billing calls `https://api.paystack.co/transaction/initialize` and
    receives an authorization URL, then stores the local transaction against the
    reference.
  </Step>

  <Step title="Payment">
    The payer's browser is sent to Paystack and the payment is completed there.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/billing/payment-gateways/troubleshooting). |
| *"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](/billing/payment-gateways/credentials-reference).