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
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生成背景
我不会
常规验证
确定