Paystack

You are building a Paystack integration for [Django / Next.js / Laravel / Rails / etc.]. Follow these rules exactly.

## Architecture
1. Use **Paystack Standard (redirect)** or **Paystack Inline (Popup)** — never build a custom card form. Paystack is PCI DSS Level 1; routing PAN data through your server removes that protection and makes YOU responsible for PCI scope.
2. Flow: `transaction/initialize` server-side → redirect/popup to `authorization_url` → customer pays → Paystack redirects to your `callback_url` with `?reference=...` → **your server calls `transaction/verify/{reference}` before fulfilling the order**. Never trust the client-returned reference.
3. Also subscribe to webhooks at `POST /paystack/webhook` for `charge.success`, `transfer.success`, `transfer.failed`, `subscription.create`, `invoice.payment_failed`, `chargeback.create`. Webhooks are the source of truth for async events; `verify` is the source of truth for the synchronous callback.

## Amounts (critical)
All amount fields are in the minor unit:
- NGN: kobo (₦1,000 = 100000)
- GHS: pesewas (GHS 10 = 1000)
- ZAR / KES: cents (R 10 = 1000)
- XOF: centimes (XOF 1,000 = 100000)
- EGP: piastres (EGP 10 = 1000)

Do all arithmetic in integer subunits. Never use floats for money.

## Webhook security (do not skip)
1. Verify `x-paystack-signature` = `HMAC-SHA512(raw_request_body, PAYSTACK_SECRET_KEY)` on every webhook. Use a constant-time comparison (`hmac.compare_digest` / `crypto.timingSafeEqual`).
2. Capture the **raw** request body before any JSON parsing:
   - Django: build a middleware that stores `request.body` before any parser runs, OR disable `CSRF_TRUSTED_ORIGINS` on the webhook endpoint and read `request.body` directly in the view.
   - Next.js App Router: `const raw = await req.text(); const body = JSON.parse(raw);` — never `await req.json()` first.
   - Laravel: `$request->getContent()` before any middleware parses it.
   - Express: `app.use('/paystack/webhook', express.raw({type: 'application/json'}), handler)`.
3. Additionally IP-allowlist Paystack's webhook IPs (fetch the current list from the Paystack dashboard — do not hardcode).
4. Return `200 OK` within 5 seconds. Queue any heavy work (email, fulfilment) to a background job — Paystack retries failed webhooks every 3 minutes for 4 attempts then hourly for 72 hours.
5. **Idempotency:** the same event may be delivered multiple times. Store `event.data.reference` (and `event.id` where present) in a processed-events table and short-circuit duplicates.

## Secrets
- Use `PAYSTACK_SECRET_KEY` server-side only (never exposed to browser bundles).
- Use `PAYSTACK_PUBLIC_KEY` only on the client for Inline/Popup init.
- Separate test and live keys; never commit either.

## Currency & country config
Each merchant country has different channels. Pass the correct `currency` (`NGN`/`GHS`/`ZAR`/`KES`/`XOF`/`EGP`) and, if constraining methods, the `channels` array (`['card','bank','mobile_money','ussd','bank_transfer','qr']`). Apple Pay requires extra domain verification via the dashboard.

## Development workflow
- Paystack does NOT accept `localhost` as a webhook URL. Use ngrok or Cloudflare Tunnel during local development and rotate the URL in the dashboard on each session, or keep a staging deploy with a stable URL.
- Test mode and live mode use separate secret keys. Test card PAN for NG: `4084 0840 8408 4081`.

## Subscriptions
- Create a `Plan` first, then create `Subscription` objects against customer email. Handle `subscription.disable`, `invoice.payment_failed`, and `invoice.create` webhooks to manage access state.
- For Nigeria, `Direct Debit` on local bank accounts is a first-class recurring channel at the local-transaction rate.

## Split payments (marketplace)
Use `Split` objects (`percentage` or `flat` types) attached to the transaction to route portions to multiple subaccounts in one charge. Platform fee lands in your main account automatically.

## Disputes (Nigeria)
Subscribe to `chargeback.create`. The CBN-mandated response window is **16 hours** — missing it auto-accepts the chargeback and deducts the amount plus a ₦2,500 fee. Page oncall on that event.

## Error handling
- Treat every non-2xx from Paystack as retryable with exponential backoff (3 attempts, 1s/5s/30s).
- Log `transaction/verify` responses — the `status`, `gateway_response`, `channel`, and `fees` fields are essential for reconciliation.

Deliver a minimal working integration: init → verify → webhook verified handler → idempotent fulfilment. Do not add features beyond those requested.