Airwallex.js

We're excited to introduce our new, comprehensive documentation site for Airwallex.js. Airwallex.js consolidates all Airwallex Elements into a single, unified SDK for greater efficiency and ease of integration. The SDK includes:

• Payment Elements (Card, Apple Pay, Google Pay, etc.)
• Payout Elements (Beneficiary, Transfer, Tax Form)
• Onboarding Elements (KYC, KYB)
• Risk Elements (RFI)
• Compliance Support Elements (SCA)

If you're using any of the legacy SDKs listed below, we recommend upgrading to the new Airwallex.js SDK to access the latest features and enhancements.

• Airwallex Payment Elements
• Airwallex Payouts SDK

• Airwallex.js
  • Installation
  • Initialization
    • Create an Element
      • Method parameters
      • options object properties:
      • Example
  • element object
    • Mount the element
    • Unmount the element
    • Destroy the element
    • Listen to element events
  • KYC Element Events
    • ready
    • success
    • cancel
    • error
  • Payments KYB Element Events
    • ready
    • success
    • reserveOptionsOffered
    • selectReserve
    • cancel
    • error
  • RFI Elements Events
    • ready
    • success
    • cancel
    • error
  • SCA Elements Events
    • ready
    • scaSetupSucceed
    • verificationSucceed
    • verificationFailed
    • resetPasscodeSucceed
    • cancel
    • error
  • Theming
• CHANGELOG

Installation

Use @airwallex/components-sdk

Install with Yarn

yarn add @airwallex/components-sdk

Or, with NPM

npm install @airwallex/components-sdk

Initialization

import { init } from '@airwallex/components-sdk';

const options = {
  locale: 'en',
  env: 'prod',
  authCode: 'x4D7A7wOSQvoygpwqweZpG0GFHTcQfVPBTZoKV7EibgH',
  clientId: 'BIjjMYsYTPuRqnkEloSvvf',
  codeVerifier:
    '~wh344Lea1FsCMVH39Fn9R2~nqq2uyD4wbvG9XCzWRxd0sZh9MFiF9gSVkM0C-ZvrdtjBFA6Cw1EvCpJcIjaeXg1-BXCfZd25ZmvuYZAqZtjJQA3NAa~7X1sgEfbMZJwQ',
};

await init(options);

Create an Element

Call createElement(elementName, options) to create an element object.

Method parameters

options object properties:

Example

import { createElement } from '@airwallex/components-sdk';

const options = {
  hideHeader: true,
  hideNav: true,
};

const element = await createElement('kyc', options);

element object

export type EVENT_TYPE = 'ready' | 'success' | 'error' | 'cancel';

interface Element {
  /**
   * Mount element to your HTML DOM element
   */
  mount(domElement: string | HTMLElement): void;
  /**
   * Using this function to unmount the element, opposite to mount function
   * The element instance is still kept
   */
  unmount(): void;
  /**
   * Using this function to destroy the element instance
   */
  destroy(): void;
  /**
   * Listen to event
   */
  on(
    eventCode: EVENT_TYPE,
    handler: (eventData: Record<string, unknown>) => void,
  ): void;
}

Mount the element

Mount the element to your page.

// type
element.mount: (domElement: string | HTMLElement) => void

// There are two ways to mount element:
// 1. call with container dom id
element.mount('container-dom-id');

// 2.find the created DOM in existing HTML and call with container DOM element
const containerElement = document.getElementById("container-dom-id");
element.mount(containerElement);

Unmount the element

Using this function to unmount the element, opposite to mount function. The element instance is still kept.

element.unmount();

Destroy the element

Using this function to destroy the element instance.

element.destroy();

Listen to element events

Using this function to listen to element events.

element.on('success', () => {
  // Handle success event
});

KYC Element Events

The Onboarding component might emit the following events during its lifecycle.

ready

This event will be fired when:

• Consent page is ready, if it is enabled. The event data will be { type: 'consent'}. Use this event to decide when to remove loading status from your page.
• Kyc page is ready. The event data will be {type: 'kyc', kycStatus: 'INIT'}, which represents the account's onboarding status. Use kycStatus to render your own status pages and handle re-entry scenarios.

