Airwallex JS
Airwallex logoAirwallex logo

Drop-in Element

Copy for LLMView as Markdown
The Drop-in Element lets you embed multiple payment methods with a single integration while offering options to customize the look and feel of the checkout experience.

createElement('dropIn', options?)

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

Parameters

type

required'dropIn'
The type of element you are creating.

options

optionalDropInElementOptions
Options for creating dropIn Element.

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.

currency

requiredstring
The three-letter ISO currency code representing the currency of the Payment Intent or Payment Consent. Only payment methods supported for the specified currency will be shown on the payment page.

allowedCardNetworks

optional('visa' | 'mastercard' | 'maestro' | 'unionpay' | 'amex' | 'jcb' | 'diners' | 'discover')[]
One or more card networks that you support.

appearance

optionalDropInAppearance
Customize the visual appearance of the DropIn Element to match your website's design.

applePayRequestOptions

optionalApplePayRequestOptions
Checkout configuration options for Apple Pay.

authFormContainer

optionalstring
The container of the authentication form used in 3D Secure authentication.

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 pre_auth is 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

autoSaveCardForFuturePayments

optionalboolean

Specifies whether the card payment method should be automatically saved for future transactions.

This parameter is only effective in payment mode when a customer_id is provided.

  • If set to true, the "Save my card for future payments" checkbox will be preselected by default.
  • If set to false, the checkbox will remain unchecked, requiring the shopper to manually opt in.
Default: true

billing

optionalBilling

Billing information provided by the merchant. This option overrides the billing information from the shopper as provided in the input billing fields. Do not set withBilling and requiredBillingContactFields when you use this option.

country_code

optionalstring
The two-letter ISO country code of the shopper's country. This is required for bank_transfer, online_banking, skrill or seven_eleven payment methods.

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'.

cvcRequired

optionalboolean
Whether you require the shopper to provide CVC when they checkout with a network tokenized card.

disableAutoCurrencyConversion

optionalboolean

Whether to force disable automatic currency conversion.

  • true: Overrides merchant settings to disable conversion.
  • false: Respects the merchant's automatic conversion configuration.
Default: false

googlePayRequestOptions

optionalGooglePayRequestOptions
Checkout configuration options for Google Pay.

intent_id

optionalstring
The ID of the Payment Intent you would like to checkout. Required when mode is 'payment'.

layout

optionalLayout
The layout of the DropIn element.

methods

optionalenum[]
The payment methods your website would like to integrate with.

mode

optional'payment' | 'recurring'
The checkout mode for the shopper, 'payment' or 'recurring'.
Default: 'payment'

payment_consent

optionalPaymentConsentOptions
The payment consent details.

platformConnectedAccount

optionalstring

When using Payments for Platforms, specify the ID of the connected account associated with the payment if you want to use its information to process the payment. For example, the statement descriptor displayed on the shopper's credit card or bank statement and the payment methods activated by the connected account.

quote_id

optionalstring | null

This field is used for Multi-Currency Pricing(MCP). The merchant can create a quote for the shopper, and pass the quote_id to Drop-in Element. If the quote_id is provided, Drop-in Element will use that quote to convert the amount and currency. And each time the shopper changes the currency, the merchant needs to create a new quote or reuse existing quotes and update the quote_id. If the quote_id is not provided, Drop-in Element will use ACC logic to automatically convert the amount and currency.

requiredBillingContactFields

optional('name' | 'email' | 'country_code' | 'address' | 'phone')[]
The billing information that you require from the user in order to process the transaction.

savedPaymentMethod

optionalSavedPaymentMethodOptions
The options for saved payment method.
Default: { displayMode: 'auto', saveMode: 'auto' }

shopper_email

optionalstring
The shopper's email address.

shopper_name

optionalstring
The shopper's full name.

shopper_phone

optionalstring
The shopper's phone number.

showConfirmButton

optionalboolean

Whether to display the built-in confirm button. Default is true. When set to false:

  • The confirm button will be hidden
  • Only card payment method will be displayed, other payment methods will be hidden
  • You must implement your own button and call dropInElement.confirm() to submit the payment
Default: true

style

optionalBoxStyle
Box style for the dropIn element.

submitType

optional'pay' | 'book' | 'subscribe' | 'save'

