Tap Payments

You are building a Tap Payments integration for [Django / Next.js / Laravel / Rails / etc.] targeting [one of KSA / KW / UAE / BH / QA / OM]. Follow these rules exactly.

## Architecture
1. Use **Tap Hosted Checkout** or the **Tap Checkout SDK** (Web/iOS/Android/Flutter/React Native) — do not build a custom card form unless you already hold a valid PCI DSS AoC. If you do go custom, you MUST use Tap's RSA public key to encrypt cardholder data client-side before sending to your server.
2. Flow: server-side `POST /v2/charges` → redirect customer to `transaction.url` (redirect flow) or render Tap SDK (direct flow) → customer completes payment → Tap redirects to your `redirect.url` with a charge ID → **your server calls `GET /v2/charges/{charge_id}` before fulfilling the order**. Never trust the client-returned status.
3. Subscribe to webhooks at `POST /tap/webhook` by passing `post.url` on the charge. Listen for `CAPTURED`, `AUTHORIZED`, `FAILED`, `DECLINED`, `CANCELLED`, and subscription/invoice events. Webhooks are the source of truth for async events; `GET /v2/charges/{id}` is the source of truth for the synchronous callback.

## Amounts (critical)
All amounts are rounded to the currency's decimal places:
- **2 decimals:** SAR, AED, QAR, EGP, USD (e.g., SAR 10.50 = 10.50)
- **3 decimals:** KWD, OMR, BHD (e.g., KWD 10.500 = 10.500)

When you construct the webhook-verification hashstring, the amount MUST match the rounding Tap uses or the signature will not match. Do arithmetic in integer subunits internally and format to the exact decimal count at the API and webhook-verification boundaries.

## Webhook security (do not skip)
1. Verify the `hashstring` header on every webhook. The hash is HMAC-SHA256 of the concatenated string, using your **secret API key** as the HMAC key.
2. Concatenation order (for charges) is documented as:
   `x_id` + `x_amount` + `x_currency` + `x_gateway_reference` + `x_payment_reference` + `x_status` + `x_created`
   Use an empty string if `gateway_reference` is unavailable. For invoices, the `updated` field replaces `gateway_reference`.
3. Compute the HMAC-SHA256 hex digest and compare with `timingSafeEqual` / `hmac.compare_digest` — never string equality.
4. Return `200 OK` within 5 seconds. Queue heavy work (email, fulfilment) to a background job.
5. **Idempotency:** pass `reference.idempotent` on the charge create to prevent duplicate charges from retried network requests. On the receive side, deduplicate by `charge.id` in a processed-events table so repeated webhook deliveries don't re-fulfil.
6. **Reconciliation:** always set `reference.order` and `reference.transaction` on the charge so your reporting can join back to your DB.

## Secrets
- Use `sk_live_...` / `sk_test_...` server-side only. Never ship to the browser bundle.
- Use `pk_live_...` / `pk_test_...` only on the client for SDK init.
- Separate test and live keys. Test transactions do not settle.

## Currency & country config
Each GCC market has different core local schemes. Pass the correct `currency` and constrain `source` / payment-methods accordingly:
- **KSA (SAR):** cards + mada + Apple Pay over mada + STC Pay + Tabby
- **KW (KWD):** cards + KNET + KFAST + Apple Pay
- **UAE (AED):** cards + Apple Pay + Google Pay + Tabby
- **BH (BHD):** cards + Benefit + BenefitPay (separate Benefit Pay Web SDK)
- **QA (QAR):** cards + NAPS/QPay
- **OM (OMR):** cards + OmanNet

Apple Pay requires domain verification via the Tap dashboard before going live.

## Development workflow
- Register webhook URL via `post.url` on each charge (not a dashboard global). Use ngrok/Cloudflare Tunnel during development or a stable staging deploy.
- Before going live: run an integration review with Tap's Developer Experience team, swap to `sk_live_` keys, configure production `redirect.url` and `post.url`, and run one live transaction per payment method across web/iOS/Android.

## Subscriptions
- Create a `Plan` then a `Subscription` tied to a customer email. Handle `subscription.create`, `subscription.updated`, and invoice webhooks.
- mada supports recurring charges with saved cards — the only Saudi local scheme that does.

## Marketplace split payments
Use the Split API to route portions of a single charge to multiple sub-accounts. Works across currencies for marketplaces with GCC-multi-country sellers.

## Error handling
- Treat non-2xx responses from Tap as retryable with exponential backoff (3 attempts, 1s/5s/30s).
- Log the full response from `GET /v2/charges/{id}` for reconciliation — the `status`, `response.code`, and `source` fields are essential when investigating declines.
- Merchants on MENA report higher decline rates on some international cards than global comparables — expose a secondary retry path (different method) in your UI.

## Compliance
- PCI DSS certification level is not publicly advertised by Tap. If your own compliance program requires a supplier AoC, request it from Tap during onboarding in writing — do not assume Level 1.
- FX premium on foreign-currency transactions is 2–5% per the T&Cs. Price accordingly if you accept non-settlement-currency cards.

Deliver a minimal working integration: create charge → verify on redirect → signature-verified webhook handler → idempotent fulfilment. Do not add features beyond those requested.