Paystack Checkout — setup and reference

Module and release scope

This guide covers Paystack Checkout 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Sandbox, live = Live
secret_key — Secret API key	secret	Yes	Use the account-specific value described below.
currencies — Approved invoice currencies	text	Yes	Comma-separated currencies approved for this merchant. No currency conversion is performed.

Uses server-side transaction initialization and Paystack-hosted checkout. Supported invoice currencies: NGN, GHS, ZAR, KES and USD. Merchant onboarding, supported countries and USD availability depend on your Paystack account; configure only approved currencies.

Configure

1. Open Paystack Dashboard → Settings → API Keys & Webhooks and copy the appropriate secret key. Sandbox requires sk_test_; live requires sk_live_. Public keys are not needed for this hosted flow.
2. Enable transaction initialization/verification and balance-read API permission. Test makes an authenticated GET /balance, never a transaction or transfer. Balance amounts are discarded and not displayed or persisted. No payout or refund-creation permission is used; refund-read permission is required to check reversal state.
3. Save the connection’s exact webhook URL in the same dashboard section. Subscribe to successful charge notifications (charge.success). Paystack signs the exact raw JSON payload with HMAC-SHA512 using the account secret key; the module verifies x-paystack-signature and then performs transaction verification independently. Do not configure a second unrelated webhook signing key.
4. Enter approved invoice currencies, run Test and enable the connection. The fixed API host is api.paystack.co; hosted redirects are restricted to checkout.paystack.com.

Paystack’s verified transaction reference, environment, amount, currency and application metadata must match. The module accepts only final success, never pending/authorization/reversed states. Provider-returned reference and trxref are locators only.

Installation and activation

The package contains generic product code only. Installation leaves the module disabled and does not create, enable or populate a merchant account. In System → Payments → Provider library, enable the module only when ready, add a connection, enter your own credentials, run Test and explicitly enable that connection. Keep sandbox and live accounts separate. Existing enabled gateways are unaffected.

Use the exact HTTPS webhook URL displayed on that saved connection; do not enter the storefront home page. One connection endpoint can serve invoices across storefront domains because payment attempts retain their connection and invoice identity. Keep it reachable without login or a browser challenge. Return URLs are generated and signed by the application per invoice; do not replace them with a static merchant callback.

The module never collects PAN, CVV or customer wallet credentials. Checkout creation is submitted once, with a unique attempt reference; a timeout requires reconciliation, not an automatic second charge. Browser success parameters never prove payment. Final amount, currency, checkout identity and application metadata are checked against authenticated provider reads. Notifications use stable payment IDs for duplicate protection. A partial or ambiguous payment stays under billing review.

No currency conversion is performed. Only the listed two-decimal invoice currencies are accepted, and only those explicitly entered under Approved invoice currencies are offered. Availability of cards, wallets and local methods remains subject to the merchant account, shopper location and provider checkout; installing a module does not enable provider payment products. Refund creation, recurring billing and token charging operations are not implemented. A read-only refund query prevents a previously refunded transaction from being newly allocated; any refund record keeps the checkout under billing review.

Validation

Run php tests/gateway-growth.php for isolated HTTP fixtures covering checkout creation, server verification, signed notifications, exact amounts, identity mismatches, invalid URLs, incomplete billing profiles and no checkout POST retries. These checks do not certify credentials, merchant underwriting or a live payment. Complete a provider sandbox checkout and callback test before enabling live traffic.

Official implementation references

Reviewed 2026-10-21. Provider contracts may change; recheck these sources before changing API versions.

• https://paystack.com/docs/api/transaction/
• https://paystack.com/docs/payments/webhooks/
• https://paystack.com/docs/transfers/managing-transfers/
• https://paystack.com/docs/api/refund/