Describes the type of transaction being performed in order to customize the submit button text. Available options are 'pay', 'book', or 'subscribe'. The type can only be specified in payment mode. If blank, the default value will be 'pay'

Default: 'pay'

wechatpay

optionalWeChatPayFlow
The options for Wechat Pay.

components

optionalenum[]Deprecated
The payment methods your website would like to integrate with
use methods instead

recurringOptions

optionalRecurringOptionsDeprecated
Options for recurring flow.
use payment_consent instead

withBilling

optionalbooleanDeprecated
Indicate to improve 3DS experience, indicate if the payment form will collect billing info from shopper
please use requiredBillingContactFields instead

Returns

DropInElement | null

createElement('dropIn', options?)

1import { init, createElement } from '@airwallex/components-sdk';
2

3await init({
4  env: 'prod',
5  enabledElements: ['payments'],
6});
7

8const element = await createElement('dropIn', {
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-intent-currency',
12});
13

14element.mount('dropin-container');

confirm(data?)

Using this function to confirm payment intent when showConfirmButton is set to false, only applicable for card payment method.

Parameters

data

optionalDropInConfirmData
Payment confirmation data

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.

Returns

Promise<Intent>

Intent

requiredobject

id

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.

confirm(data?)

1element.confirm({
2  client_secret: 'replace-with-your-client-secret',
3});
4// or
5element.confirm({});

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 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('Element is ready');
3});

on('success', handler)

This event will be fired when the 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

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 form 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 the 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('clickConfirmButton', handler)

This event will be fired when the user clicks the confirm button.

Parameters

type

required'clickConfirmButton'
The event name.

handler

required() => void
The callback function that will be called when the event occurs.

on('clickConfirmButton', handler)

1element.on('clickConfirmButton', () => {
2  console.log('Confirm button clicked');
3});

on('switchMethod', handler)

This event will be fired when the user switches the payment method.

Parameters

type

required'switchMethod'
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('switchMethod', handler)

1element.on('switchMethod', (e) => {
2  const { method, methodName, surchargeFee } = e.detail;
3  console.log('User switched to', { method, methodName, surchargeFee });
4});

on('pendingVerifyAccount', handler)

This event will be fired when the user is pending to verify their account. It is only used in the direct debit payment method.

Parameters

type

required'pendingVerifyAccount'
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('pendingVerifyAccount', handler)

1element.on('pendingVerifyAccount', (e) => {
2  const { intent, url } = e.detail;
3  console.log('User is pending to verify their account', { intent, url });
4});

on('surchargeFeeChange', handler)

This event will be fired when the surcharge fee changes.

Note: This event is specifically for surcharge fee updates. It may fire when switching payment methods if the new method has different fees. For general form state changes (completeness, input values, errors), use the change event instead.

Parameters

type

required'surchargeFeeChange'
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('surchargeFeeChange', handler)

1element.on('surchargeFeeChange', (e) => {
2  const { methodType, methodLabel, surchargeFee, currency, base_amount } = e.detail;
3  console.log('Surcharge fee changed', { methodType, methodLabel, surchargeFee, currency, base_amount });
4});

on('change', handler)

This event will be fired when the form data changes. Only triggered when showConfirmButton is set to false.

Note: This event focuses on form state changes (completeness, input values, errors). For surcharge fee updates, use the surchargeFeeChange event instead.

Parameters

type

required'change'
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('change', handler)

1element.on('change', (e) => {
2  const { complete, empty, selectedPaymentMethod, value, error } = e.detail;
3  console.log('Form changed', { complete, empty, selectedPaymentMethod, value, error });
4});

trigger('intentRefetch')

Call this function to refetch the latest intent information.

Parameters

type

required'intentRefetch'
The event name.

trigger('intentRefetch')

1element.trigger('intentRefetch');

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

optionalDropInElementOptions

allowedCardNetworks

optional('visa' | 'mastercard' | 'maestro' | 'unionpay' | 'amex' | 'jcb' | 'diners' | 'discover')[]
One or more card networks that you support.

appearance

optionalDropInAppearance
Customize the visual appearance of the DropIn Element to match your website's design.

applePayRequestOptions

optionalApplePayRequestOptions
Checkout configuration options for Apple Pay.

