Redirect Mode

Redirect Mode sends the payer to the CROSS Pay hosted checkout and then returns them to the merchant's success/fail URL or app scheme once the payment completes. It is well suited to mobile browsers, in-app WebViews, and payment methods that require a full-page transition to an external PG.

How it works

Values safe to put in the URL

The initial checkout URL must contain only non-secret routing/UI values.

Allowed	Forbidden
checkoutId, parentOrigin, theme, locale, country, redirect_url, redirect_scheme	idempotencyKey, API key, token, PII, any secret required to confirm the order

Never expose idempotencyKey in URL query strings, fragments, analytics, logs, or screenshots. It must be transmitted only over the SDK/runtime bridge or a trusted HTTPS body.

Redirect URL validation

The SDK rejects dangerous schemes before opening any redirect-class URL.

• Rejected: javascript:, data:, ftp:, blob:, malformed URLs
• Allowed: production HTTPS origins, loopback HTTP on supported platforms, explicitly registered native schemes
• The merchant allowlist must contain full HTTPS origins. Starting with v1.0, allowedHosts is removed and only allowedRedirectOrigins is used.

await crossPay.checkout({
  checkoutId,
  idempotencyKey,
  successUrl: 'https://shop.example.com/pay/success',
  failUrl: 'https://shop.example.com/pay/fail',
  redirectUrl: 'https://shop.example.com/pay/return',
  redirectScheme: 'myshop://pay/return',
});

Handling the result

The hosted checkout can deliver the browser result via postMessage or via redirect. Redirect results use a URL fragment (#...) to reduce exposure in Referer headers and server logs.

Confirm orders only on the server

Browser results can be forged by the user. Always confirm orders, fulfill goods, and disburse digital assets after receiving a webhook or fetching GET /v1/payments/{payment_id} server-side.

country hint

Sending country: 'KR' to POST /v1/payments attaches ?country=KR to the initial checkout_url only. The value is a billing/default UI hint and does not substitute for tax, routing, or authentication decisions.