Quickstart: Apple Pay element

Complete a minimal shopper-present payment on the web using Airwallex.js and the Apple Pay element (applePayButton JS). By the end of this tutorial, you will have a checkout page that shows the Apple Pay button and completes a PaymentIntent when the shopper authorizes payment.

You'll do the following:

• Authenticate to Airwallex and generate an access token.
• Create a PaymentIntent on your server.
• Build a checkout page that initializes Airwallex.js, mounts the Apple Pay button, and handles client success and error events.
• Verify the result in the Airwallex web app, via API, or with webhooks.

Before you begin

• You must have a sandbox account for testing.
• Apple Pay must be enabled for your account, and your web domain (and certificates, if applicable) must be set up as described in the Apple Pay guides—otherwise the button may not appear or sessions may fail.
• Apple Pay on the web requires a compatible Safari environment and a supported region for Apple Pay. See Apple’s documentation and Apple Pay payment scenarios for testing notes.
• Payments must be enabled on your Airwallex account with payment methods activated as required for your integration.
• You must have your Client ID and API key from Developer > API keys in the web app.
• You must be able to make HTTP requests from a backend server and serve a page over HTTPS 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

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

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.

Step 2: Create a PaymentIntent on your server

A PaymentIntent represents your intent to collect a specific amount from a shopper. The Apple Pay button uses it to authorize the wallet payment with Airwallex.

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 any redirect-based step in the payment flow. Learn more about the PaymentIntents API.

Request

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.

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 complete the payment securely.
• amount and currency: The same values you used when creating the PaymentIntent. Express the amount in the smallest currency unit (for example cents for USD); the API example uses 100 for USD 1.00.

Step 3: Build a basic checkout page with Apple Pay element

Build a page that loads Airwallex.js from the CDN, initializes the SDK, creates applePayButton JS with your PaymentIntent and Apple Pay sheet details, mounts it once, and listens for success and error. The shopper completes payment in the Apple Pay sheet; there is no separate confirm() call like the Card element.

amount.value must match the PaymentIntent amount in the smallest currency unit, as a string (for example '100' for USD 1.00 when the PaymentIntent amount is 100). countryCode is the two-letter ISO code for the transaction (for example US). For billing, shipping, and 3DS-related fields, see Apple Pay button JS. For button styling samples, see Customize style and appearance (Apple Pay element tab).

Add the SDK, container, and script

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="utf-8" />
5  <title>Quickstart — Apple Pay element</title>
6  <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
7</head>
8<body>
9  <h1>Apple Pay element</h1>
10  <p>Use the Apple Pay button to pay with Wallet.</p>
11  <div id="applePayButton"></div>
12
13  <script async>
14    const intent_id = 'replace-with-your-intent-id';
15    const client_secret = 'replace-with-your-client-secret';
16    const amountMinorUnits = '100';
17    const currency = 'USD';
18
19    (async () => {
20      await window.AirwallexComponentsSDK.init({
21        env: 'demo',
22        enabledElements: ['payments'],
23      });
24
25      const element = await window.AirwallexComponentsSDK.createElement('applePayButton', {
26        intent_id,
27        client_secret,
28        countryCode: 'US',
29        amount: {
30          value: amountMinorUnits,
31          currency,
32        },
33        totalPriceLabel: 'Demo Store',
34        buttonType: 'buy',
35        buttonColor: 'black',
36      });
37
38      element.mount('applePayButton');
39
40      element.on('success', (event) => {
41        console.log('success', event);
42      });
43
44      element.on('error', (event) => {
45        console.error('error', event);
46      });
47    })();
48  </script>
49</body>
50</html>

Replace placeholders with values from your PaymentIntent and your business copy (totalPriceLabel, countryCode, and optional billing or shipping contact fields as needed).

For button styling (buttonType, buttonColor, appearance, and more), see Customize style and appearance and open the Apple Pay element tab.

For a full HTML sample in a repo context, see the Airwallex payment demo — Apple Pay button .

Using npm instead of the CDN

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

1import { init, createElement } from '@airwallex/components-sdk';
2
3await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7
8const element = createElement('applePayButton', {
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  countryCode: 'US',
12  amount: {
13    value: '100',
14    currency: 'USD',
15  },
16  totalPriceLabel: 'Demo Store',
17  buttonType: 'buy',
18  buttonColor: 'black',
19});
20
21element.mount('applePayButton');
22
23element.on('success', (event) => {
24  console.log('success', event);
25});
26
27element.on('error', (event) => {
28  console.error('error', event);
29});

Step 4: Test Apple Pay and verify the payment

Test in sandbox

Use Apple Pay payment scenarios and the Apple Pay product guide. Testing typically uses real cards with demo API keys; behavior and availability depend on Safari, domain registration, and region support.

Verify the PaymentIntent status

Do not rely on the client alone—the shopper can close the page before your success handler finishes.

1. Airwallex web app

   Go to Payments > Payments Activity and confirm the PaymentIntent.

2. 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}}'

3. Webhooks (recommended for production)

   Listen for payment_intent.succeeded and related events. See Listen for webhook events.

Next steps

• Prepare for production

  Harden error handling, validate Apple Pay domain and certificate setup for production, and review Airwallex.js error codes.

• Customize the button

  See Customize style and appearance (open the Apple Pay element tab) for style, appearance, buttonType, buttonColor, and examples. For the full option reference, see Apple Pay button JS.

• Save payment details or add Google Pay

  Use Save and reuse payment details for wallet vaulting flows. For Google Pay on the web, see Quickstart: Google Pay element.

• Other checkout options

  See Web checkout overview, Quickstart: Drop-in element, and Quickstart: Card element.

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