Embedded Billing Checkout

Embedded Billing Checkout embeds the full Hosted Billing Checkout experience in an iframe on your page. Shoppers complete payment or subscription setup without a full-page redirect, while Airwallex creates the same Billing resources as Hosted Billing Checkout.

This tutorial uses ui_mode=EMBEDDED. For a composable checkout form on your page, see Billing Checkout Elements. To compare all Billing Checkout options, see Checkout.

Before you begin

• Obtain your access tokenAPI by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
• Check out Supported currencies for supported regions and currencies.
• Install Airwallex.jsJS (@airwallex/components-sdk) on your checkout page.

Create a Billing Checkout

Call Create a Billing CheckoutAPI from your server when the customer is ready to pay. Use the same request fields as Hosted Billing Checkout, and set:

• ui_mode=EMBEDDED

The response includes client_secret. Use this value to mount the embedded checkout. Do not redirect to the url field when using EMBEDDED.

For line items, modes, and example bodies, follow Hosted Billing Checkout and add "ui_mode": "EMBEDDED" to the JSON body.

Example: create a Billing Checkout for Embedded Billing Checkout (SUBSCRIPTION mode)

1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing_checkouts/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "0c3efb21-a986-4ef1-92d0-e0effa5b323e",
6    "mode": "SUBSCRIPTION",
7    "ui_mode": "EMBEDDED",
8    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
9    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ",
10    "success_url": "https://example.com/success",
11    "back_url": "https://example.com/back",
12    "line_items": [
13      {
14        "price_id": "pri_hkdmfsd9mhax0rfemfq",
15        "quantity": 1
16      }
17    ]
18  }'

Mount Embedded Billing Checkout

Initialize Airwallex.js with billing enabled, create the embeddedCheckout element with the client_secret, and mount it into a container with a defined height.

For parameters and events, see Embedded Checkout ElementJS in the Airwallex.js reference.

1import { init, createElement } from '@airwallex/components-sdk';
2
3const { billing } = await init({
4  env: 'demo',
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('ready', () => {
15  // Hide your loading state.
16});
17
18element.on('success', () => {
19  // Navigate to your post-checkout page (also configure success_url).
20});
21
22element.on('error', ({ code, message }) => {
23  console.error('Embedded Billing Checkout error:', code, message);
24});

Use a container with an explicit height so the iframe does not collapse, for example:

1<div id="embedded-checkout" style="height: 720px"></div>

After checkout completes

When the Billing Checkout reaches COMPLETED, Airwallex creates Billing customers, payment sources, and subscriptions or invoices according to your mode. See Billing Checkout statuses.