Airwallex logo
Airwallex logo

Quickstart: Your first online payment

Copy for LLMView as Markdown

Complete a minimal end-to-end online payment in the sandbox environment using Airwallex.js and Airwallex-hosted payment page. By the end of this tutorial, you will have a working checkout page and a successful test payment in the sandbox.

You'll do the following:

  • Authenticate to Airwallex and generate an access token.
  • Create a PaymentIntent on your server.
  • Build a checkout page that redirects to Airwallex-hosted payment page using Airwallex.js.
  • Verify the result in the Airwallex web app, via API, or with webhooks.

The Airwallex Developer MCP server can accelerate your integration. Connect your coding assistant to the MCP server for API and SDK guidance while you build.

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 tab in the web app.
  • You must have your Client ID and API key generated from Developer > API keys tab in the sandbox web app.
  • You must be able to make HTTP requests from a backend server.

Step 1: Get an access token on your server

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

Request (cURL)

Bash
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/authentication/login' \
3--header 'Content-Type: application/json' \
4--header 'x-api-key: YOUR_SANDBOX_API_KEY' \
5--header 'x-client-id: YOUR_SANDBOX_CLIENT_ID' \

Response

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

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

Keep your Client ID, API key, and access tokens on your server only. Do not expose them in frontend code or mobile apps.

Step 2: Create a PaymentIntent on your server

A PaymentIntent represents your intent to collect a specific amount from a shopper. Airwallex-hosted payment page uses it to render the checkout form and process the payment.

Call Create a PaymentIntent API with request_id, amount, currency, and merchant_order_id. The customer object is optional but helps pre-fill the hosted checkout.

Request

Shell
1curl --request POST \
2  https://api-demo.airwallex.com/api/v1/pa/payment_intents/create \
3  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
7    "amount": 100,
8    "currency": "USD",
9    "merchant_order_id": "D202503210001",
10    "return_url": "https://www.airwallex.com",
11    "customer": {
12      "email": "[email protected]",
13      "first_name": "John",
14      "last_name": "Doe"
15    }
16  }'

Response

The API returns a PaymentIntent object. See Create a PaymentIntent API for the full response schema.

JSON
1{
2  "id": "int_your_payment_intent_id",
3  "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
4  "amount": 100,
5  "currency": "USD",
6  "merchant_order_id": "D202503210001",
7  "status": "REQUIRES_PAYMENT_METHOD",
8  "created_at": "2024-01-30T03:31:29+0000",
9  "updated_at": "2024-01-30T03:31:29+0000",
10  "client_secret": "your_client_secret"
11}

For the checkout page in Step 3, you will need:

  • id: The PaymentIntent ID
  • client_secret: Used on the client side to complete the payment securely

Step 3: Build a basic checkout page

Build a simple HTML page with a Pay Now button that redirects to the payment page hosted by Airwallex using Airwallex.js. Initialize the SDK and call payments.redirectToCheckout() when the shopper clicks the button.

Add the SDK and a Pay Now button

HTML
1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="utf-8" />
5  <title>Quickstart checkout</title>
6  <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
7</head>
8<body>
9  <h1>Hosted payment page (HPP) integration</h1>
10  <p>
11    The following button redirects the customer to an Airwallex-hosted payment page.
12  </p>
13  <!-- Add a checkout button -->
14  <button id="hpp">Pay Now</button>
15  <script async>
16    const intent_id = 'replace-with-your-intent-id';
17    const client_secret = 'replace-with-your-client-secret';
18    const currency = 'replace-with-your-currency';
19

20    (async () => {
21      // Initialize Airwallex.js with the appropriate environment
22      const { payments } = await window.AirwallexComponentsSDK.init({
23        env: 'demo', // 'demo' | 'prod'
24        enabledElements: ['payments'],
25      });
26

27      const redirectHppForCheckout = () => {
28        payments.redirectToCheckout({
29          env: 'demo',
30          mode: 'payment',
31          currency, // Required
32          intent_id, // Required
33          client_secret, // Required
34          successUrl: 'https://www.example.com/success', // Must be HTTPS
35          appearance: {
36            mode: 'light',
37            variables: { colorBrand: '#612FFF' },
38          },
39        });
40      };
41

42      document.getElementById('hpp').addEventListener('click', redirectHppForCheckout);
43    })();
44  </script>
45</body>
46</html>

Replace replace-with-your-intent-id, replace-with-your-client-secret, and replace-with-your-currency with the values from the PaymentIntent you created in Step 2, and set successUrl to your own HTTPS success page.

When the shopper clicks Pay Now:

  1. They are redirected to a secure, Airwallex-hosted checkout page.
  2. They can select a payment method, enter details, and complete any 3D Secure (3DS) authentication.
  3. They are redirected back to your successUrl if configured, or to the PaymentIntent return_url otherwise.

Step 4: Test with sandbox cards and verify the payment

Use test cards in the sandbox

Use the test card numbers to test various payment scenarios. Create a new PaymentIntent for each test case and use the new id and client_secret in the HTML page.

Run at least:

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

Verify the PaymentIntent 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 PaymentIntent via API:

    Bash
    1curl --request GET \
    2  "https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_your_payment_intent_id" \
    3  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

    Check for status: "SUCCEEDED" on a successful test payment.

  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 redirects. For details, see Listen for webhook events.

Next steps

  • Prepare for production

    Implement idempotency on create/confirm calls, add error handling for declines and network errors, and validate 3DS flows in your key markets.

  • Try other integration options

    You can choose from a range of integration options based on your engineering capacity, PCI scope, and desired level of control. For details, see Online payments overview.

  • Connect Billing and Invoicing

    Use Billing Subscriptions for subscription lifecycle management and Invoicing for one-off or recurring invoices with payment links.

Complete the Test and go-live checklist to prepare a production-ready integration that meets your risk, reporting, and operational requirements.

Was this page helpful?