Type

type kycEventData = {
  type: 'kyc',
  kycStatus: 'INIT' | 'SUBMITTED' | 'SUCCESS' | 'FAILURE'
};

type consentEventData = {
  type: 'consent'
};

element.on('ready', (data: kycEventData | consentEventData) => void);

Example

element.on('ready', (data: kycEventData | consentEventData) => {
  // Handle ready event
});

success

This event fires when the onboarding flow is completed successfully.

Type

element.on('success', () => void);

Example

element.on('success', () => {
  // Handle success event
});

cancel

This event fires when the element is exited by cancellation.

Type

element.on('cancel', () => void);

Example

element.on('cancel', () => {
  // Handle cancel event
});

error

This event fires when an error occurs within the element.

Type

type errorCode = 'API_ERROR' | 'SUBMIT_FAILED' | 'UNKNOWN';
type ErrorData = { code: errorCode, message?: string }

element.on('error', (data: ErrorData) => void);

Example

element.on('error', (data: ErrorData) => {
  // Handle error event
});

Payments KYB Element Events

ready

This event will be fired when the Payments Kyb element is ready for starting the Kyb application. If PERMISSION_DENIED error takes place, this event will not be triggered.

data Type

{
  kybStatus: 'PENDING_REVIEW' | 'IN_REVIEW' | 'REJECTED' | 'ACCEPTED' | 'APPROVED',
  kycStatus: 'INIT' | 'SUBMITTED' | 'SUCCESS' | 'FAILED'
}

success

This event fires when the initial KYB case is submitted successfully.

data Type

{
  storeList: Array<StoreObject>;
}

reserveOptionsOffered

This is only for when the reserve selection is available for the accounts. Contact Account Manager for more detail.

data Type

{
  reserveOptions: UserReserveSelection;
}

selectReserve

This is what the user selects for the reserve option. Only for when the reserve selection is available for the accounts. Contact Account Manager for more detail.

data Type

{
  selected: UserReserveSelection;
}

cancel

This event fires when the element is exited by cancellation.

Type

element.on('cancel', () => void);

Example

element.on('cancel', () => {
  // Handle cancel event
});

error

See Errors section below

data Type

{ code: string, message?: string }

RFI Elements Events

ready

This event will be fired when:

• RFI page is ready. The event data will be:
  • {type: 'kycRfi' | 'paymentEnablementRfi' | 'transactionRfi' | 'mrmRfi'}

Type

type RfiEventData = {
  type: 'kycRfi' | 'paymentEnablementRfi' | 'transactionRfi' | 'mrmRfi',
};

element.on('ready', (data: RfiEventData) => void);

Example

element.on('ready', (data: RfiEventData) => {
  // Handle ready event
});

success

This event fires when the rfi flow is completed successfully.

Type

type RfiSuccessEventData = {
  rfiId: string;
};

element.on('success', (data: RfiSuccessEventData) => void);

Example

element.on('success', (data: RfiSuccessEventData) => {
  // Handle success event
});

cancel

This event fires when the element is exited by cancellation.

Type

element.on('cancel', () => void);

Example

element.on('cancel', () => {
  // Handle cancel event
});

error

This event fires when an error occurs within the element.

Type

type errorCode = 'API_ERROR' | 'SUBMIT_FAILED' | 'INVALID_KYC_STATUS' | 'INVALID_RFI_STATUS' | 'UNKNOWN';
type ErrorData = { code: errorCode, message?: string }

element.on('error', (data: ErrorData) => void);

Example

element.on('error', (data: ErrorData) => {
  // Handle error event
});

SCA Elements Events

ready

This event will be fired when: sca page is ready.

Type

element.on('ready', () => void);

Example

element.on('ready', () => {
  // Handle ready event
});

scaSetupSucceed

This event will be fired when SCA has been successfully configured by users:

Type

element.on('scaSetupSucceed', (
  data: {
    mobileInfo?: {
      /** countryCode is represented as pure number codes string, such as '44'. */
      countryCode: string;
      nationalNumber: string;
    }
  }) => void);

Example

element.on('scaSetupSucceed', () => {
  // Handle event
});

