Apple Pay Button Element

The Apple Pay Element allows you to offer Apple Pay checkout option on your website. Shoppers can click the Apple Pay button and pay using Touch ID or Face ID.

createElement('applePayButton', options?)

Use this function to create an instance of an individual Element.

Parameters

type

required'applePayButton'

The type of element you are creating.

options

optionalApplePayButtonOptions

Options for creating applePayButton Element.

amount

requiredAmount

Indicate the amount and currency of the Payment Intent.

If the mode is set to 'recurring' and intent_id omitted, amount should be {value: '0', currency: 'Replace with payment currency'}.

countryCode

requiredstring

The merchant's two-letter ISO 3166 country code. For example, 'US'.

appearance

optionalApplePayButtonAppearance

Customize the appearance of the Apple Pay button.

applicationData

optionalstring

Optional user-defined data.

authorizationType

optional'pre_auth' | 'final_auth'

The authorization type for the card payment.

Set it to 'pre_auth' if you want to place a hold on your customer's card for more than 7 days, i.e., extend the authorization time window.

Currently it's only available when the card brand is Visa or Mastercard. autoCapture will be automatically set to false if you enable pre_auth.

Default: 'final_auth'

autoCapture

optionalboolean

Whether the amount should be captured automatically upon successful payment authorization.

Set it to false if you want to place a hold on the payment method and capture the funds sometime later.

Default: true

billingContact

optionalApplePayPaymentContact

Billing contact information for the shopper.

buttonColor

optional'black' | 'white' | 'white-outline'

Indicate the color of the button.

Default: 'black'

buttonType

optionalenum

Supported methods for presenting the Apple Pay button.

A translated button label may appear if a language specified in the viewer's browser matches an available language.

client_secret

optionalstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

Leave it empty if intent_id and customer_id are not provided as you can provide it in the update() function later.

customer_id

optionalstring

The ID of the Customer used in registered user checkout. Refer to Airwallex Client API

This field is required when mode is 'recurring'.

existingPaymentMethodRequired

optionalboolean

Whether the shopper must have an active card provisioned in Apple Pay.

When set to true, the Apple Pay button will only be displayed if the user has an active card in their Apple Pay wallet, checked via ApplePaySession.canMakePaymentsWithActiveCard().

Default: false

intent_id

optionalstring

The ID of the Payment Intent you would like to checkout.

Required when mode is set to 'payment' but optional for 'recurring'.

Refer to Airwallex Client API

lineItems

optionalApplePayLineItem[]

A set of line items that explain recurring payments and/or additional charges.

merchantCapabilities

optional('supports3DS' | 'supportsEMV' | 'supportsCredit' | 'supportsDebit')[]

Payment capabilities supported by the merchant.

If not configured, merchantCapabilities will be based on merchant's account settings.

