# @airwallex/payouts-web-sdk 中文文档

规范地址：https://npmcn.com/package/%40airwallex/payouts-web-sdk/

版本：1\.5\.0
npm 元数据更新时间：2025-05-22T08:22:48.944Z
中文译文更新时间：2026-11-06T00:11:36.129Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40airwallex/payouts-web-sdk
原文对照：https://npmcn.com/package/%40airwallex/payouts-web-sdk/?lang=original
项目主页：https://github.com/airwallex/payouts-web-sdk#readme
源码仓库：https://github.com/airwallex/payouts-web-sdk

弃用说明：Package no longer supported\. Use @airwallex/components-sdk to access the latest features and enhancements\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：36.2 kB，5 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-12-21T01:55:48.245Z
- 最新版本发布：2024-01-15T10:53:00.745Z
- 近 30 天下载量：8319（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

支付网络SDK

## 安装

```sh
npm install @airwallex/payouts-web-sdk
```

也可以使用：`pnpm add @airwallex/payouts-web-sdk`、`yarn add @airwallex/payouts-web-sdk`、`bun add @airwallex/payouts-web-sdk`

## README

# Airwallex 付费网络SDK

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

## 演示和文件

要查看和与嵌入式组件互动,请访问 [嵌入组件演示站点](https://demo.airwallex.com/widgets/embedded-components)。 。 。 .

要查看高层次的集成序列和分步骤指南,请参见我们的产品文件 [嵌入式付款部分](https://www.airwallex.com/docs/payouts__embedded-payout-component) 财务报告和审定财务报表 [嵌入式受益部分](https://www.airwallex.com/docs/payouts__embedded-beneficiary-component)。 。 。 .

## 安装

用 Yarn 安装

```ts
yarn add @airwallex/payouts-web-sdk
```

或者,与国家预防机制

```ts
npm install @airwallex/payouts-web-sdk
```

## 初始化

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

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

await init(options);
```

| 选项 | 类型 | 需要吗? | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `env` | `string` | **无** | `prod` | 您想要整合您的应用程序的 Airwalex 环境 。 选项包括: `staging`, (中文(简体) ), `demo`, (中文(简体) ), `prod` |
| `langKey` | `string` | **无** | `en` | 语言. 选项包括: `en`, (中文(简体) ), `zh` |
| `clientId` | `string` | **对** | \- 说吧 | 你唯一的客户ID 由Airwalex发布。 您可以找到客户端的ID [`Airwallex WebApp - Developer - API Keys`](https://www.airwallex.com/app/account/apiKeys) |
| `authCode` | `string` | **对** | \- 说吧 | 认证账户的认证码 [`Embedded components API`](https://www.airwallex.com/docs/api#/Scale/Embedded_Components/Intro) |
| `codeVerifier` | `string` | **对** | \- 说吧 | 用作代码交换的证明钥匙(见RFC 7636 第4节). 由自己选择的随机字符串,用来生成代码Challenge. |

### 初始化错误

| 代码 | 消息 | 下一个步骤 |
| --- | --- | --- |
| 失败的( LOAD- SCRIPT) | 预期文档. body not be null, 需要一个 <body> 元素. | 确保您在客户端中添加了 SDK , 并在 HTML 中添加了 <body> 元素 |
| 失败的( LOAD- SCRIPT) | 装入 SDK 脚本失败, 请检查您的网络 | 请检查您的网络并再次尝试 |
| 参数( P) | 无效的 { option key} | SDK在初始化时得到了一个不支持的参数. 请检查参数表是否为有效选项 . |
| 参数( P) | 未提供 {参数} | 缺少所需的参数 。 请检查参数表以查看所需的选项 . |
| 未经授权 | `clientId`, (中文(简体) ), `authCode` 财务报告和审定财务报表 `codeVerifier` 不匹配 . | 请检查认证是否完成,成功生成了代码验证器,并为同一授权链提供了匹配值. |
| 定义 | 刷新令牌过期 | 这个 `refreshToken` 已过期。 请通过重取新的认证代码并初始化SDK来重启整个流量,然后再次创建元素. |
| 自动启动 | 30秒后自动超时, 请检查您的网络 | 请重新启动整个流量以获得新的认证代码,初始化组件,再创建组件 . |

## 创建元素

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

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

const element = createElement(type, options);
```

### 方法参数

| 参数 | 类型 | 需要吗? | 说明 |
| --- | --- | --- | --- |
| `type` | `string` | **对** | 您正在创建的元素类型 。 支持的类型 : `payoutForm`, (中文(简体) ), `beneficiaryForm` |
| `options` | `Record<string, unknown>` | **无** | 创建元素时的选项 。 参见下表. |

#### `options` 对象属性

| 支助构成部分 | 财产 | 类型 | 需求 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 付款部分,受益人部分 | 默认值 | 记录 < string, unkown > | 虚假 | 未定义 | 指定组件中渲染的字段的默认值.  |
| 付款部分,受益人部分 | 定制 | 记录 < string, unkown > | 虚假 | 未定义 | 组件上的自定义 . |
| 付款部分,受益人部分 | 主题 | 记录 < string, unkown > | 虚假 | 未定义 | 支持 Payout 组件的色彩主题 . |

#### `defaultValues` 对象属性 :

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

-   支付部分 : [API 文件中定义的支付对象](https://www.airwallex.com/docs/api#/Payouts/Payments/_api_v1_payments_create/post)
-   受益部分: [API 文件中定义的受益对象](https://www.airwallex.com/docs/api#/Payouts/Beneficiaries/_api_v1_beneficiaries_create/post)

```ts
// 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 组件

| 支助构成部分 | 财产 | 类型 | 需求 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 付款部分,受益人部分 | 字段 | 对象 | 虚假 | 未定义 | 用于禁用或隐藏单个字段的配置 。 我们建议在使用字段属性时提供默认值 . |
| 受益部分 | 版式 | 对象 | 虚假 | 未定义 | 用于隐藏某些类字段的配置, 这样您就可以有选择地制作窗体 . |
| 付款部分,受益人部分 | 欧 | 对象 | 虚假 | 未定义 | 隐藏某些 UI 组件的配置 . |

#### `fields` 对象属性 :

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

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

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

```ts
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供您设定主题属性的值.

```ts
  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 () 之前输入 | 请确认您用我们软件包或CDN链接的init()函数正确装入了 SDK 脚本 . |

## 与 `element` 对象

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

### 挂载元素

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

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

const element = createElement(type, options);

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

#### 挂载出错

| 代码 | 消息 | 下一个步骤 |
| --- | --- | --- |
| (原始内容存档于2017-09-21) (中文(简体) ). MUNT CONTER NOT EXIST | 挂载容器不存在 | 请检查dom id 或dom 元素在 Mount () 函数中通过是否有效 . |

### 订阅事件

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

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

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

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

#### `Ready`

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

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

#### `Error`

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

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

##### 可能的错误代码

| 构成部分 | 代码 | 说明 | 下一步 |
| --- | --- | --- | --- |
| 付款部分,受益人部分 | 职业介绍所: | 这个 `beneficiary_id` 中提供的默认值无效. | 提供属于该账户的有效受益人身份,或为受益人指定参数. |
| 付款部分,受益人部分 | SCHEMA NOT FOUND (英语) | 这个 `defaultValue` 提供不支持我们的计划. | 提供支持的数值组合 `sourceCurrency`, (中文(简体) ), `paymentCurrency`, (中文(简体) ), `bankCountryCode`, (中文(简体) ), `paymentMethod`,以及 `localClearingSystem`。 。 。 . |

#### `Change`

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

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

#### `FormState`

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

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

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

#### 可能的错误代码

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

| 构成部分 | 代码 | 说明 | 下一步 |
| --- | --- | --- | --- |
| 付款部分,受益人部分 | SCHEMA NOT FOUND (英语) | 我们的计划不支持所提供的数值. | 提供支持的数值组合 `sourceCurrency`, (中文(简体) ), `paymentCurrency`, (中文(简体) ), `bankCountryCode`, (中文(简体) ), `paymentMethod`,以及 `localClearingSystem`。 。 。 . |
| 支付部分 | 缩写: | 金额超过转移限额. | 提供较低的金额. |
| 支付部分 | 甲型联赛(AMUNT-ABY) | 金额超过转移限额. | 提供较低的金额. |
| 支付部分 | 弹出声道 | 这一数额低于最低转移限额. | 提供更高的金额. |
| 支付部分 | AFTER FEE IS TOO 小写 | 这一数额低于扣除支付费用后的最低转移限额. | 提供更高的金额. |
| 支付部分 | (中文(简体) ) | 此金额仅支持小数点后三位数最大值 . | 提供不超过小数点后三位数的有效金额. |
| 支付部分 | (中文(简体) ) | 此数值仅支持两个小数位最大值 . | 提供不超过两个小数位数的有效金额. |
| 支付部分 | (中文(简体) ) | 此金额不支持任何小数位 . | 提供有效数量而不设小数位. |
| 支付部分 | 输入( A) | 这一数额只能是正数. | 提供正数. |
| 支付部分 | 输入( S) | 不支持付款日期 . | 提供有效的付款日期. |
| 支付部分 | 竞价 货币 公平 | 这个 `sourceCurrency` 财务报告和审定财务报表 `paymentCurrency` 此账户不支持或启用指定的组合. | 提供支持 `sourceCurrency` 财务报告和审定财务报表 `paymentCurrency` 双人. |
| 支付部分 | (简体中文) | 此账户不支持或启用指定的货币. | 提供有效的来源 即时或支付 . |
| 支付部分 | 错过 FEE CONF | 此账户的付费配置有问题. | 联系您的账户管理员并报告这个问题 . |
| 受益部分 | 评估( F) | 请求失败了我们的计划验证 | 检查窗体上的错误, 并用接受的值更新 . |

### 从 `submit` 方法

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

```ts
  const results = await element.submit()
```

#### 结果有效载荷

| 支助构成部分 | 财产 | 类型 | 说明 |
| --- | --- | --- | --- |
| 付款部分,受益人部分 | 数值 | 对象 | 用户在组件中指定的值. |
| 付款部分,受益人部分 | 错误 | 窗体状态错误 | 组件中出现出错 。 检查窗体状态出错的细节 . |
| 支付部分 | 额外信息 | 对象 | 附加信息,包括可以选择的支付理由和引用信息. |

#### `additionalInfo` 对象

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

## 常见问题

### @airwallex/payouts-web-sdk 是什么？

支付网络SDK注意：该包已被作者标记为弃用——Package no longer supported\. Use @airwallex/components-sdk to access the latest features and enhancements\.

### 如何安装 @airwallex/payouts-web-sdk？

在项目目录运行 npm install @airwallex/payouts-web-sdk，或使用 pnpm add / yarn add / bun add。

### @airwallex/payouts-web-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @airwallex/payouts-web-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @airwallex/payouts-web-sdk 可以商用吗？

@airwallex/payouts-web-sdk 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @airwallex/payouts-web-sdk 的下载量有多少？

根据 npm 官方下载统计，@airwallex/payouts-web-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 8,319 次，日均约 277 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @airwallex/payouts-web-sdk 还在维护吗？

最新版本 1\.5\.0 发布于 2024/01/15（2 年前）；至今共发布 11 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/12/21。作者已将其标记为弃用，新项目建议寻找替代方案。