KYC Element

The KYC (Know Your Customer) Element allows platforms to onboard connected accounts globally with a single integration. It provides a frictionless, conversion-optimized experience by leveraging Airwallex’s latest capabilities for connected accounts. To explore the experience, go to the Airwallex demo site

createElement('kyc', options?)

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

Parameters

type

required'kyc'

The type of element you are creating.

options

optionalKycElementOptions

Options for creating kyc Element.

hideHeader

optionalboolean

If set to true, the onboarding flow header will be hidden, allowing platforms to configure a customized taskflow header on top the Element. By default, the header will be displayed within the onboarding flow and shows the platform's content.

locale

optional'en' | 'zh' | 'fr'

The locale for the Element, applied to Element UI strings and error messages. By default, the locale configured in init() is used.

The provided locale must be supported by the onboarding business’s registration country. For example, ‘fr’ is supported if the business is registered in Canada or an EU country.

For a full list of supported locales by country, see customization options.

navLayout

optional'side' | 'floating' | 'none'

Controls how the application progress tracker is displayed. When set, takes precedence over hideNav.

side (default): Shows a vertical navigation bar on the left-hand side.
floating: Shows a compact, collapsible navigation at the top (recommended for mobile).
none: Hides the navigation entirely.

Default:

ts
'side'

hideNav

optionalbooleanDeprecated

Hides the application progress tracker when set to true. When set to false or omitted, the tracker is shown using a vertical navigation bar on the left-hand side.

Note: hideNav is deprecated. Use navLayout instead to control how the application progress tracker is displayed.

If both navLayout and the legacy hideNav field are provided, navLayout takes precedence and hideNav is ignored. This ensures the new configuration is always applied consistently.

The values are migrated as follows:

When hideNav is set to true, navLayout: none
When hideNav is set to false, navLayout: side or floating, depending on your preferred layout.

Use navLayout instead. hideNav: true is equivalent to navLayout: 'none'.

langKey

optional'en' | 'zh' | 'fr'Deprecated

Use locale instead.

Returns

KycElement | null

createElement('kyc', options?)

1import { createElement } from '@airwallex/components-sdk';
2
3const element = await createElement('kyc', {
4  hideHeader: true,
5  hideNav: true,
6});

destroy()

Destroys the Element instance.

destroy()

1element.destroy();

mount(domElement)

Mounts Element to your HTML DOM.

Parameters

domElement

requiredstring | HTMLElement

The container DOM element to mount the element.

mount(domElement)

1// There are two ways to mount element:
2// 1. Call with container DOM id
3element.mount('container-dom-id');
4
5// 2. Find the created DOM in existing HTML and call with container DOM element
6const containerElement = document.getElementById('container-dom-id');
7element.mount(containerElement);

on('ready', handler)

This event will be fired when:

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

Parameters

type

required'ready'

The event name.

handler

requiredfunction

The callback function that will be called when the event occurs.

on('ready', handler)

1type kycEventData = {
2  type: 'kyc',
3  kycStatus: 'INIT' | 'SUBMITTED' | 'SUCCESS' | 'FAILURE'
4 };
5
6 type consentEventData = {
7   type: 'consent'
8 };
9
10  element.on('ready', (data: kycEventData | consentEventData) => {
11    console.log('KYC ready:', data.type);
12  });

on('success', handler)

This event fires when the onboarding flow is completed successfully.

Parameters

type

required'success'

The event name.

handler

required() => void

The callback function that will be called when the event occurs.

on('success', handler)

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

on('cancel', handler)

This event fires when the element is exited by cancellation.

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('KYC cancelled');
3});

on('error', handler)

This event fires when an error occurs within the element.

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:

code

required'API_ERROR' | 'SUBMIT_FAILED'

message

optionalstring

on('error', handler)

1type errorCode = 'API_ERROR' | 'SUBMIT_FAILED' | 'UNKNOWN';
2type ErrorData = { code: errorCode, message?: string }
3
4element.on('error', (data: ErrorData) => {
5  console.error('KYC error:', data.code, data.message);
6});

unmount()

Unmounts the Element. Note that the Element instance will remain.

unmount()

1element.unmount();

Was this page helpful?