Airwallex logo

Migrate to Checkout Session (pre-built payment page)

Migrate your Hosted Payment Page integration from Airwallex.js to Checkout Session.

Copy for LLMView as Markdown

Who this guide is for

Use this guide if you use the pre-built payment page (Hosted Payment Page) with redirectToCheckout()JS from Airwallex.js to collect payments.

What changes

IntegrationBeforeAfter
ServerCreate a PaymentIntent for payment checkoutCreate a Checkout Session
FrontendLoad Airwallex.js and call redirectToCheckout()Redirect to the session url
PaymentIntentYou create it before checkoutIn PAYMENT mode, the session creates it when checkout completes.
AppearancePass appearance in codeApply a Theme with ui_options.theme_id
Verify paymentRetrieve the PaymentIntent and handle payment webhooksRetrieve the Checkout Session and subscribe to Checkout Session events alongside your existing payment webhooks

Choose your checkout mode

Choose the mode that matches your checkout flow.

Use caseSession modeCompletion handling
Collect a one-off paymentPAYMENTVerify payment before marking the order paid or fulfilling it.
Collect a payment and save payment detailsPAYMENT with payment_options.payment_method_saveVerify payment and store the resulting payment_consent_id for later payments.
Save payment details without a paymentSETUPVerify setup and store the payment_consent_id. Setup completion does not mean an order was paid.

Before you begin

  1. Checkout Session is available in API version 2026-05-29 and later.
  2. You must have a sandbox account for testing.
  3. Payments must be enabled on your Airwallex account with at least one payment method activated under Payments > Payment methods in the web app.
  4. You must have your Client ID and API key from Developer > API keys in the sandbox web app. Enable read and write permissions for Checkout Session on the key.
  5. You must be able to make HTTP requests from a backend server. The Hosted Payment Page requires no Airwallex JavaScript SDK or frontend payment components. You only need to redirect the shopper to the checkout session URL.

Migration steps

Step 1: Migrate your PaymentIntent creation call

Replace Create a PaymentIntentAPI with Create a Checkout SessionAPI.

Before

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_intents/create \
2 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
6 "amount": 100,
7 "currency": "USD",
8 "merchant_order_id": "D202503210001",
9 "return_url": "https://www.example.com/success"
10 }'

After

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/create \
2 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "mode": "PAYMENT",
6 "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
7 "account_id": "{{YOUR_ACCOUNT_ID}}",
8 "currency": "USD",
9 "line_items": [
10 {
11 "quantity": 1,
12 "price": {
13 "currency": "USD",
14 "unit_amount": "100.00",
15 "product": {
16 "name": "T-shirt",
17 "unit": "unit"
18 }
19 }
20 }
21 ],
22 "payment_intent_data": {
23 "merchant_order_id": "D202503210001"
24 },
25 "success_url": "https://www.example.com/success",
26 "ui_options": {
27 "theme_id": "{{YOUR_THEME_ID}}"
28 }
29 }'

ui_options.theme_id is optional; omit it if you use the default appearance. Use a unique request ID for each new create request.

The response returns the session id and url. Store the session id against your order, then redirect the shopper to the url.

The url works only while the session status is ACTIVE. An unfinished session expires 1 hour after creation. Before creating a replacement, check whether the order has already been paid or has a payment in progress.

The PaymentIntent does not exist until the shopper completes checkout. If you currently store its ID when creating an order, store the session id and your merchant_order_id instead. Add the returned payment_intent_id after completion.

Step 2: Replace redirectToCheckout() with a redirect

Redirect the shopper to the session url. No Airwallex.js or other client SDK is needed for this flow.

Before

JavaScript
1payments.redirectToCheckout({ intent_id, client_secret, currency, successUrl });

After

JavaScript
1window.location.assign(checkoutSession.url);

You can also redirect from your server with an HTTP 302 response. Remove Airwallex.js if the pre-built payment page was its only use.

Step 3: Move your options

Move your existing settings to the Checkout Session request. Check the Checkout Session API referenceAPI for accepted values and the configuration available.

BeforeAfter
amountline_items, with an inline price for each item. If you already define Prices, you can also pass a price_id instead.
merchant_order_id on the PaymentIntentpayment_intent_data.merchant_order_id
successUrl and PaymentIntent return_urlsuccess_url
appearanceA Theme, applied with ui_options.theme_id
layoutui_options.layout
submitTypeui_options.submit_type
localelocale
methods[]payment_options.payment_method_types
country_codecustomer_data.country_code
requiredBillingContactFieldsReview customer_data_collection for the fields your integration requires
Customer details or an existing customercustomer_data, or customer_id for an existing customer
Save payment detailspayment_options.payment_method_save during payment, or SETUP without payment

Step 4: Update payment verification

Retrieve the Checkout SessionAPI using the ID stored against your order and check for status: "COMPLETED".

Shell
1curl -G https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/{{CHECKOUT_SESSION_ID}} \
2 -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response includes the payment_intent_id of the PaymentIntent the session created. Use Retrieve a PaymentIntentAPI when you need the underlying payment details.

In Developer > Webhooks in the Airwallex web app, add these three Checkout Session events to your webhook subscription alongside your existing payment events:

  • checkout_session.created: Track when a Checkout Session is created.
  • checkout_session.cancelled: Track when a Checkout Session is cancelled.
  • checkout_session.completed: Track when checkout completes. For most payment methods, use this event to trigger order fulfillment.

For direct debit payment methods, processing is asynchronous. Keep listening for payment_intent.succeeded and wait for this event before fulfilling the order; checkout completion alone does not confirm that the payment has succeeded.

The shopper may close the browser before the success_url redirect happens, so the redirect must not be your only payment confirmation. For subscription and endpoint setup, see Listen for webhook events.

Save payment details without a payment

For a setup-only flow, create a session in SETUP mode. Customer creationAPI remains unchanged.

Existing saved-payment-details flowCheckout Session
Configure customer and consent details for SDK checkoutCreate a SETUP session with the required customer and consent fields
payment_consent.next_triggered_by in redirectToCheckout()payment_options.payment_method_save.next_triggered_by
Redirect with redirectToCheckout()Redirect to the session url
Read the consent result from your existing flowRetrieve the completed session and store payment_consent_id

Sample request

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/create \
2 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "mode": "SETUP",
6 "request_id": "e193b51e-2c2a-435a-a03c-8d86bfa083fe",
7 "account_id": "{{YOUR_ACCOUNT_ID}}",
8 "currency": "USD",
9 "customer_id": "{{CUSTOMER_ID}}",
10 "success_url": "https://www.example.com/payment-details/success",
11 "payment_options": {
12 "payment_method_save": {
13 "next_triggered_by": "MERCHANT"
14 }
15 }
16 }'

Redirect to the returned url, as in Step 2. Persist the session-to-customer association before redirecting. After checkout, retrieve the session; when setup has completed, verify the customer association and store payment_consent_id against that customer.

Charging the saved payment method later remains a separate payment operation. Use Create a PaymentIntentAPI and Confirm a PaymentIntentAPI as described in Save and reuse payment details.

Test and go live

Create a new session for each test case in the sandbox and redirect to its own url. Run at least one successful card payment, one failed payment, and one 3D Secure payment. See Test your integration for test card numbers.

Was this page helpful?