@airwallex/components-sdk

Airwallex Components SDK

• Airwallex Components SDK
  • 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
    • caseStatusChanged
    • reserveOptionsOffered
    • selectReserve
    • error
  • RFI Elements Events
    • ready
    • success
    • 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 = {
  langKey: '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.
langKey	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.

Create an Element

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 kyc, paymentsKyb, kycRfi, paymentEnablementRfi and transactionRfi.
options	Record<string, unknown>	NO	Options for creating an Element, which differ for each element type.

options object properties:

Element type	Property	Required?	Default value	Type	Description
kyc, kycRfi, paymentEnablementRfi, transactionRfi	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.
paymentsKyb	hideHeader	NO	false	boolean	Hide top navigation inside the element.
	hideNav	NO	false	boolean	Hide left side navigation section inside the element.
	contactUrl	Yes	false	boolean	Specify localized customer support urls.
	brandName	Yes	false	boolean	Specify localized brand name for your business.
	theme	No	-	Theme Object	Contact your Account Manager for details.

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>
}

caseStatusChanged

This event fires when KYB case status changed

data Type - Same as ready

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
}

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

Type

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

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
});

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