Embedded Checkout Element

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+.

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.

client_secret

requiredstring

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

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

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:

code

requiredenum

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?