Airwallex 付费网络SDK

Airwallex Payouts Web SDK包括嵌入式付费组件和嵌入式受益人组件,这些组件是预建的UI元素,您可以整合到自己的用户流中. 而不是从零开始,你现在可以利用它们来提供用户体验,充分利用Airwalex的覆盖范围,同时减少开发努力,提高市场速度.

演示和文件

要查看和与嵌入式组件互动,请访问 嵌入组件演示站点。 。 。 .

要查看高层次的集成序列和分步骤指南,请参见我们的产品文件 嵌入式付款部分 财务报告和审定财务报表 嵌入式受益部分。 。 。 .

安装

用 Yarn 安装

yarn add @airwallex/payouts-web-sdk

或者,与国家预防机制

npm install @airwallex/payouts-web-sdk

初始化

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

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

await init(options);

初始化错误

创建元素

打电话 createElement(type, options) 以创建元素对象.

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

const element = createElement(type, options);

方法参数

options 对象属性

defaultValues 对象属性 :

可用默认值指定的字段列于以下对象中

• 支付部分 : API 文件中定义的支付对象
• 受益部分: API 文件中定义的受益对象

// 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 对象属性 :

自定义允许您禁用或隐藏 Payout 组件中的一些字段或 UI 组件

fields 对象属性 :

// 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 对象属性 :

受益人表格中的信息可分为三类:受益人银行条件、银行详情和受益人详情。 您可以使用布局定制特性来渲染表格的任何部分.

如果您想要隐藏任何字段或区域,请确保提供默认值.

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 对象属性 :

我们支持嵌入式组件的主题。 为了最好地将品牌需求与我们的综合主题系统相匹配,请与您的账户管理器联系,以便我们能提供定制的JSON供您设定主题属性的值.

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

创建元素错误

与 element 对象

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

挂载元素

元素创建后, 将其挂入您的网页

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

const element = createElement(type, options);

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

挂载出错

订阅事件

添加事件听众来处理从Airwallex收到的事件. 事件可用于方便用户界面中的其他流动。 详情请见以下事件列表.

您可以通过监视更改事件的值,根据用户输入引入不同的调用动作. 例如,你可以根据源量触发一个批准流,即当它超过一定阈值时,可以引导用户通过不同的用户流.

也可以作为窗体状态事件的一部分来监视出错,并为用户提供额外的指导,以便他们能修正出错. 可能的错误列表可见"出错与事件"一节.

以下类型的事件可在支付元件的生命周期内被排放出.

Ready

当页面中的组件可以进行用户交互时,此事件会起火.

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

Error

当页面中的组件被挂起但因错误而未能工作时,此事件会起火 。 发生错误时处理这些错误.

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

可能的错误代码

Change

当组件中的值发生变化时,此事件会起火 .

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

FormState

当组件的形式状态发生变化时,此事件会起火. 国家包括表单渲染过程中的加载、验证和出错.

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

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

可能的错误代码

您可以使用下面的错误代码来映射自己的消息 。 Airwallex建议的错误信息也可供您参考.

从 submit 方法

准备取回最终有效载荷时,可以调用提交函数. 它会触发组件中所有字段的验证,并将有效载荷还给你.

  const results = await element.submit()

结果有效载荷

additionalInfo 对象

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