Paystack integration guide

What this integration supports

Methods

Card, bank transfer, mobile money, USSD.

Currencies

KES, NGN, GHS, ZAR, USD (subject to your own Paystack account).

Checkout

Hosted checkout on checkout.paystack.com.

Webhooks

Signed by Paystack with HMAC-SHA512 (x-paystack-signature), then re-emitted to you by NunuaPay.

Refunds

Full and partial refunds.

Status query

Yes — NunuaPay verifies server-side with Paystack.

Prerequisites

• Your own Paystack merchant account with a test and/or live secret key.
• A business in NunuaPay.
• A NunuaPay API key for the environment you are testing.

1. Configure Paystack in NunuaPay

In your business settings open Providers, add Paystack, and supply the secret and public keys from your Paystack dashboard for the chosen environment. Credentials are encrypted at rest with AES-256-GCM and are never returned by the API.

Provider credentials are configured once per business and inherited by its branches; method availability can be overridden per branch.

2. Create a card payment

Paystack hosted checkout requires a customer email. The amount is an integer in minor units (whole shillings for KES); NunuaPay handles the provider’s amount conversion.

curl -X POST https://pay.nunuanow.com/v1/payment-intents \\
  -H "Authorization: Bearer nup_live_<lookup>_<secret>" \\
  -H "Idempotency-Key: order-1002" \\
  -H "Content-Type: application/json" \\
  -d '{
    "businessId": "<businessId>",
    "method": "card",
    "amount": 2500,
    "currency": "KES",
    "email": "customer@example.com",
    "returnUrl": "https://your-shop.example.com/order/1002",
    "merchantRef": "ORDER-1002"
  }'

The response includes checkoutUrl. Redirect the customer there to pay.

3. Hosted checkout and the return URL

Paystack appends reference and trxref to your returnUrl when the customer comes back. The return page is not proof of payment: NunuaPay’s checkout return view re-verifies the transaction server-side and shows pending, success or failure — polling while the payment is still pending.

4. Verify the payment

Confirm the outcome before fulfilling with POST /v1/payment-intents/:id/verify. Only a succeeded status means the customer paid.

5. Paystack webhooks

Paystack posts events to NunuaPay, which validates the x-paystack-signature header (HMAC-SHA512 of the raw request body using that account’s secret key) before applying any state change. Paystack’s charge.success maps to a successful payment and charge.failed to a failure. NunuaPay then notifies your endpoint with a signed payment.succeeded or payment.failed event.

You do not implement the Paystack webhook yourself — configure it once per Paystack account at https://pay.nunuanow.com/v1/webhooks/inbound/<businessId>/paystack/live (or /test). See the webhooks guide for the outbound events you handle.

6. Refunds

Refunds use POST /v1/refunds and require an Idempotency-Key header:

curl -X POST https://pay.nunuanow.com/v1/refunds \\
  -H "Authorization: Bearer nup_live_<lookup>_<secret>" \\
  -H "Idempotency-Key: refund-order-1002" \\
  -H "Content-Type: application/json" \\
  -d '{ "paymentIntentId": "nup_pay_...", "amount": 2500, "currency": "KES", "reason": "customer request" }'

Partial refunds are supported where the payment allows it; a refund that exceeds the refundable balance returns refund_exceeds_available. PayHero and M-Pesa do not support refunds through NunuaPay.

Testing

Use a test API key and Paystack test cards to exercise success, failure and pending flows. Test and live credentials are separate: a live payment intent cannot be created with a test key.

Common errors

validation_error

Missing customer email.

unsupported_currency

The currency is not enabled on your Paystack account.

invalid_signature

A proxy altered the Paystack webhook body before verification.

provider_not_configured

No Paystack credentials are set for this business.

Next steps