Search...
APIJSLog inGet started
Airwallex logo
Home
Platform APIs
Connected Accounts
Accounts
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewChoose your payments solutionGet started with payments
Supported currencies
Online payments
Online payments overviewPayment Method Onboarding RequirementGet started with online paymentsHosted Payment Page
Drop-in Element
Guest user checkoutRegistered user checkout
Embedded Elements
Mobile SDK
Plugins
Native API
Automatic Currency Conversion
Invoice integrations
Tax filing

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.

Checkout flow

If you want to offer a one-off or single payment experience where the shopper is present and active on your shop site, see Guest user checkout.

If you want to save shopper's payment details for future payments, see Registered user checkout.

Supported features

You can use the following features in your Drop-in Element integration.

Style and appearance customization

theme and style objects have been deprecated in @airwallex/components-sdk version 1.19.1, use the enhanced appearance object instead.

appearance

You can customize the appearance of your Element to match the design of your website using the following customization options:

  • mode: The appearance mode for the Element. Accepts dark or light modes where each mode provides a different color variable preset and color generation logic. Defaults to light.

  • variables: Set variables to customize the appearance of the Element. Supports three color keys that accept RGB or HEX color formats.

    • colorBackground: Sets the primary text color. This option automatically generates a comprehensive color set, including secondary text, inverse text, disabled text, placeholder text, and more. Defaults to #14171a (light mode) and #F5F6F7 (dark mode).
    • colorBrand: Sets the main accent color used for Elements such as buttons, text links, focus borders, interactive backgrounds, highlights, etc. This color defines your brand's visual identity in the Element. Defaults to #612fff (light mode) and #ABA8FF (dark mode).
    • colorText: Sets the primary background color. This option alautomatically generates a complete set of background colors, including primary, secondary, field, and disabled backgrounds. Defaults to #ffffff (light mode) and #14171A (dark mode).
  • rules: Fine tune individual Elements and states by specifying custom CSS properties using rules. The following classes and pseudo-classes can be styled using rules.
    • .Button: CSSProperties
    • .Button:hover: CSSProperties
    • .GooglePayButton: CSSProperties
    • .GooglePayButton:hover: CSSProperties
    • .ApplePayButton: CSSProperties
    • .ApplePayButton:hover: CSSProperties
    • .Input: CSSProperties
    • .Input:hover: CSSProperties
    • .Input:active: CSSProperties
JavaScript

layout

The layout object supports two options:

  • alwaysShowMethodLabel: By default (false), the payment method icon is hidden when only one payment method is available. Set to true to always display the payment method icon.
  • type: Specify the layout for the payment elements. Defaults to accordion and tab layout on desktop and mobile interfaces respectively.
JavaScript
Accordion layout on Desktop Accordion layout - DesktopAccordion layout on MobileAccordion layout - Mobile
Tab layout on Desktop Tab layout - DesktopTab layout on Mobile Tab layout - Mobile

style (deprecated)

Provide base styling for the iframe using CSS properties. You can also customize the width and height of a pop-up overlay, e.g., payment with 3-D Secure authentication.

JavaScript

Localization

You can configure the Element to display localized text of the payment fields based on the locale set in init(). See supported locales JS.

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 JS: 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 a div after body tag and use it as the container.
  • withBilling JS: If applicable set this to true 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. Airwallex.js automatically handles device fingerprinting, so no additional integration is needed.

Payments for platforms

You can accept payments as a platform via Drop-in Element. Example platforms include marketplaces, SaaS platforms, on-demand service providers. For more information on payments for platforms with Airwallex as an acquirer, see Airwallex payment gateway.

If you want the shopper to see the available payment methods activated by the connected account, specify the Connected Account ID in the platformConnectedAccount field in createElement().

To use Connected Account information to process the payment, e.g., statement descriptor displayed on the shopper's credit card or bank statement, provide connected_account_id in Create a Payment Intent API.

FAQ

What payment methods are supported in a Drop-in Element integration?

By default, all payment methods activated on your Airwallex merchant account are displayed to the shopper. However, you can restrict the payment methods shown using:

Can I offer Apple Pay via Drop-in Element 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.

JavaScript

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.

JavaScript

Development resources

On this page
  • Checkout flow
  • Supported features
  • FAQ
  • Development resources