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.
This page describes how to embed a Apple Pay Element on your payment page to accept payments.
The diagram below depicts the information flow in a Apple Pay Element integration.
Before you implement the integration, consider the following:
Contact your Airwallex Account Manager to enable payment acceptance using Embedded Elements for your merchant account.
Ensure that your merchant account is enabled for Apple Pay and you have added your domain information on the Airwallex web app > Payments > Settings page. For more information, see Enable Apple Pay.
Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
airwallex-payment-elementspackage using Yarn or NPM
yarn add airwallex-payment-elements
npm install airwallex-payment-elements
When the shopper begins the checkout process, you will need to create a PaymentIntent object to indicate your intent to collect payment from the shopper.
When the checkout page loads, on your server, call Create a PaymentIntent API API with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious shoppers from being able to alter the payment amount.
return_url in Create a PaymentIntent API to indicate where Airwallex should redirect the shopper after completing the payment, whether successful or otherwise.
client_secret are returned in the response — these parameters let you confirm the payment and update card details on the client, without allowing manipulation of sensitive information, like payment amount.
First, you will need to import the
airwallex-payment-elements SDK and then initialize the package. For details, see Initialize Airwallex JS.
To embed the Apple Pay Element into your checkout page, you will need to create an empty container, create the Element and then mount the Element to the container.
Define the payment form
First, create an empty container
div with a unique id in your payment form. Ensure that the payment form only contains one Element with this unique id. Airwallex inserts an iframe into this
div on mounting the Element.
Create the Apple Pay Element
When the payment form has loaded, call
createElement(type, options) by specifying the Element type as
applePayButton to create the Element. Ensure that the payment form only contains one Element with
Mount the Apple Pay Element
mount() with the id of the
div to mount the Element to the DOM. This creates the Apple Pay button. The Element should only be mounted once in a single payment flow.
onReady event listener to ensure the Element is mounted. Use this event to prepare and load the checkout page.
onError event listeners to handle error and success events received from Airwallex.
If no error occurred, display a message that the payment was successful. If payment fails with an error, display the appropriate message to your shopper so they can take action and try again.
For any actions subsequent to the payment such as shipping goods or sending email receipts, you can retrieve the payment result using the following options:
Set up webhooks to receive notifications on whether the payment has succeeded. Airwallex sends
payment_intent.succeededevent when a payment succeeds. Listen to these events rather than waiting on a callback from the client. On the client, the shopper could close the browser window or quit the app before the callback executes. For information on how to set up webhooks and listen to events, see Getting started with webhooks
On your server, call Retrieve a PaymentIntent API to check the PaymentIntent status.
Check Payment Activity screen on your Airwallex web app.
createElement( ), you can perform the following operations on the Element.
|Use this method to update the Element’s
options after creating the Element.
|Use this method to query the created Element by type.
|Use this method to destroy the created Element. The element can no longer be accessed after this call. The call returns a boolean to indicate the success or failure of the call.
Perform transaction tests in the production environment as described in the go-live checklist to ensure your integration is working correctly.
You can add the following features to your Embedded Element integration.
You can configure the Element to display localized text of the payment fields based on the
locale set in
loadAirwallex( ). See supported locales JS.
Device fingerprinting uniquely tracks and identifies devices used for transacting on your shopping site, increasing your protection from fraud. The
Airwallex allows you to create a PaymentConsent with the shopper to initiate future payments using shopper’s saved payments details. For more information, see Save payment details for future payments. You need to add additional information about the order & terms of the payment to display this information on the payment sheet.
- See below example to understand how to setup recurring with Apple Pay without payment
- See below example to understand how to setup recurring with Apple Pay with payment
- See example below for variable amount / variable subscription use-case with payment
- See example below for variable amount / variable subscription use-case without payment
Some common error scenarios include :
|Airwallex is not defined
|Check if you have initialized Airwallex (Step 2) before using Airwallex functions. If you are using CDN, check if you have changed the bundle version from x.x.x to the latest version in the
package.json file. For example,
https://checkout.airwallex.com/assets/elements.bundle.min.js is invalid
|Access denied, authentication failed
|Check if you have replaced your intent
createElement() and optionally
|The PaymentIntent with ID int_xxxxxxxxx cannot be found
|Check if the environment you initialized Airwallex in, for example, demo or prod, matches the environment you retrieved your intent
client_secret from. In other words, if you ran init in the demo environment, you must also create your PaymentIntent in the demo environment.
|InvalidAccessError: Page already has an active payment session
|ApplePay doesn't allow duplicate sessions in the same page. However, you may create the apple pay element multiple times, please follow either of the options listed to address the error: 1) Call the destroy function to destroy old element before you create the new element. 2) Call the update function to update the old element with new intentId.