Overlay 모드 (JS SDK)

Overlay 모드는 현재 페이지 안에서 CROSS Pay checkout runtime을 popup 또는 iframe widget으로 띄우는 방식입니다. 결제자는 가맹점 페이지를 벗어나지 않고 결제수단을 선택하고 승인합니다.

import { loadCrossPay } from '@nexus-cross/cross-pay-sdk';

const crossPay = await loadCrossPay();

const result = await crossPay.checkout({
  checkoutId: 'cs_abc123',
  idempotencyKey: 'ik_xyz',
  appearance: { theme: 'auto' },
  locale: 'ko',
  embeddedWallet: true,
});

embeddedWallet 기본값은 true입니다. false로 지정하면 crossx connector가 사용 가능한 환경에서도 embedded wallet/social row를 숨깁니다.

결제수단 목록을 페이지 일부에 embed하고, 별도 버튼으로 submit하는 방식입니다.

const crossPay = await loadCrossPay();
const widgets = crossPay.widgets({
  appearance: { theme: 'light' },
  locale: 'ko',
});

widgets.setAmount({ value: 50000, currency: 'KRW' });

const paymentMethods = widgets.renderPaymentMethods({
  selector: '#payment-methods',
  checkoutId: 'cs_abc123',
  idempotencyKey: 'ik_xyz',
  embeddedWallet: true,
});

paymentMethods.on('ready', () => console.log('widget ready'));
paymentMethods.on('paymentMethodSelect', selected => console.log(selected));

// 런타임 중 UI 옵션 변경
paymentMethods.update({ embeddedWallet: false });

const result = await widgets.submit({ idempotencyKey: 'ik_xyz' });

paymentMethods.destroy();
widgets.destroy();

idempotencyKey는 iframe URL에 넣지 않습니다. renderPaymentMethods()와 widgets.submit()의 bridge payload로만 전달합니다.

Theme와 locale

appearance.theme: light, dark, auto
locale: ko, en 등 runtime 지원 locale
auto theme는 prefers-color-scheme을 따릅니다.
런타임 변경은 THEME_CHANGE, LOCALE_CHANGE, ELEMENT_UPDATE 메시지로 전달됩니다.

widgets.setTheme('dark');
widgets.setLocale('en');

보안 요구사항

postMessage 수신 시 runtime origin과 source window를 모두 검증합니다.
SDK가 보내는 메시지는 pinned target origin으로만 발송합니다.
idempotencyKey, API key, token, PII를 iframe URL, return URL, analytics에 남기지 않습니다.
사용자가 결제창을 닫거나 취소하면 SDK는 USER_REJECTED 계열 에러로 처리될 수 있습니다. 사용자 취소와 결제 실패를 분리해 UI를 표시하세요.

Popup checkout​

Widget checkout​

Theme와 locale​

보안 요구사항​

Popup checkout

Widget checkout

Theme와 locale

보안 요구사항