Use a pre-built payment page (with Checkout Session)Early access

Complete a minimal end-to-end online payment in the sandbox environment using a Checkout Session and the Airwallex-hosted payment page. By the end of this tutorial, you will have created a Checkout Session, redirected a shopper to the hosted payment page, and verified a successful test payment in the sandbox.

You'll do the following:

• Authenticate to Airwallex and generate an access token.
• Create a Checkout Session on your server.
• Redirect the shopper to the hosted payment page URL.
• Verify the result in the Airwallex web app, via API, or with webhooks.

Before you begin

• You must have a sandbox account for testing.
• Payments must be enabled on your Airwallex account with at least one payment method activated under Payments > Payment methods in the web app.
• You must have your Client ID and API key from Developer > API keys in the sandbox web app.
• You must have at least one product with a non-recurring price. Checkout Session line items reference prices by price_id.
• You must be able to make HTTP requests from a backend server. The hosted payment page requires no frontend code or JavaScript SDK.

Step 1: Get an access token on your server

Payment APIs require an access token generated from your Client ID and API key.

Request

1curl -X POST https://api.sandbox.airwallex.com/api/v1/authentication/login \
2  -H 'Content-Type: application/json' \
3  -H 'x-api-key: {{YOUR_SANDBOX_API_KEY}}' \
4  -H 'x-client-id: {{YOUR_SANDBOX_CLIENT_ID}}'

Response

1{
2  "token": "your_access_token",
3  "expires_at": "2026-12-31T23:59:59Z"
4}

Save the token in your backend and reuse it until it expires.

Step 2: Create a Checkout Session on your server

A Checkout Session represents one shopper's journey through the hosted checkout. It captures what the shopper is buying, the payment methods offered, and where the shopper is sent after checkout.

When the shopper begins checkout, call Create a Checkout SessionAPI on your server with:

• mode: PAYMENT for a one-off payment.
• request_id: A unique ID for the request.
• currency: The checkout currency.
• line_items: The items the shopper is purchasing, referencing your prices by price_id.
• success_url: Where Airwallex redirects the shopper after checkout completes.
• invoice_creation.enabled: Set to false to collect the payment without creating an invoice.

Request

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    "currency": "USD",
8    "success_url": "https://www.example.com/order/D202503210001/success",
9    "line_items": [
10      {
11        "price_id": "{{YOUR_PRICE_ID}}",
12        "quantity": 1
13      }
14    ],
15    "invoice_creation": {
16      "enabled": false
17    }
18  }'

Response

The API returns a Checkout Session object. See Create a Checkout SessionAPI for the full response schema.

1{
2  "id": "your_checkout_session_id",
3  "mode": "PAYMENT",
4  "status": "ACTIVE",
5  "currency": "USD",
6  "url": "your_hosted_checkout_url",
7  "created_at": "2026-09-28T06:00:00+0000",
8  "expires_at": "2026-09-28T07:00:00+0000"
9}

For Step 3, you will need:

• id: The Checkout Session ID, used to retrieve the session later.
• url: The hosted payment page URL to redirect the shopper to. It is only present while the session is ACTIVE.

Step 3: Redirect the shopper to the hosted payment page

Return the session url to your frontend and redirect the shopper:

1// Redirect the shopper to the Airwallex-hosted payment page
2window.location.assign(checkoutSession.url);

You can also redirect directly from your server with an HTTP 302 response. No Airwallex.js or other client SDK is required.

When the page loads:

1. The hosted payment page shows the payment methods available for the session's currency and the shopper's location.
2. The shopper selects a method, enters their details, and completes any 3D Secure authentication when required.
3. Airwallex redirects the shopper to your success_url after checkout completes.

The session creates the underlying Payment Intent when the shopper completes checkout, so you do not need to create or confirm a Payment Intent yourself.

Step 4: Test with sandbox cards and verify the payment

Use test cards in the sandbox

Use the test card numbers to test success, failure, and 3DS flows. Create a new Checkout Session for each test case and redirect to its new url.

Run at least:

• One successful card payment.
• One failed payment (invalid card or insufficient funds).
• One 3DS scenario.

Verify the Checkout Session status

Verify that the payment worked in one of these ways:

1. Airwallex web app

   Go to Payments > Payments Activity in the web app and confirm that your payments appear.

2. Retrieve the Checkout Session via API

   Shell

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

   Check for status: "COMPLETED" on a successful test payment. The response includes the payment_intent_id created for the payment.

   JSON

   1{
   2  "id": "your_checkout_session_id",
   3  "mode": "PAYMENT",
   4  "status": "COMPLETED",
   5  "payment_intent_id": "int_your_payment_intent_id",
   6  "completed_at": "2026-09-28T06:30:00+0000"
   7}

3. Webhooks (recommended for production)

   Configure a webhook endpoint for payment_intent.succeeded and related events. Use it to trigger order fulfillment, emails, or internal workflows instead of relying only on the success_url redirect—the shopper may close the browser before the redirect happens. For details, see Listen for webhook events.

Next steps

• Customize the checkout page

  Apply your own theme with ui_options.theme_id, control the payment method layout with ui_options.layout, and set the submit button label with ui_options.submit_type. See the Checkout Session API referenceAPI for all options.

• Save payment details for future payments

  Configure payment_options.payment_method_save to store the shopper's payment method during checkout. See Save and reuse payment details.

• Sell subscriptions or invoices

  Use mode SUBSCRIPTION or enable invoice_creation to manage recurring billing and invoicing with Airwallex Billing.

• Try other integration options

  Compare the pre-built payment page, Drop-in element, Embedded Elements, and more in Web checkout overview.

Complete Test your integration before going live.