Airwallex Payouts Web SDK

Airwallex Payouts Web SDK includes the Embedded Payout component and the Embedded Beneficiary component, which are pre-built UI elements you can integrate into your own user flows. Instead of building a flow from scratch, you can now use them to deliver a user experience that fully leverages Airwallex’s coverage while reducing development efforts and improving speed to market.

Demo and documentation

To view and interact with the Embedded components, go to the Embedded components demo site.

To view the high-level integration sequence and a step-by-step guide, see our Product Docs for Embedded Payout component and Embedded Beneficiary component.

Installation

Install with Yarn

yarn add @airwallex/payouts-web-sdk

Or, with NPM

npm install @airwallex/payouts-web-sdk

Initialization

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

const options = {
  langKey: 'en',
  env: 'prod',
  authCode: '<authCode>',
  clientId: '<clientId>',
  codeVerifier: '<codeVerifier>',
};

await init(options);

Initialization Errors

Create Element

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

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

const element = createElement(type, options);

Method parameters

options object properties

defaultValues object properties:

Fields that can be specified with default values are listed in the objects below

• Payout Component: Payment Object defined in API docs
• Beneficiary Component: Beneficiary Object defined in API docs

// Field examples where defaultValue can be specified in the Payout component
const type DefaultValues = {
  beneficiary_id?: string;
  source_currency?: string;
  source_amount?: number;
  payment_currency?: string;
  payment_amount?: number;
  fee_paid_by?: 'PAYER' | 'BENEFICIARY';
  payment_date?: string;
  beneficiary?: {
      bank_details?: {
          bank_country_code?: string;
          local_clearing_system?: string;
      },
      entity_type?: 'COMPANY' | 'PERSONAL'
  },
  swift_charge_option?: 'SHARED' | 'PAYER',
  payment_method: 'SWIFT' | 'LOCAL'
}

customizations object properties:

Customizations allow you to disable or hide some fields or UI components from the Payout component

fields object properties:

// Fields and UI components that can be customized in the Payout component
const type Customizations = {
  ui?: {
    hideTransferFee?: boolean;
    hideFeeConfig?: boolean;
    hideFlightTime?: boolean;
  },
  fields?: {
    source_currency?: {
      disabled: boolean;
    },
    source_amount?: {
      disabled: boolean;
    },
    payment_currency?: {
      disabled: boolean;
    },
    payment_amount?: {
      disabled: boolean;
    },
    payment_date?: {
      disabled: boolean;
      hidden: boolean;
    },
    'beneficiary.bank_details.bank_country_code'?: {
      disabled: boolean;
      hidden: boolean;
    },
    'beneficiary.bank_details.local_clearing_system'?: {
      disabled: boolean;
      hidden: boolean;
    },
    'beneficiary.entity_type'?: {
      disabled: boolean;
      hidden: boolean;
    },
    swift_charge_option?: {
      disabled: boolean;
      hidden: boolean;
    }
  }
}

layout object properties:

The beneficiary form contains information that can be grouped into three categories, the beneficiary bank conditions, bank details, and beneficiary details. You can render any part of the forms with the layout customization feature.

If you want to hide any fields or sections, make sure default values are provided.

import { createElement } from '@airwallex/payouts-web-sdk'

// When you have collected address information from your beneficiaries
// and do not want to collect again using the component
const beneficiaryComponentElement = sdk.createElement('beneficiaryForm',{
  customizations: {
    layout: [
      { name: 'address', hidden: true },
    ]
  }
});

// When you have a preferred payment_method and local_clearing_system
// and only needs to collect bank details, you need to provide default values
// for the beneficiary bank conditions
const beneficiaryComponentElement = sdk.createElement('beneficiaryForm',{
  defaultValues: {
    beneficiary: {
      entity_type: 'COMPANY',
      bank_details: {
        account_currency: 'AUD',
        bank_country_code: 'AU',
        local_clearing_system: 'BANK_TRANSFER',
      },
    },
    payment_methods: ['LOCAL'],
  },
  customizations: {
    layout: [
      { name: 'conditions', hidden: true },
    ]
  }
});

theme object properties:

We support theming for embedded components. To best match your branding needs with our comprehensive systems of themes, please contact your Account Manager so we can provide a tailored JSON for you to set the value of the theme property.

  const type ColorPattern = {
    '10': string;
    '20': string;
    '30': string;
    '40': string;
    '50': string;
    '60': string;
    '70': string;
    '80': string;
    '90': string;
    '100': string;
  }


 const type Theme = {
  palette: {
    primary: ColorPattern;
    secondary: ColorPattern;
    error: ColorPattern;
  };
 }

CreateElement Errors

Interact with element object

export type EVENT_TYPE = 'ready' | 'change' | 'error' | 'formState'

interface Element {
  /**
   * Mount element to your HTML DOM element
   */
  mount(domElement: string | HTMLElement): void;
  /**
   * Use this function to unmount the element
   * The element instance remains
   */
  unmount(): void;
  /**
   * Use this function to destroy the element instance
   */
  destroy(): void;
  /**
   * Use this function to Submit form and get final formValues
   */
  submit(): FormValues
  /**
   * Listen to events
   */
  on(eventCode: EVENT_TYPE, handler: (eventData: Record<string, unknown>) => void): void;
}

Mount element

Once the element is created, mount it to your web page

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

const element = createElement(type, options);

const container = document.getElementById('form-wrapper');
element.mount(container);

Mount Errors

Subscribe to Events

Add event listeners to handle events received from Airwallex. Events can be used to facilitate other flows in your user interface where applicable. Please find more details in the list of events below.

You can introduce different call-to-actions based on the user input by monitoring the values in the change event. For example, you can trigger an approval flow based on the source amount, i.e., when it is above a certain threshold amount, you can guide the user to go through a different user flow.

You can also monitor errors as part of the formState event and provide additional guidance for the users so they can fix the errors. The list of possible errors can be found in the Errors and events section.

The following types of events can be emitted during the lifecycle of the payoutComponent.

Ready

This event fires when the component in the page is ready for user interaction.

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

Error

This event fires when the component in the page is mounted but failed to work with errors. Handle these errors when they occur.

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

Possible Error Codes

Change

This event fires when a value in the component changes.

element.on('change', () => FormData);

FormState

This event fires when the form state of the component changes. States include loading, validating, and errors during form rendering.

type OnFormState = {
  loading: boolean;
  validating: boolean;
  errors: { code: ErrorCodes } | null;
}

element.on('formState', (state: OnFormState) => void);

Possible Error Codes

You can map your own messages with the error codes below. The error messages suggested by Airwallex are also available for your reference.

Get final payload from submit method

When you are ready to retrieve the final payload, you can call the submit function. It will trigger the validation of all fields in the component and return you the payload.

  const results = await element.submit()

Result payload

additionalInfo object

const type AdditionalInfo = {
  // The supported reasons for the payment_method and local_clearing_system selected
  reasons: Array<{
    label: string;
    value: string;
  }>,
  // The quote id used in the payout component alongside its validity, i.e., when it expires.         
  quote: {
    id: string;
    validity: {
      validFrom: string;
      validTo: string;
    }
  }
}