Web checkout (desktop and mobile browser)

Apple Pay is supported in the Drop-in element. Ensure your account is Apple Pay enabled and your domain is registered in the Airwallex web app under Payments > Settings.

Use applePayRequestOptions JS in createElement("dropIn", ...); countryCode is required.

1const dropInElement = createElement("dropIn", {
2  intent_id: intent.id,
3  client_secret: intent.client_secret,
4  currency: "USD",
5  applePayRequestOptions: {
6    countryCode: "US",
7    buttonType: "buy",
8    buttonColor: "white-with-line",
9    totalPriceLabel: "COMPANY, INC.",
10  },
11});

Use the Apple Pay Element if you want a dedicated Apple Pay button in your web checkout.

• Apple Pay element overview
• Guest checkout flow

Native API gives you full front-end control, but you must handle Apple Pay session events and token confirmation.

Key browser events you must handle in your web checkout:

1. canMakePayments
2. ApplePayPaymentRequest + ApplePaySession
3. onValidateMerchant
4. completeMerchantValidation
5. onPaymentAuthorized

Core API flow:

1. Create PaymentIntent API.
2. Start Apple Pay session via POST /api/v1/pa/payment_session/start.
3. Confirm PaymentIntent via Confirm PaymentIntent API.
4. Call Apple completePayment to close the widget.

For POST /api/v1/pa/payment_session/start, note these key fields:

• x-on-behalf-of (header): If you are a partner using Payments for Platforms and connected accounts use their own domains, include this header with the connected account identifier. If domains are shared or centrally managed, this header may not be required.
• payment_intent_id: PaymentIntent identifier returned from Create PaymentIntent API.
• validation_url: Apple merchant validation URL from ApplePayValidateMerchantEvent in the onValidateMerchant handler.
• initiative_context: Your verified e-commerce domain name.

Example request:

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_session/start \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
6    "payment_intent_id": "int_xxx",
7    "initiative_context": "your-domain.com",
8    "request_id": "your-request-id"
9  }'

Example response:

1{
2  "epochTimestamp": 1645778549965,
3  "expiresAt": 1645782149965,
4  "merchantSessionIdentifier": "SSH22C7A051B56546DEA1C33EE1F1309E8B_CCE257A9D27B42513B2C3CA67DB49F602F3450D996C0811ED462EDCA0D7477FD",
5  "nonce": "a924b785",
6  "merchantIdentifier": "803FB3E0FC3FFD4BFAEFF1CE226D663225E09D805ACDF4F8EE23A17A4FEDB745",
7  "domainName": "checkout-demo.airwallex.com",
8  "displayName": "demo merchant",
9  "signature": "308006092a864886f70d010702a0803080020101310f300d06096086480165030402010500308006092a864886f70d010",
10  "operationalAnalyticsIdentifier": ":803FB3E0FC3FFD4BFAEFF1CE226D663225E09D805ACDF4F8EE23A17A4FEDB745",
11  "retries": 0
12}

Use this response as the merchantSession parameter in Apple's completeMerchantValidation on the front end.

Example confirm request:

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "{{REQUEST_ID}}",
6    "payment_method": {
7      "type": "applepay",
8      "applepay": {
9        "payment_data_type": "encrypted_payment_token",
10        "encrypted_payment_token": "{{APPLE_PAY_TOKEN}}"
11      }
12    }
13  }'

For Apple Pay token confirmation payloads:

• applepay.payment_data_type: Type of payment data. Use tokenized_card or encrypted_payment_token.
• applepay.encrypted_payment_token: Payment data from ApplePayPaymentToken.
• payment_method.applepay.card_brand: Value from ApplePayPaymentToken.paymentMethod.network.
• payment_method.applepay.card_type: Value from ApplePayPaymentToken.paymentMethod.type.
• payment_method.applepay.data: Value from ApplePayPaymentToken.paymentData.data.
• payment_method.applepay.ephemeral_public_key: Value from ApplePayPaymentToken.paymentData.header.ephemeralPublicKey.
• payment_method.applepay.public_key_hash: Value from ApplePayPaymentToken.paymentData.header.publicKeyHash.
• payment_method.applepay.transaction_id: Value from ApplePayPaymentToken.paymentData.header.transactionId.
• payment_method.applepay.signature: Value from ApplePayPaymentToken.paymentData.signature.
• payment_method.applepay.version: Value from ApplePayPaymentToken.paymentData.version.

Drop-in supports Apple Pay recurring patterns with mode: "recurring" and applePayRequestOptions.lineItems.

• Without upfront payment: deferred line items (paymentTiming: "deferred").
• With upfront payment: include intent_id and recurring line items (paymentTiming: "recurring").
• Variable amount use cases are supported via type: "pending".

For complete flow setup, see Save payment details for future payments.

For recurring flows with the Apple Pay Element, use:

• Save and reuse payment details
• Apple Pay element registered user checkout

Native API recurring flows are supported with PaymentConsent:

• Save details without payment: create and verify PaymentConsent after session + token flow.
• Save details with payment: create PaymentMethod, then PaymentConsent, then create/confirm PaymentIntent for the first order.
• Include recurring/deferred terms in Apple lineItems shown to shopper.

Related APIs:

• Create a PaymentConsent API
• Verify a PaymentConsent API
• Create a PaymentMethod API