Billing Checkout Elements

Billing Checkout Elements let you embed a composable Billing Checkout on your website. Shoppers enter their details and pay without leaving your site, while Airwallex handles validation and processing. On success, Airwallex creates the same Billing resources as Hosted Billing Checkout (customer, payment source, subscription or invoice).

This tutorial uses ui_mode=ELEMENTS. For a redirect to Airwallex, see Hosted Billing Checkout. For the full Hosted Billing Checkout UI in an iframe, see Embedded Billing 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 (mode, line items, tax, success_url, and so on), and set:

• ui_mode=ELEMENTS

The response includes client_secret. Use this value to initialize the checkout on the client. Do not redirect to the url field when using ELEMENTS.

Choose your billing mode

Set the mode field to match your use case:

• PAYMENT: Collect a one-off payment.
• SUBSCRIPTION: Start a subscription with recurring prices or a rate card.
• SETUP: Collect and save a payment method for future payments.

For line items, success URLs, and example request bodies, follow Hosted Billing Checkout and add "ui_mode": "ELEMENTS" to the JSON body.

Example: create a Billing Checkout for Elements (PAYMENT 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": "38c18a4b-3758-40b6-9615-d123b94058f1",
6    "mode": "PAYMENT",
7    "ui_mode": "ELEMENTS",
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_hkdmfsd9mhax0zj2fht",
15        "quantity": 10
16      }
17    ]
18  }'

Mount Billing Checkout Elements

Initialize Airwallex.js with billing enabled, create a Checkout instance with the client_secret, mount the paymentForm element, and listen for lifecycle events.

For the full API surface, see Billing Checkout ElementsJS in the Airwallex.js reference.

1import { init } from '@airwallex/components-sdk';
2
3const { billing } = await init({
4  env: 'demo',
5  enabledElements: ['billing'],
6});
7
8const checkout = await billing.createCheckout({
9  client_secret: 'replace-with-your-checkout-client-secret',
10});
11
12const paymentForm = await checkout.createElement('paymentForm');
13paymentForm.mount('payment-form');
14
15paymentForm.on('ready', () => {
16  // Hide your loading state.
17});
18
19paymentForm.on('success', () => {
20  // Navigate to your post-checkout page (also configure success_url).
21});
22
23paymentForm.on('error', ({ code, message }) => {
24  console.error('Billing Checkout error:', code, message);
25});

Add a container element with id payment-form on your page.

After checkout completes

When the Billing Checkout reaches COMPLETED, Airwallex creates the customer, payment source, and subscription or invoice according to the mode you selected—the same as Hosted Billing Checkout. Use success_url to send shoppers to your confirmation page.

Billing Checkout statuses

See Billing Checkout statuses in the Hosted Billing Checkout guide.