Drop-in Element
The Drop-in Element is a UI component that lets you accept multiple payment methods with a single integration. Whether you’re just collecting card payments or using multiple payment methods, the Drop-in Element provides an easy solution to build a customised payments experience. Accepting more payment methods can help your business expand its global reach and improve checkout conversion.
Key features include:
Automatically adjusts input fields to collect information based on the payment method and country.
Reduces friction for card payments with input validation, styling and error handling.
Adds new payment methods to your payment form without requiring code changes in your integration.
To view the checkout experience offered by the Drop-in Element, go to the Airwallex demo book store , add items to your shopping cart and click Checkout.
This page describes how to embed a Drop-in Element on your payment page to accept payments.
How it works
The diagram below depicts the information flow in a Drop-in Element integration.
Before you begin
Before you implement the integration, consider the following:
Contact your Airwallex Account Manager to enable payment acceptance using Embedded Elements for your merchant account.
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.
Explore the
airwallex-payment-elementsJavaScript client library reference JS to familiarize yourself with the Embedded Elements methods, parameters, and propertiesInstall the
airwallex-payment-elementspackage using Yarn or NPMyarn add airwallex-payment-elementsnpm install airwallex-payment-elements
Create a PaymentConsent if you want to save payment details for future payments.
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 3: Add the Drop-in Element to your checkout page
To embed the Drop-in 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 Drop-in Element
When the payment form has loaded, call createElement(type, options) by specifying the Element type as dropIn to create the Element. Ensure that the payment form only contains one Element with dropIn id.
Mount the Drop-in Element
Call mount() with the id of the div to mount the Element to the DOM. This builds a payment form with various payment methods. The Element should only be mounted once in a single payment flow.
Add onReady event listener to ensure the Drop-in Element is mounted. Use this event to prepare and load the checkout page.
Drop-in Props
You can also pass options in createElement() to overwrite styles and other functions as shown in the following table. The client_secret and currency fields are mandatory. For details, see dropIn props JS.
Step 4: Handle the response
Add onSuccess and 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.
Retrieve the payment result
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 webhooksOn your server, call Retrieve a PaymentIntent API to check the PaymentIntent status.
Check Payment Activity screen on your Airwallex web app.
Example integrations
Explore a full, working code sample of an integration built using various web frameworks JS.
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.
Additional features
You can add the following features to your Embedded Element integration.
Localization
You can configure the Element to display localized text of the payment fields based on the locale set in init() or loadAirwallex( ). Supported locales are:
en(US English)zh(Simplified Chinese)ja(Japanese)ko(Korean)ar(Arabic)fr(French)
Save card details for future payments
Airwallex allows you to create a PaymentConsent with the shopper to initiate future payments using shopper’s saved card details. For more information, see Save payment details for future payments .
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 adivafterbodytag and use it as the container.withBilling: If applicable set this totrueto collect billing information from the shopper, which increases the likelihood of frictionless checkout.
FAQ
What are the common error scenarios with Embedded Elements integration?
Some common 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. |
How do I customize the Embedded Element?
You can provide the fonts[ ] option in init( ) or loadAirwallex( ) when you initialize Airwallex to customize the font styles of payment Elements. Airwallex supports two font weights: regular (400) and bold (700). You can specify font options using src, family and weight attributes.
You can also customize styles for the cardNumber/card/fullFeaturedCard Element using style. With Split Card, you can also customize cvc and expiry Elements.
What payment methods are supported in a Drop-in Element integration?
All payment methods configured on your merchant account are supported. The list displayed to the shopper on the payment form is filtered based on the following fields:
currencypassed increateElement()components[ ]passed increateElement(). Contains the list of payment methods you want to offer the shopper.(Optional)
country_codepassed increateElement( )for payment methods such asonline_banking,bank_transfer,seven_eleven,skrill,sofort,trustly,paysafecash,paysafecard,satispay,paysera,paypal,bitpay
Can I offer Apple Pay via Drop-in integration?
Yes, Apple Pay is supported via Drop-in integration. Ensure that your merchant account is enabled for Apple Pay and you have added your domain information on the Airwallex web app > Payments > Settings. For more information, see Enable Apple Pay. Once registered, you can pass applePayRequestOptions JS in createElement to offer Apple Pay. Note that countryCode is mandatory.
Can I offer Google Pay via Drop-in Element integration?
Yes, Google Pay is supported via Drop-in integration. Ensure that your merchant account is enabled for Google Pay and you have added your domain information on the Airwallex web app > Payments > Settings. For more information, see Enable Google Pay. Once registered, you can pass googlePayRequestOptions JS in createElement to offer Google Pay. Note that countryCode is mandatory.