verificationSucceed

This event triggers when the SCA flow is authenticated successfully

Type

element.on('verificationSucceed', ({token}: {token:string}) => void);

Example

element.on('verificationSucceed', ({ token }: { token: string }) => {
  // Handle success event
});

verificationFailed

This event triggers when the SCA flow authentication fails.

Type

element.on('verificationFailed', ({reason}:{reason:string}) => void);

Example

element.on('verificationFailed', () => {
  // Handle event
});

resetPasscodeSucceed

This event triggers when the user successfully resets their passcode

Type

element.on('resetPasscodeSucceed', () => void);

Example

element.on('resetPasscodeSucceed', () => {
  // Handle event
});

cancel

This event fires when the element is exited by cancellation.

Type

element.on('cancel', () => void);

Example

element.on('cancel', () => {
  // Handle cancel event
});

error

This event fires when an error occurs within the element.

Type

element.on('error', (data: { code: string, message?: string }) => void);

Example

element.on('error', (data: { code: string; message?: string }) => {
  // Handle error event
});

Theming

We can configure the Elements to reflect your brand's color palette and logo. Contact your Airwallex Account Manager to enable customization in line with your business requirements.

CHANGELOG

1.36.0 (2026-10-21)

Features

• expose appearance on BeneficiaryFormOptions [GCORP-4447] (e9bf674)

1.35.2 (2026-09-15)

Bug Fixes

• [OSAI-13450] add balance elements (32d9f65)

1.35.1 (2026-08-04)

Bug Fixes

• [GTA-4230] make publish-npm version bump idempotent (ac4a221)
• [OSAI-13217] rename NPM_TOKEN (07a61b7)

1.35.0 (2026-07-08)

Features

• [OSAI-13212] Support deploy to SG preview (f399bab)

1.34.0 (2026-06-29)

Features

• ADV-7443 reload billing types from remote source (57cfc8a)

1.27.2 (2025-11-07)

Bug Fixes

• [AJS-184] Add init log (30b4b87)

1.27.1 (2025-11-04)

Bug Fixes

• [AJS-184] Prefetch PA script (63155d7)
• [AJS-184] Support to prefetch payments script (a7b8a1c)

1.27.0 (2025-10-21)

Features

• [PACST-6601] Change kr card element naming, 2 to two (d58abac)

1.26.0 (2025-09-26)

Features

• [PACST-6601] Add kr card split element (13c1f27)

1.25.0 (2025-09-08)

Features

• update airtracker (cebbe20)
• update type (963343b)

1.24.2 (2025-07-22)

Bug Fixes

• [AJS-179] Optimize error logs (80a6e6d)

1.24.1 (2025-07-18)

Bug Fixes

• @airwallex/components running in Next.js (f63c268)
• hidden unused type (37f8bd7)

1.24.0 (2025-07-16)

Features

• [OBD-5984] Update README.md to include 'mrmRfi' (98e8894)

1.23.0 (2025-07-15)

Features

• [OBD-5739] add mrmRfi support with event handling in KycRfi (a167f85)
• [OBD-5739] enhance KycRfi event handling with generic EventCode type parameter for improved type inference (b772056)
• [OBD-5739] implement mrmRfi support in EcosystemApp (bcddaae)

1.22.3 (2025-07-04)

Bug Fixes

• [AJS-178] Update error message (0a87f17)

1.22.2 (2025-07-04)

Bug Fixes

• [AJS-178] Add invalid element type error (b70a0c7)

1.22.1 (2025-07-03)

Bug Fixes

• [AJS-178] Update error message (9f528ef)

1.22.0 (2025-07-03)

Bug Fixes

• pipeline (12bda3a)

Features

• update cache policy (fa5f3ca)

1.21.0 (2025-06-11)

Features

• [OBD-5580] update types (8cccff4)

1.20.1 (2025-05-30)

Bug Fixes

• [OBD-5489] support lending RFI (87b53f3)

1.20.0 (2025-05-15)

Features

• [DEVX-1874] update pa types: add apperance option (0daa844)

1.19.1 (2025-04-22)

Bug Fixes

