Hosted Billing Checkout

Hosted Billing Checkout allows you to use a pre-built, configurable Airwallex-hosted checkout page to enable a seamless purchase experience for your customers.

This tutorial guides you through the steps to build a Hosted Billing Checkout integration.

Before you begin

• Obtain your access token API 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.

Create a Billing Checkout

First, call Create a Billing Checkout API from your server side. A Billing Checkout manages the setup and lifecycle of an Airwallex-hosted customer checkout experience, enabling customers to confirm and pay for line items or set up payment details for future transactions.

Each time a customer initiates a purchase, create a new Billing Checkout and redirect them to an Airwallex-hosted URL to complete the checkout. Upon successful payment, relevant resources such as Customer, Payment Source, and Subscription are automatically created.

Recommended integration flow

1. The customer clicks Checkout or Subscribe on your website or app.
2. Your server calls Create a Billing Checkout API.
3. Your app redirects the customer to the url returned in the response.

Create the Billing Checkout when the customer is ready to pay — not in advance. Billing Checkout is designed for real-time checkout flows, not as a shareable long-lived payment link.

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.
• SETUP: Collect and save a payment method for future payments.

Add products and prices

You can add multiple items to the checkout by adding price_id and quantity in the line_items request field. The price_id can be retrieved via Get list of prices API, or in the price drawer of the product page in the Airwallex web app.

Set up success and back URLs

Set up URLs for success and back pages with the success_url and back_url request field, and ensure they’re publicly accessible.

The customer will be directed to the success page after the checkout completion. If the back page is set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this page.

Redirect to Billing Checkout

After a Billing Checkout object is successfully created, redirect your customer to the url of the Billing Checkout object to complete the checkout in the browser.

On completion of the checkout flow, the customer’s payment details are captured in a Payment Method API object. In addition, Airwallex-hosted Checkout automatically creates a subscription for you.

Billing Checkout request for mode PAYMENT

1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/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    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
8    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ",
9    "success_url": "https://example.com/success",
10    "back_url": "https://example.com/back",
11    "line_items": [
12      {
13        "price_id": "pri_hkdmfsd9mhax0zj2fht",
14        "quantity": 10
15      }
16    ],
17    "invoice_data": {
18      "default_tax_percent": 10,
19      "memo": "Thank you for your purchase!"
20    }
21  }'

Billing Checkout request for mode SUBSCRIPTION

1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/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    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
8    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ",
9    "success_url": "https://example.com/success",
10    "back_url": "https://example.com/back",
11    "line_items": [
12      {
13        "price_id": "pri_hkdmfsd9mhax0rfemfq",
14        "quantity": 10
15      }
16    ],
17    "subscription_data": {
18      "days_until_due": 5,
19      "default_tax_percent": 10,
20      "default_invoice_template": {
21        "invoice_memo": "Thank you for your subscription!"
22      },
23      "duration": {
24        "period": 12,
25        "period_unit": "MONTH"
26      }
27    }
28  }'

Billing Checkout request for mode SETUP

1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/billing_checkouts/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "22532b8a-eeb1-477e-8e76-a3457473095a",
6    "mode": "SETUP",
7    "currency": "USD",
8    "billing_customer_id": "bcus_hkdmz2plrhawrfeqdth",
9    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
10    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ",
11    "success_url": "https://example.com/success",
12    "back_url": "https://example.com/back"
13  }'

Update a Billing checkout

You can call Update a Billing Checkout API to update the metadata of a Billing Checkout object to link a cart, order or customer in your system to it.

Cancel a Billing Checkout

A Billing Checkout in OPEN status can be cancelled. Once cancelled, the customer will no longer be able to complete the checkout flow and will see an error message when attempting to load it.

Billing checkout statuses

Billing checkout can have multiple statuses, depending on their stage in the checkout lifecycle.

FAQ

Can I extend the Billing Checkout expiration time?
No. Billing Checkout URLs expire 1 hour after creation. Expiry is fixed and cannot be configured via the API. Create the checkout when the customer is ready to pay, not in advance.

Can I email a Billing Checkout link to a customer to pay later?
No. Billing Checkout is not designed as a shareable long-lived link. If you need to send a specific customer a link to pay asynchronously, create and send a digital invoice instead.

What should I do if a Billing Checkout expires?
Create a new Billing Checkout when the customer is ready to complete payment. Do not reuse an expired URL.

Is Billing Checkout the same as a Payment Link?
No. Payment Links are a separate Payments product for collecting one-off payments. Payment Links are not integrated with Billing and cannot create Billing invoices or subscriptions. Use Hosted Billing Checkout when you need Billing to create customers, payment sources, invoices, or subscriptions automatically.

Does timezone affect Billing Checkout expiry?
No, if you follow the recommended integration flow. Create the Billing Checkout on your server when the customer initiates checkout in their session. Timezone differences are not a concern when checkout is created at payment time rather than hours in advance.