Guest user checkout
This page describes how to redirect to a payment page hosted by Airwallex to accept payments.
How it works
The diagram below depicts the information flow in a Hosted Payment Page integration.
Before you begin
Before you implement the integration, consider the following:
Ensure your Airwallex account has been activated for online payments.
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.
Read the
airwallex-payment-elements
JavaScript client library reference JS to familiarize yourself with the Hosted Payment Page methods, parameters, and properties.Install the package
- Using Yarn or NPM
yarn add airwallex-payment-elements
npm install airwallex-payment-elements
- Using CDN
<script src="https://checkout.airwallex.com/assets/elements.bundle.min.js"></script>
- Using Yarn or NPM
Step 1: Set up the server to create a PaymentIntent
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.
Provide return_url
in Create a PaymentIntent API if you want to offer alternative payment methods (Alipay, Dana, KakaoPay, etc) that redirect shoppers to a partner site. The shopper will be returned to the return_url
after the payment is complete, whether successful or otherwise.
The PaymentIntent’s id
and 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.
To display order information on the Hosted Payment Page, provide the order
object with the product information when you call Create a PaymentIntent API.
Step 2: Initialize Airwallex on your checkout page
First, you will need to import the airwallex-payment-elements
SDK and then initialize the package. For details, see Initialize Airwallex JS.
Step 4: Retrieve the payment result
Upon completing the payment, your shopper will be redirected to one of these URLs, successUrl
, failUrl
, cancelUrl
, provided in redirectToCheckout( )
method, and the PaymentIntent id will be appended to the URL.
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.succeeded event 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.
Test your integration
Use test card numbers and the test and go-live checklist to test your integration for various success and error scenarios in the demo environment and then go live in the production environment.
Example integrations
Explore a full, working code sample of an integration built using various web frameworks JS.
Supported features
You can add the following features to your Hosted Payment Page integration.
Localization
You can configure the Hosted Payment Page to display localized text of the payment fields based on the locale set in redirectToCheckout()
. For supported locales, see the locale
property JS.
3D Secure authentication
Airwallex automatically handles 3D Secure authentication offering either frictionless or challenge flow depending on the card issuer’s requirements. You can optionally pass the following fields in createElement( )
to support 3DS:
authFormContainer
: A container for the authentication form. If a challenge flow is required to authenticate the shopper, an iframe will be rendered in this container to display the authentication page provided by the issuing bank. If not provided, Airwallex will create adiv
afterbody
tag and use it as the container.withBilling
: If applicable set this totrue
to collect billing information from the shopper, which increases the likelihood of frictionless checkout.
Device fingerprinting
Device fingerprinting uniquely tracks and identifies devices used for transacting on your shopping site, increasing your protection from fraud. The airwallex-payment-elements
JavaScript client library automatically handles device fingerprinting, so no additional integration is needed.
Troubleshooting
Some common error scenarios include :
Error | Next steps |
---|---|
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 id and client_secret in createElement() and optionally confirmPaymentIntent() . |
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 id and 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. |