• [OBD-5222] theme type in options (0d05e2a)
• add sca regression test (08d5f83)

1.19.0 (2025-04-08)

Features

• update types (2407fd8)
• update types (221283b)

1.18.0 (2025-02-24)

Features

• address to comment (5824889)
• update (71f0e56)
• update readme. (01e85be)

1.17.2 (2025-01-14)

Bug Fixes

• [osai-11299] update payment type source and sca type (221e19d)

1.17.1 (2025-01-13)

Bug Fixes

• update sdk name (638190c)

1.17.0 (2024-12-27)

Features

• add missing langKey (6d81f49)
• add ro & pt locale (02a9add)
• format (df90de4)

1.16.0 (2024-12-19)

Features

• add init enabledElement option (239af6a)
• address comment (e98562e)

1.15.0 (2024-12-16)

Features

• change pa static url (0ed7b86)

1.14.2 (2024-10-21)

Bug Fixes

• [AJS-161] update payout component types (5e22d39)

1.14.1 (2024-10-18)

Bug Fixes

• [PFF-3463] README column issue (902c9c9)

1.14.0 (2024-10-16)

Features

• [osai-10331] add tax form into sdk (9763153)

1.13.0 (2024-09-12)

Features

• update types (30633a1)

1.12.2 (2024-09-12)

Bug Fixes

• [AJS-150] Update README (aa44137)

1.12.1 (2024-09-11)

Bug Fixes

• [osai-10516] rename some properties of sca (a2dea75)

1.12.1 (2024-09-11)

Bug Fixes

• [osai-10516] rename some properties of sca (a2dea75)

1.12.0 (2024-09-10)

Features

• [osai-10516] add mobile info in sca setup succeed event (a47522a)

1.11.0 (2024-09-06)

Features

• [AJS-150] Support locale and deprecate langKey (b933de2)

1.10.2 (2024-08-27)

Bug Fixes

• [OBD-2931] clean up paymentsKyb typing (4055117)

1.10.1 (2024-08-26)

Bug Fixes

• update sca docs and types (031f3fe)

1.10.1 (2024-08-16)

Bug Fixes

• update sca docs and types (031f3fe)

1.10.0 (2024-08-07)

Features

• change PA static url (e640c5a)

1.9.2 (2024-08-06)

Bug Fixes

• [AJS-141] update paymentsKyb typing (f7b8fdc)

1.9.1 (2024-08-05)

Bug Fixes

• [AJS-139] add cancel event explaination on the js doc (1d3d08c)

1.9.0 (2024-07-30)

Features

• [AJS-67] prefetch scripts (e82e86d)

1.8.2 (2024-07-29)

Bug Fixes

• update README (f2b4ed5)

1.8.1 (2024-07-18)

Bug Fixes

• namespace missing export after bundle (c93d2bc)

1.8.0 (2024-07-18)

Features

• [osai-10139] update interface and docs and add sca functions (00f2cda)
• wrap all domain types with namespace (6f496c6)

1.7.1 (2024-06-28)

Bug Fixes

• [OBD-2389] fix pipeline (6f8d2c9)

1.7.0 (2024-06-28)

Features

• [OBD-2389] update types (caf702c)

1.6.0 (2024-06-28)

Bug Fixes

• [OBD-2083] Add paymentEnablement component (f913354)

Features

• add sca (bfb2b28)

1.5.0 (2024-05-13)

Features

• add perf log (ad526ef)

1.4.16 (2024-04-17)

Bug Fixes

• [OSAI-9559] log script loading time (1590e47)

1.4.15 (2024-04-07)

Bug Fixes

• [OSAI-9436] upload to multiple gcs (5c4a7d4)

1.4.14 (2024-04-03)

Bug Fixes

• [OSAI-9436] bucket version (9170595)

1.4.13 (2024-04-03)

Bug Fixes

• [OSAI-9436] bucket version (2cb6a3b)

1.4.12 (2024-04-03)

Bug Fixes

• [OSAI-9436] upload multi buckets (b44a27f)

1.4.11 (2024-03-08)

Bug Fixes

• Enhanced the implementation of CI for changelog updates (37094cb)