Flutterwave

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

## Architecture
1. Use **Flutterwave Standard (redirect checkout)** or **Flutterwave Inline (modal)** — never build a custom card form. Flutterwave is PCI DSS Level 1; routing raw PAN through your server moves PCI scope to you.
2. Flow: server calls `POST /v3/payments` with `tx_ref`, `amount`, `currency`, `customer`, `redirect_url` → customer is redirected to `data.link` → completes payment → Flutterwave redirects to your `redirect_url` with `?status=&tx_ref=&transaction_id=` → **your server calls `GET /v3/transactions/{transaction_id}/verify` before fulfilling the order**. Never trust the client-returned status.
3. Also subscribe to webhooks at `POST /flutterwave/webhook` for `charge.completed`, `transfer.completed`, `transfer.failed`, `subscription.cancelled`, `charge.dispute`. Webhooks are the source of truth for async events; `verify` is the source of truth for the synchronous redirect.

## Amounts (critical — different from Paystack/Stripe)
Flutterwave v3 uses **main currency units**, NOT subunits:
- NGN 1,000 → `amount: 1000`
- GHS 10 → `amount: 10`
- ZAR 50 → `amount: 50`
- USD 9.99 → `amount: 9.99`

If you are porting from Paystack (kobo/pesewas/cents), divide by 100. Do all money math in `Decimal` (never floats) and pass as the main unit.

## Webhook security (do not skip)
1. Set a long random Secret Hash in Dashboard → Settings → Webhooks — separate values for Live and Test. Store as `FLUTTERWAVE_SECRET_HASH_LIVE` / `_TEST`.
2. Verify `flutterwave-signature` = `HMAC-SHA256(raw_request_body, SECRET_HASH)` base64-encoded. Use constant-time comparison (`hmac.compare_digest` / `crypto.timingSafeEqual`).
3. Capture the **raw** request body before any JSON parsing:
   - Django: read `request.body` in the view before DRF's parser runs. Mark the webhook endpoint `@csrf_exempt` but keep a `HttpResponseForbidden` fallback.
   - Next.js App Router: `const raw = await req.text(); const body = JSON.parse(raw);` — never `await req.json()` first.
   - Laravel: `$request->getContent()` before middleware parses it.
   - Express: `app.use('/flutterwave/webhook', express.raw({type: 'application/json'}), handler)`.
4. Return `2xx` within 60 seconds — Flutterwave times out past that. Queue heavy work (email, fulfilment) to a background job.
5. **Idempotency:** duplicates happen. Store `event.data.tx_ref` + `event.data.id` in a processed-events table and short-circuit duplicates. Also call `/verify` on the transaction ID before fulfilling to protect against replay.
6. IP-allowlist Flutterwave's webhook IPs (pull current list from the Dashboard — do not hardcode).

## Secrets
- `FLW_SECRET_KEY` server-side only (used for all /v3 API calls; never expose to browser bundles).
- `FLW_PUBLIC_KEY` client-only for Inline/modal init.
- `FLW_ENCRYPTION_KEY` server-side only if using raw Card API (prefer Standard/Inline to avoid this).
- `FLW_SECRET_HASH` server-side only for webhook verification — separate Live/Test values.
- Never commit any of these.

## Currency & country config
Each market gets specific channels. Pass the correct `currency` (`NGN`/`GHS`/`KES`/`ZAR`/`UGX`/`TZS`/`RWF`/`ZMW`/`XOF`/`XAF`/`EGP`/`GBP`/`EUR`/`USD`) and, if constraining methods, `payment_options` (e.g., `"card,banktransfer,ussd,mpesa,mobilemoneyghana,mobilemoneyuganda"`). Apple Pay requires domain verification via the dashboard.

## International Processing Fee
A flat 2% IPF applies to non-card APMs (bank transfer, Apple Pay, Google Pay, mobile money) for every **cross-border** transaction — uncapped. Decide up-front whether to absorb it or pass it to customers (Dashboard → Business Preferences → Fee Settings). Document the choice in your pricing copy.

## Development workflow
- Use the Flutterwave CLI (`npm i -g @flutterwave/cli` then `flutterwave webhook:ping`) to test webhooks locally without tunnelling — or use ngrok + register the URL in the Test-mode dashboard.
- In test mode, **transfers stay pending until you pass `X-Scenario-Key`** in the header (e.g., `success`, `failed`). Without it no webhook fires.
- Test card PAN for NG: `5531 8866 5214 2950` (Mastercard); CVV `564`; PIN `3310`; OTP `12345`.

## Subscriptions
- Create a `Payment Plan` first (`POST /v3/payment-plans`) then initiate a transaction with `payment_plan` set. Handle `subscription.cancelled`, `charge.completed` (renewal), and `charge.failed` webhooks to manage access state.
- Tokenize once (first successful charge returns a `token`) then reuse via `/v3/tokenized-charges` — avoids repeated 3DS on the same card.

## Split payments (marketplace)
Create `Subaccounts` (`POST /v3/subaccounts`) then pass a `subaccounts: [{id, transaction_split_ratio}]` array on the charge. Platform fee lands in the main account automatically.

## Disputes
Subscribe to `charge.dispute`. NG local response window is **24 working hours**, international is **48 working hours**. Missing it auto-accepts and deducts the disputed amount plus a $38 international-chargeback fee. Page on-call when the event fires.

## Error handling & reconciliation
- Treat every non-2xx from Flutterwave as retryable with exponential backoff (3 attempts, 1s/5s/30s) — except for 4xx validation errors.
- Log every `/verify` response — the `status`, `processor_response`, `charged_amount`, `app_fee`, `merchant_fee` fields are essential for reconciliation.
- Store the Flutterwave `id`, `tx_ref`, `flw_ref`, and `charged_amount` on your order. Reconcile daily against settlement reports.

## Dashboard hardening
- Enforce 2FA on every admin account (the 2023 and 2024 breaches were internal-access vectors).
- Rotate Secret/Public/Encryption keys on staff departure.
- IP-allowlist admin dashboard and API key usage where possible.

Deliver a minimal working integration: initialize → redirect/modal → server-side verify → webhook with HMAC-SHA256 → idempotent fulfilment. Do not add features beyond those requested.