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

``bash
yarn add @airwallex/components-sdk
`

Or, with NPM

`bash
npm install @airwallex/components-sdk
`

Initialization

`ts
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);
`

| Option | Type | Required? | Default value | Description |
| :------------- | :------- | :-------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| env | string | NO | prod | The Airwallex environment. Options include: staging, demo and prod. |
| locale | string | NO | en | Language. Options include: de, en, es, fr, it, ja, ko and zh. |
| clientId | string | YES | - | Unique Client ID issued by Airwallex. More on Airwallex WebApp - Developer - API Keys. |
| authCode | string | YES | - | Auth code to authenticate the connected account retrieved from /api/v1/accounts/{id}/authorize Embedded Component Authorization API. |
| codeVerifier | string | YES | - | Serves as proof key for code exchange (see RFC 7636 Section 4). A random string used for generating a codeChallenge. |

$3

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

#### Method parameters

| Parameter | Type | Required? | Description |
| :-------- | :------------------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | YES | The elements name of element. Supported values are payoutForm, beneficiaryForm, kyc, paymentsKyb, kycRfi, paymentEnablementRfi, transactionRfi, mrmRfi, scaManagement, scaVerify, scaSetup. |
| options | Record | NO | Options for creating an Element, which differ for each element type. |

#### options object properties:

| Element type | Property | Required? | Default value | Type | Description |
| :--------------------------------------------------------------------------------- | :--------------- | :-------- | :------------ | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| payoutForm, beneficiaryForm | defaultValues | NO | - | Form Value Object | Used to set the default values for the form. |
| | customizations | NO | - | Customizations Object | Contact your Account Manager for details. |
| | theme | NO | - | Theme Object | Contact your Account Manager for details. |
| kyc, paymentsKyb, kycRfi, paymentEnablementRfi, transactionRfi, mrmRfi | hideHeader | NO | false | boolean | Used to hide the page's header. |
| | hideNav | NO | false | boolean | Used to hide the page's navigation, which is heavily tied to the progression of the onboarding exercise. It is important to note that the user can review completed items, and edit if they need to adjust content. In addition, the user has another option to edit the form on the final review page. |
| | theme | NO | - | Theme Object | Contact your Account Manager for details. |
| scaSetup,scaVerify | userEmail | Yes | - | string | Used to recovery 2fa method |
| | scaSessionCode | No | - | string | It must be provided when initialising the embedded scaVerify component for a one-time SCA token |
| | contactEmail | No | - | string | Platfrom customer service email address |
| | theme | No | - | Theme Object | Contact your Account Manager for details. |
| | | | | | ############################## |

#### Example

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

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

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

element object

`ts
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) => void,
): void;
}
`

$3

Mount the element to your page.

`ts
// 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);

`

$3

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

`ts
element.unmount();
`

$3

Using this function to destroy the element instance.

`ts
element.destroy();
`

$3

Using this function to listen to element events.

`ts
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

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

type consentEventData = {
type: 'consent'
};

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

Example

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

#### success

This event fires when the onboarding flow is completed successfully.

Type

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

Example

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

#### cancel

This event fires when the element is exited by cancellation.

Type

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

Example

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

#### error

This event fires when an error occurs within the element.

Type

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

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

Example

`ts
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

`ts
{
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

`ts
{
storeList: Array;
}
`

#### reserveOptionsOffered

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

data Type

`ts
{
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

`ts
{
selected: UserReserveSelection;
}
`

#### cancel

This event fires when the element is exited by cancellation.

Type

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

Example

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

#### error

See Errors section below

data Type

`ts
{ 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

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

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

Example

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

#### success

This event fires when the rfi flow is completed successfully.

Type

`ts
type RfiSuccessEventData = {
rfiId: string;
};

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

Example

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

#### cancel

This event fires when the element is exited by cancellation.

Type

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

Example

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

#### error

This event fires when an error occurs within the element.

Type

`ts
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

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

SCA Elements Events

#### ready

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

Type

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

Example

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

#### scaSetupSucceed

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

Type

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

Example

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

#### verificationSucceed

This event triggers when the SCA flow is authenticated successfully

Type

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

Example

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

#### verificationFailed

This event triggers when the SCA flow authentication fails.

Type

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

Example

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

#### resetPasscodeSucceed

This event triggers when the user successfully resets their passcode

Type

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

Example

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

#### cancel

This event fires when the element is exited by cancellation.

Type

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

Example

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

#### error

This event fires when an error occurs within the element.

Type

`ts

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

Example

`ts
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.

1.27.2 (2025-11-07)

$3

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

1.27.1 (2025-11-04)

$3

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

1.27.0 (2025-10-21)

$3

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

1.26.0 (2025-09-26)

$3

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

1.25.0 (2025-09-08)

$3

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

1.24.2 (2025-07-22)

$3

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

1.24.1 (2025-07-18)

$3

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

1.24.0 (2025-07-16)

$3

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

1.23.0 (2025-07-15)

$3

* [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)

$3

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

1.22.2 (2025-07-04)

$3

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

1.22.1 (2025-07-03)

$3

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

1.22.0 (2025-07-03)

$3

* pipeline (12bda3a)

$3

* update cache policy (fa5f3ca)

1.21.0 (2025-06-11)

$3

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

1.20.1 (2025-05-30)

$3

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

1.20.0 (2025-05-15)

$3

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

1.19.1 (2025-04-22)

$3

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

1.19.0 (2025-04-08)

$3

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

1.18.0 (2025-02-24)

$3

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

1.17.2 (2025-01-14)

$3

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

1.17.1 (2025-01-13)

$3

* update sdk name (638190c)

1.17.0 (2024-12-27)

$3

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

1.16.0 (2024-12-19)

$3

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

1.15.0 (2024-12-16)

$3

* change pa static url (0ed7b86)

1.14.2 (2024-10-21)

$3

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

1.14.1 (2024-10-18)

$3

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

1.14.0 (2024-10-16)

$3

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

1.13.0 (2024-09-12)

$3

* update types (30633a1)

1.12.2 (2024-09-12)

$3

* [AJS-150] Update README (aa44137)

1.12.1 (2024-09-11)

$3

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

1.12.1 (2024-09-11)

$3

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

1.12.0 (2024-09-10)

$3

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

1.11.0 (2024-09-06)

$3

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

1.10.2 (2024-08-27)

$3

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

1.10.1 (2024-08-26)

$3

* update sca docs and types (031f3fe)

1.10.1 (2024-08-16)

$3

* update sca docs and types (031f3fe)

1.10.0 (2024-08-07)

$3

* change PA static url (e640c5a)

1.9.2 (2024-08-06)

$3

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

1.9.1 (2024-08-05)

$3

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

1.9.0 (2024-07-30)

$3

* [AJS-67] prefetch scripts (e82e86d)

1.8.2 (2024-07-29)

$3

* update README (f2b4ed5)

1.8.1 (2024-07-18)

$3

* namespace missing export after bundle (c93d2bc)

1.8.0 (2024-07-18)

$3

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

1.7.1 (2024-06-28)

$3

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

1.7.0 (2024-06-28)

$3

* [OBD-2389] update types (caf702c)

1.6.0 (2024-06-28)

$3

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

$3

* add sca (bfb2b28)

1.5.0 (2024-05-13)

$3

* add perf log (ad526ef)

1.4.16 (2024-04-17)

$3

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

1.4.15 (2024-04-07)

$3

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

1.4.14 (2024-04-03)

$3

* [OSAI-9436] bucket version (9170595)

1.4.13 (2024-04-03)

$3

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

1.4.12 (2024-04-03)

$3

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

1.4.11 (2024-03-08)

$3

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