Xendit

You are building a Xendit integration for [Django / Next.js / Laravel / Rails / Node.js / etc.] targeting [Indonesia / Philippines / Malaysia / Thailand / Vietnam / Singapore]. Follow these rules exactly.

## Architecture
1. Use **Xendit Invoice API (hosted checkout)** or **Xendit Payment Links** for 80% of integrations — never build a custom card form. Xendit is PCI DSS Level 1; routing raw PAN through your server moves PCI scope to you.
2. Flow: server calls `POST /v2/invoices` (Invoice API) with `external_id`, `amount`, `currency`, `customer`, `success_redirect_url`, `failure_redirect_url`, `payment_methods` → customer is redirected to `invoice_url` → completes payment on Xendit's hosted page → Xendit redirects back to `success_redirect_url`.
3. **Do NOT trust the redirect** — Xendit always fires a webhook at your configured URL (per product: `invoice.paid`, `ewallet.capture`, `virtual_account.paid`, `qr_code.payment`, `disbursement`, etc.). Treat the webhook as the source of truth for fulfilment. The redirect is a UX hint only.

## Amounts
Xendit uses **main currency units** (not subunits):
- IDR 50,000 → `amount: 50000`
- PHP 100 → `amount: 100`
- MYR 25 → `amount: 25`
- THB 500 → `amount: 500`
- USD 9.99 → `amount: 9.99`

Do all money math in `Decimal`, never floats. Round to the currency's minor-unit precision (IDR 0 decimals, THB/PHP/MYR 2 decimals).

## Webhook verification (this is the weakest link — take it seriously)
Xendit does **NOT use HMAC** on the request body. Instead it echoes a static token in the `x-callback-token` header. That means:

1. In Dashboard → Settings → Webhooks, generate a long random token (≥32 bytes, base64 or hex). Use **separate tokens for Live and Test**.
2. Store them as `XENDIT_CALLBACK_TOKEN_LIVE` / `XENDIT_CALLBACK_TOKEN_TEST` secrets — never commit.
3. In your webhook handler, extract `request.headers['x-callback-token']` and compare it to the expected token using a **constant-time comparison** (`hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js, `hash_equals` in PHP). Plain `==` leaks timing information.
4. Reject the request with `401` if it doesn't match. Do NOT log the token value.
5. Layer IP allowlisting on top if your WAF or framework supports it (pull Xendit's current egress IPs from their Dashboard — don't hardcode; they can change).
6. Rotate the token on any staff departure, secret scanner alert, or public-repo mistake. Rotation is immediate — Xendit uses the new token on the next callback.

## Idempotency (webhooks + retries)
- Xendit retries failed callbacks up to **6 times with exponential backoff**. Duplicates can also occur on successful deliveries during infrastructure events.
- Every handler must be idempotent on a stable unique id — `invoice_id`, `payment_id`, `capture_id`, `disbursement_id`, or `external_id`. Persist processed event ids in a dedupe table and short-circuit replays before writing any side effects.
- Return `2xx` within Xendit's timeout window; queue fulfilment (emails, provisioning, ERP writes) to a background job rather than doing it inline.

## Authentication (API)
- Xendit uses HTTP Basic Auth: `Authorization: Basic base64(<SECRET_KEY>:)` — note the trailing colon.
- `XENDIT_SECRET_KEY` is server-side only; never expose to browser bundles.
- Public keys exist for some client-side SDKs (tokenization) but you do not need them for Invoice-based flows.
- Use **separate test/live keys** and swap only at deployment time with your env vars.

## Virtual Account model choice (Indonesia specifically)
Decide up-front: **Aggregator** or **Switcher**.
- Aggregator: customer pays a Xendit-owned VA number → funds land in your Xendit balance (Rp 4,000 fee). T+1/T+2 payout.
- Switcher: customer pays a merchant-bank-owned VA number → funds land directly in your bank (Rp 2,000 + bank fee). Setup requires the bank contract separately.
- Don't mix them in the same integration unless your finance team can reconcile two settlement streams.

## 3D Secure
- Keep 3DS enabled for all cross-border and high-risk card payments — the liability shift to the issuer is worth the ~5% auth-rate cost on legit customers.
- For recurring/subscription charges, use `card_on_file_type: "RECURRING"` + the `recurring_configuration` object; Xendit flags subsequent charges as merchant-initiated and skips 3DS where the scheme allows.

## Subscriptions
- Create a `Subscription Plan` first (weekly/monthly/yearly cadence, retry configuration) then initiate a transaction with the plan reference.
- Subscribe to `recurring.plan.activated`, `recurring.plan.inactivated`, `recurring.cycle.created`, `recurring.cycle.succeeded`, `recurring.cycle.failed` webhooks.
- Xendit auto-cancels a subscription on chargeback per the T&Cs — your app needs to detect that state and offer re-subscription rather than assuming the plan is still active.

## Chargebacks
- Subscribe to the card-dispute webhook. Lifecycle is initial (T+120) → retrieval (T+30) → chargeback (T+30) → arbitration (T+30, ~$500 fee).
- Respond with full evidence (order record, shipping proof, IP log, 3DS result) at the retrieval stage. Don't let disputes escalate to arbitration by default.

## Payouts / Disbursement
- Single endpoint handles ID/PH/MY/TH/VN with one payload — use it for cross-country payouts.
- Batch disbursement supports up to 10,000 transfers per batch (API or Excel upload). Processing window 07:00–23:00 local, 7 days/week.
- Always validate the destination account via Xendit's account-validation endpoint (name check) BEFORE disbursing to avoid unrecoverable misrouting.

## SDK choice
Prefer first-party libraries: `xendit-node`, `xendit-python` (Python 3.10+), `xendit-go` (v4), `xendit-php`, or `xendit-java`. All live under github.com/xendit and share API shape. Do not roll your own HTTP client unless you have a specific reason.

## Development workflow
- Use separate Test-mode API keys and a separate webhook token. Test-mode transactions are free.
- Test card PANs are published per country in the help center (for Indonesia, use `4000000000000002` for success and `4000000000000069` for expired card). E-wallet test flows use mock OTPs.
- Use ngrok or cloudflared to expose localhost for webhook testing; register the tunnel URL in the Test-mode dashboard.

## Error handling & reconciliation
- Treat every non-2xx from Xendit as retryable with exponential backoff (3 attempts, 1s/5s/30s), except for 4xx validation errors.
- Log every webhook's `id`, `event`, `amount`, `status`, and `external_id` to a ledger table. Reconcile daily against Xendit's settlement reports.
- Store Xendit's `id`, your `external_id`, channel, and settlement status on your order.

## Dashboard hardening
- Enforce 2FA on every admin account.
- Rotate the `x-callback-token` and `XENDIT_SECRET_KEY` on any staff departure.
- Give analysts read-only dashboard access; production integration keys belong to devops only.

Deliver a minimal working integration: Invoice create → hosted redirect → webhook with x-callback-token constant-time comparison → idempotent fulfilment. Do not add features beyond those requested.