Embedded Checkout Element - Airwallex.js

Search documentation

Ask Kai

Ask Kai

Embedded Checkout Element

Copy for LLMView as Markdown

The Embedded Checkout Element lets you embed the full Airwallex-hosted checkout experience directly within your web page (via an iframe), allowing shoppers to complete their payment or subscriptions setup without being redirected to a separate Airwallex-hosted payment page.

Browser support

Embedded Checkout supports Google Chrome 102+, Microsoft Edge 102+, and Safari 26.2+ — the versions that ship the Navigation API and support Apple Pay inside cross-origin iframes.

createElement('embeddedCheckout', options)

Use this function to create an instance of an individual Element.

Parameters

type required'embeddedCheckout'

The type of element you are creating.

options requiredEmbeddedCheckoutOptions

Options for creating embeddedCheckout Element.

HideEmbeddedCheckoutOptions properties

client_secret requiredstring

The client_secret of the Billing Checkout that the element should render.

Obtain this value by calling the Airwallex Billing Checkout APIAPI from your server.

merchantOrigin optionalstring

Origin of the merchant's top-level page, used for Apple Pay domain validation. Defaults to the current page origin; set this when the SDK is itself embedded in a nested iframe so the top-level origin still reaches Apple Pay.

Returns

EmbeddedCheckoutElement | null

createElement('embeddedCheckout', options)

1import { init, createElement } from '@airwallex/components-sdk';
2

3const { billing } = await init({
4  env: 'demo', // Choose the Airwallex environment ('demo' or 'prod')
5  enabledElements: ['billing'],
6});
7

8const element = await createElement('embeddedCheckout', {
9  client_secret: 'replace-with-your-checkout-client-secret',
10});
11

12element.mount('embedded-checkout');
13

14element.on('success', () => {
15  // Navigate the merchant page to its post-checkout state.
16});
17

18element.on('error', ({ code, message }) => {
19  // Surface or log the error.
20  console.error('Embedded Checkout error:', code, message);
21});

destroy()

Permanently destroys the Element instance. The instance cannot be reused afterwards. Call createElement() again if you want to render the Embedded Checkout later.

destroy()

1element.destroy();

mount(domElement)

Mounts the Element to your HTML DOM. Safe to call once per element instance; mounting the same instance twice has no effect.

Parameters

domElement requiredstring | HTMLElement

The container to mount into. Pass either the id of an existing DOM element, or the HTMLElement itself. The container must have a resolvable height, otherwise the iframe collapses.

mount(domElement)

1// Ensure the container has a resolvable height, e.g.
2// <div id="checkout" style="height: 720px"></div>
3

4// 1. mount by container id
5element.mount('checkout');
6

7// 2. mount by container element
8const container = document.getElementById('checkout');
9element.mount(container);

on('ready', handler)

Emitted when the embedded checkout is ready for customer interaction.

Parameters

type required'ready'

The event name.

handler requiredfunction

Callback invoked every time the event fires.

on('ready', handler)

1element.on('ready', () => {
2  // The embedded checkout is ready; hide your own loading state.
3});

on('success', handler)

Emitted when the checkout has been completed successfully. Please note that some local payment methods may trigger browser navigation before a success event can be delivered. As a result, the current page may no longer be available when the payment completes.

Parameters

type required'success'

The event name.

handler requiredfunction

Callback invoked every time the event fires.

on('success', handler)

1element.on('success', () => {
2  // Navigate the merchant page to its post-checkout state.
3});

on('error', handler)

Emitted on any embedded-checkout error.

Parameters

type required'error'

The event name.

handler requiredfunction

Callback invoked every time the event fires.

The handler receives an object with the following properties:

Hideobject properties

code requiredenum

Show possible enums

secretExpired

invalidSecret

serviceUnavailable

paymentFailed

unsupportedBrowser

unsupportedElement

unknown

invalidContainer

invalidUiMode

message optionalstring

type optional'embeddedCheckout'

on('error', handler)

1element.on('error', ({ code, message }) => {
2  // Surface or log the error.
3  console.error('Embedded checkout error:', code, message);
4});

unmount()

Removes the Element from the DOM while keeping the instance available for remounting. Use this when you want to temporarily hide the checkout and display it again later. To permanently remove the Element and release its resources, call destroy() instead.

unmount()

1element.unmount();

Was this page helpful?

YesNo

Ask AI

Docs AI Assistant answers questions using sources from Airwallex Docs, Airwallex API, Airwallex JS, and other public Airwallex knowledge bases. To get your questions answered right from your coding agent, try our Developer MCP server.

Hi, how can I help?

How do I start as a merchant?How to create a billing customer?

Deep thinking

Powered by

kapa.ai

protected by reCAPTCHA

Cookies on the Airwallex website

We use cookies to enhance your website experience at Airwallex. Visit our cookie policy to learn more and manage your preferences at any time.

I accept

验证码

安全验证

返回

拖动下方滑块完成拼图

确定

AI生成背景

我不会

常规验证

确定