Paystack integration

What this integration supports

Methods

Card, bank transfer, mobile money, USSD.

Currencies

KES, NGN, GHS, ZAR, USD.

Countries

Kenya (KE), Nigeria (NG), Ghana (GH), South Africa (ZA) — subject to your own Paystack account.

Checkout

Initiation returns a hosted checkoutUrl you redirect the customer to.

Webhooks

Signed with HMAC-SHA512 over the raw request body.

Refunds

Full and partial refunds are supported.

Status query

Yes — NunuaPay verifies the transaction server-side with Paystack.

How to configure it

1. In your business settings, open Providers and add a Paystack account.
2. Enter the secret and public keys from your own Paystack dashboard, choosing the correct environment (test or live).
3. Test the connection. Credentials are encrypted at rest with AES-256-GCM.
4. Optionally restrict which payment methods are offered per branch.

Payment initiation flow

1. Create a payment intent with method of card, bank_transfer, mobile_money or ussd.
2. NunuaPay calls Paystack to initialize the transaction and returns a checkoutUrl.
3. Redirect the customer to Paystack’s hosted checkout.
4. Paystack notifies NunuaPay via webhook, and NunuaPay verifies the outcome before marking the intent paid.

Callbacks and webhooks

Paystack posts events to NunuaPay. NunuaPay validates the x-paystack-signature header (HMAC-SHA512 over the raw body) before applying the event, then notifies your endpoint with a signed payment.succeeded or payment.failed event. See the webhooks guide for verification details.

Verifying a payment

Treat the hosted checkout return page as presentational only. Confirm with GET /v1/payment-intents/:id/verify, which queries Paystack directly, or rely on the signed webhook. Only a succeeded status means the customer paid.

Common errors

• invalid_api_key / authorization failed — the Paystack secret does not match the selected environment.
• currency not supported — the method/currency combination is not enabled for the provider account.
• webhook signature mismatch — a proxy modified the request body before NunuaPay verified it.

Testing

Use a test API key and Paystack test cards to exercise success, failure and pending flows before switching to live keys. Test and live credential sets are separate; a live payment intent cannot be created with a test key.

Related