authFormContainer

optionalstring
The container of the authentication form used in 3D Secure authentication.

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 pre_auth is 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

autoSaveCardForFuturePayments

optionalboolean

Specifies whether the card payment method should be automatically saved for future transactions.

This parameter is only effective in payment mode when a customer_id is provided.

  • If set to true, the "Save my card for future payments" checkbox will be preselected by default.
  • If set to false, the checkbox will remain unchecked, requiring the shopper to manually opt in.
Default: true

billing

optionalBilling

Billing information provided by the merchant. This option overrides the billing information from the shopper as provided in the input billing fields. Do not set withBilling and requiredBillingContactFields when you use this option.

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.

country_code

optionalstring
The two-letter ISO country code of the shopper's country. This is required for bank_transfer, online_banking, skrill or seven_eleven payment methods.

currency

optionalstring
The three-letter ISO currency code representing the currency of the Payment Intent or Payment Consent. Only payment methods supported for the specified currency will be shown on the payment page.

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'.

cvcRequired

optionalboolean
Whether you require the shopper to provide CVC when they checkout with a network tokenized card.

disableAutoCurrencyConversion

optionalboolean

Whether to force disable automatic currency conversion.

  • true: Overrides merchant settings to disable conversion.
  • false: Respects the merchant's automatic conversion configuration.
Default: false

googlePayRequestOptions

optionalGooglePayRequestOptions
Checkout configuration options for Google Pay.

intent_id

optionalstring
The ID of the Payment Intent you would like to checkout. Required when mode is 'payment'.

layout

optionalLayout
The layout of the DropIn element.

methods

optionalenum[]
The payment methods your website would like to integrate with.

mode

optional'payment' | 'recurring'
The checkout mode for the shopper, 'payment' or 'recurring'.
Default: 'payment'

payment_consent

optionalPaymentConsentOptions
The payment consent details.

platformConnectedAccount

optionalstring

When using Payments for Platforms, specify the ID of the connected account associated with the payment if you want to use its information to process the payment. For example, the statement descriptor displayed on the shopper's credit card or bank statement and the payment methods activated by the connected account.

quote_id

optionalstring | null

This field is used for Multi-Currency Pricing(MCP). The merchant can create a quote for the shopper, and pass the quote_id to Drop-in Element. If the quote_id is provided, Drop-in Element will use that quote to convert the amount and currency. And each time the shopper changes the currency, the merchant needs to create a new quote or reuse existing quotes and update the quote_id. If the quote_id is not provided, Drop-in Element will use ACC logic to automatically convert the amount and currency.

requiredBillingContactFields

optional('name' | 'email' | 'country_code' | 'address' | 'phone')[]
The billing information that you require from the user in order to process the transaction.

savedPaymentMethod

optionalSavedPaymentMethodOptions
The options for saved payment method.
Default: { displayMode: 'auto', saveMode: 'auto' }

shopper_email

optionalstring
The shopper's email address.

shopper_name

optionalstring
The shopper's full name.

shopper_phone

optionalstring
The shopper's phone number.

showConfirmButton

optionalboolean

Whether to display the built-in confirm button. Default is true. When set to false:

  • The confirm button will be hidden
  • Only card payment method will be displayed, other payment methods will be hidden
  • You must implement your own button and call dropInElement.confirm() to submit the payment
Default: true

style

optionalBoxStyle
Box style for the dropIn element.

submitType

optional'pay' | 'book' | 'subscribe' | 'save'

Describes the type of transaction being performed in order to customize the submit button text. Available options are 'pay', 'book', or 'subscribe'. The type can only be specified in payment mode. If blank, the default value will be 'pay'

Default: 'pay'

wechatpay

optionalWeChatPayFlow
The options for Wechat Pay.

components

optionalenum[]Deprecated
The payment methods your website would like to integrate with
use methods instead

recurringOptions

optionalRecurringOptionsDeprecated
Options for recurring flow.
use payment_consent instead

withBilling

optionalbooleanDeprecated
Indicate to improve 3DS experience, indicate if the payment form will collect billing info from shopper
please use requiredBillingContactFields instead

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  methods: ['card'],
3}, {
4  locale: 'en',
5});
Was this page helpful?