Routing

When you call POST /v1/payments, the gateway chooses which PSP to route to using three inputs from the request: currency, method, and the calling app’s mode.

Resolution order

1. Method override (absolute) — If method is one of the registered overrides, the gateway routes directly there regardless of currency or app allowlist:
   • method=polar → Polar.sh
   • method=paypal → PayPal
2. IDR + method match — If currency=IDR, the gateway walks an ordered preference list for that method and returns the first PSP that:
   • is in the app’s allowed_providers allowlist (or the allowlist is empty), AND
   • has a driver registered for the calling app’s mode.
3. Non-IDR, no override — Falls through to the configured global PSP (Paddle today, when wired). Gated by allowlist.
4. No match — 422 no provider supports method=… for currency=… (production) or fall through to mock (when MOCK_NONIDR_FALLBACK=1 in dev).

IDR preference list

Today the gateway has only NICEPAY in the IDR list (DOKU has been removed):

Method	Preference order
qris	NICEPAY
va_bca	NICEPAY
va_mandiri	NICEPAY
va_bni	NICEPAY
va_bri	NICEPAY
va_permata	NICEPAY

If a future direct-PJP integration lands (e.g. a BCA QRIS direct merchant), the table extends naturally — qris would prefer the direct rail first, fall back to NICEPAY for unsupported wallets. Products keep using method=qris; the gateway picks.

Mode-aware routing

The IDR walk skips PSPs that don’t have a driver registered for the calling app’s mode. Practical example:

• App is mode=sandbox
• DOKU is registered only for live (no sandbox creds in env)
• NICEPAY is registered only for sandbox
• Routing for (IDR, qris, sandbox) returns NICEPAY (skipping DOKU)

This means “what PSP serves your request” depends on (1) the routing table, (2) the app’s allowlist, and (3) which credential sets the operator has populated for which PSP.

Per-app allowlist

Each app has an allowed_providers text array. Empty = “all registered providers allowed” (the multi-tenant default). Non-empty restricts the app to listed providers only.

Useful for narrowing a product to a single PSP:

update apps set allowed_providers = '{nicepay}' where name = 'posz-live';

posz-live will now reject any request that would route to a non-NICEPAY rail (422 provider X not allowed for this app).

Method allowlist (per app, per provider)

The allowed_methods JSONB is finer-grained: {"nicepay": ["qris", "va_bca"]} lets the app use NICEPAY for QRIS and BCA VA only. Empty = no restriction.

Useful when one product should only do QRIS and another only does VA, both on the same NICEPAY merchant.

Inspecting routing decisions

The gateway has a routing-preview endpoint for debugging without creating a payment:

GET /v1/routing/preview?currency=IDR&method=qris
X-PAY-* signed

Returns the PSP that would be picked + which check filtered out alternatives.

Method overrides bypass everything

method=polar and method=paypal ignore the per-app allowlist by design. They’re absolute escape hatches — useful when a product has explicit reason to force a rail (e.g., USD product that wants to bill via PayPal even though Polar is the default for non-IDR).

If you don’t want a product to be able to use a method override, just don’t tell its team about it. There’s no per-app blocklist for overrides today.