Skip to main content

Overlay Mode (JS SDK)

Overlay Mode loads the CROSS Pay checkout runtime inside the current page as either a popup or an iframe widget. The payer selects a payment method and authorizes the payment without leaving the merchant site.

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 defaults to true. Setting it to false hides the embedded wallet/social row even when the crossx connector is available.

Widget checkout​

Embed the payment method list inside part of the page and submit it via a separate button.

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));

// Change UI options at runtime
paymentMethods.update({ embeddedWallet: false });

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

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

idempotencyKey is never placed in the iframe URL. It is delivered only as part of the bridge payload for renderPaymentMethods() and widgets.submit().

Theme and locale​

  • appearance.theme: light, dark, auto
  • locale: runtime-supported locales such as ko, en
  • The auto theme follows prefers-color-scheme.
  • Runtime changes are delivered through THEME_CHANGE, LOCALE_CHANGE, and ELEMENT_UPDATE messages.
widgets.setTheme('dark');
widgets.setLocale('en');

Security requirements​

  • When receiving postMessage, validate both the runtime origin and the source window.
  • Messages sent by the SDK target only the pinned target origin.
  • Never leave idempotencyKey, API keys, tokens, or PII in iframe URLs, return URLs, or analytics.
  • When the payer closes or cancels the checkout, the SDK may surface a USER_REJECTED class of error. Display distinct UI for user cancellations vs payment failures.