본문으로 건너뛰기

Redirect 모드

Redirect 모드는 결제자를 CROSS Pay hosted checkout으로 이동시킨 뒤, 결제 결과를 가맹점의 성공/실패 URL 또는 앱 scheme으로 돌려보내는 방식입니다. 모바일 브라우저, 앱 WebView, 외부 PG 화면 전환이 필요한 결제수단에 적합합니다.

동작 흐름​

URL에 실어도 되는 값​

초기 checkout URL에는 routing/UI용 비밀이 아닌 값만 포함합니다.

허용금지
checkoutId, parentOrigin, theme, locale, country, redirect_url, redirect_schemeidempotencyKey, API key, token, PII, 주문 확정에 필요한 secret

idempotencyKey는 URL query string, fragment, analytics, log, screenshot에 노출하지 않습니다. SDK/runtime bridge나 신뢰된 HTTPS body로만 전달합니다.

Redirect URL 검증​

SDK는 redirect 계열 URL을 열기 전에 위험한 scheme을 거부합니다.

  • 거부: javascript:, data:, ftp:, blob:, malformed URL
  • 허용: 운영 HTTPS origin, 지원 플랫폼의 loopback HTTP, 명시적으로 등록된 native scheme
  • merchant allowlist에는 전체 HTTPS origin을 등록합니다. v1.0부터 allowedHosts는 제거되고 allowedRedirectOrigins만 사용합니다.
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',
});

결과 처리​

Hosted checkout은 browser result를 postMessage 또는 redirect로 전달할 수 있습니다. Redirect 결과는 URL fragment(#...)를 사용해 Referer와 서버 로그 노출을 줄입니다.

주문 확정은 서버에서만

브라우저 결과는 사용자가 위조할 수 있습니다. 주문 확정, 상품 지급, 디지털 자산 지급은 반드시 webhook 수신 또는 GET /v1/payments/{payment_id} 서버 조회 후 처리하세요.

country hint​

POST /v1/payments에 country: 'KR'을 보내면 최초 checkout_url에만 ?country=KR이 붙습니다. 이 값은 billing/default UI hint이며 세금, 라우팅, 인증 결정을 대신하지 않습니다.