Quickstart: Card element

Copy for LLMView as Markdown

Complete a minimal end-to-end card payment in the sandbox using Airwallex.js and the Card element. 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 mounts the Card element and confirms the PaymentIntent from the browser.
Verify the result in the Airwallex web app, via API, or with webhooks.

Airwallex AgentOS can accelerate your integration. Connect your coding assistant to the Developer MCP for API and SDK guidance while you build, or use the airwallex CLI for production reads and writes.

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 be able to make HTTP requests from a backend server and serve a simple HTML page (or equivalent) that loads the Airwallex.js script from the CDN.
Install Airwallex.js JS from the CDN (as in this tutorial) or via @airwallex/components-sdk . If you currently use Airwallex Payment elements , see the upgrade guide.

Step 1: Get an access token on your server

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

Request

Shell

1curl -X POST https://api-demo.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

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. The Card element collects card details against that intent; you confirm it when the shopper submits payment.

End-to-end flow (sequence diagram)

Card element Sequence

When the shopper begins checkout, call Create a PaymentIntent API on your server with request_id, amount, currency, and merchant_order_id. Always decide how much to charge on the server so shoppers cannot alter the amount.

Provide return_url so Airwallex can return the shopper to your site after flows that require a redirect (for example some 3D Secure authentication or wallet flows). Learn more about the PaymentIntents API.

Request

Shell

1curl -X POST https://api-demo.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/payment-return"
10  }'

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 (intent_id on the client).
client_secret: Used on the client to attach card details and confirm securely.
currency: The same currency you passed when creating the PaymentIntent.

Step 3: Build a basic checkout page with Card element

Build a simple HTML page that loads Airwallex.js from the CDN, initializes the SDK, creates the Card element JS, mounts it into a container, and calls confirm() JS when the shopper clicks Pay. Mount the element only once per payment flow.

Add the SDK, container, and script

HTML

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="utf-8" />
5  <title>Quickstart — Card element</title>
6  <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
7</head>
8<body>
9  <h1>Card element integration</h1>
10  <p>Enter card details, then click Pay to confirm the PaymentIntent.</p>
11  <div id="card"></div>
12  <button id="submit" type="button">Pay</button>
13  <script async>
14    const intent_id = 'replace-with-your-intent-id';
15    const client_secret = 'replace-with-your-client-secret';
16    const currency = 'replace-with-your-currency';
17
18    (async () => {
19      await window.AirwallexComponentsSDK.init({
20        env: 'demo',
21        enabledElements: ['payments'],
22      });
23
24      const card = await window.AirwallexComponentsSDK.createElement('card', {
25        intent_id,
26        client_secret,
27        currency,
28      });
29
30      card.mount('card');
31
32      document.getElementById('submit').addEventListener('click', () => {
33        card
34          .confirm({
35            intent_id,
36            client_secret,
37          })
38          .then((response) => {
39            // Inspect response; always verify PaymentIntent status on your server
40            console.log(response);
41          })
42          .catch((err) => {
43            console.error(err);
44          });
45      });
46    })();
47  </script>
48</body>
49</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.

You can pass additional options in createElement() (for example style JS or 3DS-related fields). For all options, see CardElementOptions JS.

Using npm instead of the CDN

If you bundle your frontend with npm, use the same flow with module imports:

JavaScript

1import { init, createElement } from '@airwallex/components-sdk';
2
3await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7
8const card = createElement('card', {
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-currency',
12});
13
14card.mount('card');
15
16document.getElementById('submit').addEventListener('click', () => {
17  card
18    .confirm({
19      intent_id: 'replace-with-your-intent-id',
20      client_secret: 'replace-with-your-client-secret',
21    })
22    .then((response) => {
23      console.log(response);
24    })
25    .catch((err) => {
26      console.error(err);
27    });
28});

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 PaymentIntent for each test case and use the new id and client_secret on your checkout 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:

Airwallex web app

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

Retrieve PaymentIntent via API

Shell

1curl -G https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_your_payment_intent_id \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

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

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 client confirm() response—the shopper may close the browser before your handler runs. For details, see Listen for webhook events.

Next steps

Prepare for production

Implement idempotency on create and confirm calls, add robust error handling for declines and network errors, and validate 3DS flows in your key markets. See Airwallex.js error codes.
Customize checkout

See Customize style and appearance.
Try Split Card or other checkout options

For individual card fields, follow Quickstart: Split card element. For a pre-built multi-method block, see Quickstart: Drop-in element. For the redirect-based Hosted Payment Page, see Quickstart: Your first online payment. For more options, see Web checkout overview.

Complete the Test and go-live checklist before going live.

Was this page helpful?