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.
Billing Checkout currently accepts cards, AliPay, ApplePay and GooglePay as payment methods — support for more local payment methods will be available soon.
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
Skip this step if the mode is SETUP.
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 verified Payment Consent API object. In addition, Airwallex-hosted Checkout automatically creates a subscription for you.
Billing Checkout request for mode PAYMENT
Billing Checkout request for mode SUBSCRIPTION
Billing Checkout request for mode SETUP
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 ACTIVE 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.
| Status | Description |
|---|---|
ACTIVE |
Billing Checkout is available for the customer purchase. |
COMPLETED |
The payment has been completed or the payment method has been verified. |
CANCELLED |
The merchant has cancelled the Billing Checkout via Cancel Billing Checkout API. |
EXPIRED |
The status automatically transitions from ACTIVE to EXPIRED after 1 hour if the purchase has not been completed.
|