supports3DS: Required. This value must be supplied.
supportsCredit: Optional. If present, only transactions that are categorized as credit cards are allowed.
supportsDebit: Optional. If present, only transactions that are categorized as debit cards are allowed.
supportsEMV: Include this value only if you support China Union Pay transactions. (if supportedNetworks does not contain chinaUnionPay, don't include it).

mode

optional'payment' | 'recurring'

The checkout mode for the shopper.

Default: 'payment'

payment_consent

optionalPaymentConsentOptions

Options for PaymentConsent.

requiredBillingContactFields

optional'postalAddress'[]

The billing information that you require from the shopper in order to process the transaction. Only postalAddress is supported. If you need to collect name, email, phone, you need to add requiredShippingContactFields config. e.g. requiredShippingContactFields: ['name', 'email', 'phone']

requiredShippingContactFields

optional('email' | 'name' | 'phone' | 'postalAddress' | 'phoneticName')[]

The shipping information that you require from the shopper in order to fulfill the order.

shippingContact

optionalApplePayPaymentContact

Shipping contact information for the shopper.

shippingMethods

optionalApplePayShippingMethod[]

A set of shipping method objects that describe the available shipping methods.

shippingType

optional'shipping' | 'delivery' | 'storePickup' | 'servicePickup'

An optional value that indicates how purchased items are to be shipped.

style

optionalCSSProperties

Box style for the ApplePayButton Element.

supportedCountries

optionalstring[]

A list of ISO 3166 country codes for limiting payments to cards from specific countries.

supportedNetworks

optionalstring[]

Card networks supported by the merchant.

If not configured, supportedNetworks will be based on merchant's account settings.

For more details, see https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/1916122-supportednetworks

totalPriceLabel

optionalstring

Provide a business name for the label field. Use the same business name that you want displayed for the charge on the shopper's bank or credit card statement. For example, "COMPANY, INC.".

totalPriceType

optional'pending' | 'final'

Indicate whether a line item is final or pending.

If the mode is recurring and if it's a variable subscription, the value should be pending.

Default: 'final'

Returns

ApplePayButtonElement | null

createElement('applePayButton', options?)

1import { init, createElement } from '@airwallex/components-sdk';
2
3await init({
4  env: 'prod',
5  enabledElements: ['payments'],
6});
7
8const element = await createElement('applePayButton', {
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  amount: {
12    value: 'replace-with-your-intent-amount',
13    currency: 'replace-with-your-intent-currency',
14  },
15  countryCode: 'replace-with-your-country-code',
16});
17
18element.mount('applepay-container');

completeValidation(merchantSession)

Parameters

merchantSession

requiredunknown

An opaque message session object.

completeValidation(merchantSession)

1element.completeValidation({
2  epochTimestamp: 1721269728247,
3  expiresAt: 1721273328247,
4  merchantSessionIdentifier: 'SSH16075688527B4E',
5  nonce: '9c283350',
6  merchantIdentifier: '3409DA66CE0',
7  domainName: 'your domain name',
8  displayName: 'Sawayn, Conner and Quigley',
9  signature: '308006092a86',
10  operationalAnalyticsIdentifier: 'Carroll, Swaniawski',
11  retries: 0,
12  pspId: '803FB3E0FC',
13});

confirmIntent(data)

Call this function when the shopper is ready to make a payment as per the details in the Payment Intent.

Parameters

data

requiredConfirmIntentData

client_secret

requiredstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

payment_consent

optionalPaymentConsentOptions

Options for PaymentConsent.

Returns

Promise<Intent>

Intent

requiredobject

requiredstring

The ID of the Payment Intent.

amount

optionalnumber

Payment amount. This is the order amount you would like to charge your customer.

client_secret

optionalstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

created_at

optionalstring

The time this Payment Intent was created, in ISO 8601 format.

currency

optionalstring

The three-letter ISO currency code representing the currency of the Payment Intent.

customer_id

optionalstring

The ID of the Customer who intends to pay for the Payment Intent.

customer_payment_consents

optionalobject

customer_payment_methods

optionalobject

merchant_order_id

optionalstring

The merchant's order ID for this payment.

payment_consent_id

optionalstring

The ID of the Payment Consent associated with this Payment Intent.

request_id

optionalstring

Unique request ID specified by the merchant.

status

optionalstring

The status of the Payment Intent (e.g. 'REQUIRES_PAYMENT_METHOD', 'SUCCEEDED').

updated_at

optionalstring

The time this Payment Intent was last updated, in ISO 8601 format.

confirmIntent(data)

1element.confirmIntent({
2  client_secret: intent?.client_secret,
3});

createPaymentConsent(data)

Call this function to create a Payment Consent, which represents the agreement between the merchant and shopper of making subsequent payments using the provided payment method.

Parameters

data

requiredParameterObject

client_secret

requiredstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

Returns

Promise<Consent | undefined>

The client_secret returned when creating a Payment Consent.

The time this Payment Consent was created.

The ID of the Customer who intends to pay for the Payment Intent.

The ID of the Payment Consent to be confirmed.

Whether the merchant or customer should trigger subsequent payments.

The status of the Payment Consent.

The time this Payment Consent was last updated.

The ID of the initial Payment Intent.

Whether subsequent payments are 'scheduled' or 'unscheduled'. Only applicable when next_triggered_by is 'merchant'.

Default: 'unscheduled'

createPaymentConsent(data)

1element.createPaymentConsent({
2  client_secret: intent?.client_secret,
3});

destroy()

Destroys the Element instance.

destroy()

1element.destroy();

mount(domElement)

Mounts Element to your HTML DOM.

Parameters

domElement

requiredstring | HTMLElement

Returns

HTMLElement | null

mount(domElement)

1// There are two ways to mount the element:
2// 1. Call with the container DOM id
3element.mount('container-dom-id');
4
5// 2. Find the created DOM in the existing HTML and call with the container DOM element
6const containerElement = document.getElementById('container-dom-id');
7element.mount(containerElement);

on('ready', handler)

This event will be fired when the Apple Pay button element is mounted and ready to interact with the user.

Parameters

type

required'ready'

The event name.

handler

required() => void

The callback function that will be called when the event occurs.

on('ready', handler)

1element.on('ready', () => {
2    console.log('Apple Pay button is ready');
3  });

on('success', handler)

This event will be fired when payment is successful.

Parameters

type

required'success'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

The consent of the payment

intent

optionalIntent

The intent of the payment

requiredstring

The ID of the Payment Intent.

amount

optionalnumber

Payment amount. This is the order amount you would like to charge your customer.

client_secret

optionalstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

created_at

optionalstring

The time this Payment Intent was created, in ISO 8601 format.

currency

optionalstring

The three-letter ISO currency code representing the currency of the Payment Intent.

customer_id

optionalstring

The ID of the Customer who intends to pay for the Payment Intent.

customer_payment_consents

optionalobject

customer_payment_methods

optionalobject

merchant_order_id

optionalstring

The merchant's order ID for this payment.

payment_consent_id

optionalstring

The ID of the Payment Consent associated with this Payment Intent.

request_id

optionalstring

Unique request ID specified by the merchant.

status

optionalstring

The status of the Payment Intent (e.g. 'REQUIRES_PAYMENT_METHOD', 'SUCCEEDED').

updated_at

optionalstring

The time this Payment Intent was last updated, in ISO 8601 format.

on('success', handler)

1element.on('success', (e) => {
2    const { intent, consent } = e.detail;
3    console.log('Payment is successful', { intent, consent });
4  });

on('error', handler)

This event will be fired when the element encounters an unexpected error.

Parameters

type

required'error'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

on('error', handler)

1element.on('error', (e) => {
2    const { error } = e.detail;
3    console.error('There is an error', error);
4  });

on('cancel', handler)

This event will be fired when payment is cancelled.

Parameters

type

required'cancel'

The event name.

handler

required() => void

The callback function that will be called when the event occurs.

on('cancel', handler)

1element.on('cancel', () => {
2    console.log('Payment cancelled');
3  });

on('shippingMethodChange', handler)

This event will be fired when the shipping method changes.

Parameters

type

required'shippingMethodChange'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

on('shippingMethodChange', handler)

1element.on('shippingMethodChange', (e) => {
2    const { shippingMethod } = e.detail;
3    console.log('Shipping method changed', shippingMethod);
4  });

on('shippingAddressChange', handler)

This event will be fired when the shipping address changes.

Parameters

type

required'shippingAddressChange'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

on('shippingAddressChange', handler)

1element.on('shippingAddressChange', (e) => {
2    const { shippingAddress } = e.detail;
3    console.log('Shipping address changed', shippingAddress);
4  });

on('click', handler)

This event will be fired when the user clicks the Apple Pay button.

Parameters

type

required'click'

The event name.

handler

required() => void

The callback function that will be called when the event occurs.

on('click', handler)

1element.on('click', () => {
2    console.log('Apple Pay button clicked');
3  });

on('validateMerchant', handler)

This event will be fired when the user validates the merchant.

Parameters

type

required'validateMerchant'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

on('validateMerchant', handler)

1element.on('validateMerchant', (e) => {
2    const { validationURL } = e.detail;
3    console.log('Validation URL', validationURL);
4  });

on('authorized', handler)

This event will be fired when the user authorizes the payment.

Parameters

type

required'authorized'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

The handler receives an object with the following properties:

detail

requiredobject

paymentData

requiredobject

token

requiredApplePayPaymentToken

The encrypted information for an authorized payment.

billingContact

optionalApplePayPaymentContact

The billing contact selected by the user for this transaction.

shippingContact

optionalApplePayPaymentContact

The shipping contact selected by the user for this transaction.

on('authorized', handler)

1element.on('authorized', (e) => {
2    const { paymentData } = e.detail;
3    console.log('Payment authorized', paymentData);
4  });

unmount()

Unmounts the Element. Note that the Element instance will remain.

unmount()

1element.unmount();

update(options?, initOptions?)

Call this function to update Element options after creating the Element.

Parameters

options

optionalApplePayButtonUpdateOptions

amount

optionalAmount

Indicate the amount and currency of the Payment Intent.

If the mode is set to 'recurring' and intent_id omitted, amount should be {value: '0', currency: 'Replace with payment currency'}.

appearance

optionalApplePayButtonAppearance

Customize the appearance of the Apple Pay button.

applicationData

optionalstring

Optional user-defined data.

authorizationType

optional'pre_auth' | 'final_auth'

The authorization type for the card payment.

Set it to 'pre_auth' if you want to place a hold on your customer's card for more than 7 days, i.e., extend the authorization time window.

Currently it's only available when the card brand is Visa or Mastercard. autoCapture will be automatically set to false if you enable pre_auth.

Default: 'final_auth'

autoCapture

optionalboolean

Whether the amount should be captured automatically upon successful payment authorization.

Set it to false if you want to place a hold on the payment method and capture the funds sometime later.

Default: true

billingContact

optionalApplePayPaymentContact

Billing contact information for the shopper.

buttonColor

optional'black' | 'white' | 'white-outline'

Indicate the color of the button.

Default: 'black'

buttonType

optionalenum

Supported methods for presenting the Apple Pay button.

A translated button label may appear if a language specified in the viewer's browser matches an available language.

client_secret

optionalstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

Leave it empty if intent_id and customer_id are not provided as you can provide it in the update() function later.

countryCode

optionalstring

The merchant's two-letter ISO 3166 country code. For example, 'US'.

customer_id

optionalstring

The ID of the Customer used in registered user checkout. Refer to Airwallex Client API

This field is required when mode is 'recurring'.

errors

optionalApplePayError[]

A customizable error type that you create to indicate problems with the address or contact information on an Apple Pay sheet.

existingPaymentMethodRequired

optionalboolean

Whether the shopper must have an active card provisioned in Apple Pay.

When set to true, the Apple Pay button will only be displayed if the user has an active card in their Apple Pay wallet, checked via ApplePaySession.canMakePaymentsWithActiveCard().

Default: false

intent_id

optionalstring

The ID of the Payment Intent you would like to checkout.

Required when mode is set to 'payment' but optional for 'recurring'.

Refer to Airwallex Client API

lineItems

optionalApplePayLineItem[]

A set of line items that explain recurring payments and/or additional charges.

merchantCapabilities

optional('supports3DS' | 'supportsEMV' | 'supportsCredit' | 'supportsDebit')[]

Payment capabilities supported by the merchant.

If not configured, merchantCapabilities will be based on merchant's account settings.

supports3DS: Required. This value must be supplied.
supportsCredit: Optional. If present, only transactions that are categorized as credit cards are allowed.
supportsDebit: Optional. If present, only transactions that are categorized as debit cards are allowed.
supportsEMV: Include this value only if you support China Union Pay transactions. (if supportedNetworks does not contain chinaUnionPay, don't include it).

mode

optional'payment' | 'recurring'

The checkout mode for the shopper.

Default: 'payment'

payment_consent

optionalPaymentConsentOptions

Options for PaymentConsent.

requiredBillingContactFields

optional'postalAddress'[]

requiredShippingContactFields

optional('email' | 'name' | 'phone' | 'postalAddress' | 'phoneticName')[]

The shipping information that you require from the shopper in order to fulfill the order.

shippingContact

optionalApplePayPaymentContact

Shipping contact information for the shopper.

shippingMethods

optionalApplePayShippingMethod[]

A set of shipping method objects that describe the available shipping methods.

shippingType

optional'shipping' | 'delivery' | 'storePickup' | 'servicePickup'

An optional value that indicates how purchased items are to be shipped.

style

optionalCSSProperties

Box style for the ApplePayButton Element.

supportedCountries

optionalstring[]

A list of ISO 3166 country codes for limiting payments to cards from specific countries.

supportedNetworks

optionalstring[]

Card networks supported by the merchant.

If not configured, supportedNetworks will be based on merchant's account settings.

For more details, see https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/1916122-supportednetworks

totalPriceLabel

optionalstring

Provide a business name for the label field. Use the same business name that you want displayed for the charge on the shopper's bank or credit card statement. For example, "COMPANY, INC.".

totalPriceType

optional'pending' | 'final'

Indicate whether a line item is final or pending.

If the mode is recurring and if it's a variable subscription, the value should be pending.

Default: 'final'

initOptions

optionalInitOptions

env

optional'demo' | 'prod'

The Airwallex integration environment your site would like to connect with.

Default: 'prod'

fonts

optionalFontOptions[]

Global option to customize font styles of Elements.

locale

optionalenum

The locale for your website. Defaults to the browser's locale; however, if the browser's locale is not supported, it will default to 'en'.

origin

optionalstringDeprecated

This field is no longer used.

update(options?, initOptions?)

1element.update({
2  buttonType: 'donate',
3}, {
4  locale: 'en',
5});

Was this page helpful?