> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考速查表

> 其他 Waffo API 页面所指向的四张查询表：按国家和 Payout 方式划分的 Payout 收款人字段要求、创建订单时的条件必填字段、供自建收银台商户使用的完整 orderAction.actionData 字段列表，以及各 API 族（Payout、收单、订阅、提现）的错误码表。

Waffo 的多个页面会写"参见字段要求表"或"参见错误码列表"。
这些表格统一收录在本页。本页是**完整查询表**；相邻的两个页面
从不同角度覆盖了同样的内容，通常读起来更快：

| 页面 | 用途 |
| - | - |
| [错误码快速参考](/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes) | 跨所有 API 查一个你刚收到的错误码 |
| [错误与排障](/docs/zh/support/errors-troubleshooting-guide) | 导致大多数集成失败的少数几个错误码及其修复方法 |
| **本页** | **某一个** API 族的完整表格，以及这些表格所引用的字段 |

快速参考里唯一查不到的是一个错误码属于哪个 API 族
——而有几个错误码在不同 API 族里含义不同。这就是下面的第一个问题。

## 同一个错误码在 Waffo 每个 API 上的含义都一样吗？

**不一样。** 错误码的数字部分是按 API 族划分的，不是全局的。尤其有三个错误码
是陷阱：

| 错误码 | 在收单（`/api/v1/order/*`）上 | 在 Payout 和提现上 |
| - | - | - |
| `A0013` | 订单无法取消——支付已成功 | 请求过多——另一个使用相同 `payoutRequestId` 的请求仍在处理中 |
| `A0014` | 因退款规则订单无法退款 | 不存在——参数完全相同的重复创建请求会返回普通的成功码及原订单 |
| `A0008` | 超出交易限额；支付金额必须在范围内 | 超出 Payout / 提现限额；金额必须在范围内 |

因此，`/api/v1/payout/create` 上的 `A0013` 表示你之前带该
`payoutRequestId` 的请求仍在处理中——请等待，然后先查询该请求，再重新提交；而
`/api/v1/order/cancel` 上的 `A0013` 是终态，不得重试。
务必按你所调用端点所属的 API 族来解读错误码。

前缀的含义在所有地方都是稳定的：`A` 商户相关，`B` 用户相关，`C`
系统相关，`D` 风控拒绝，`E` 未知（持续查询直到得到最终状态）。

## Payout 时我必须传哪些收款人字段，哪些要放进 `payoutMethodProperty`？

字段要求是一个**收款国家 × Payout 方式**的矩阵，而不是 API 本身的属性。
正因为如此，规范中把 `payeeFirstName`、`payeeMiddleName`、`payeeLastName` 和 `payeeIDType` 声明为
`conditional`。

| 国家 | `payoutMethodType` | `payoutMethodName` | 名 / 中间名 / 姓 | 国籍 | 生日 | 电话 | 邮箱 | `bankCode` | `addressInfo` |
| - | - | - | - | - | - | - | - | - | - |
| 印尼（`IDN`） | `BANK_ACCOUNT` | `IDN_BANK` | 非必填 | 非必填 | 非必填 | 非必填 | 非必填 | **必填** | 非必填 |
| 印尼（`IDN`） | `EWALLET` | `DANA` | 非必填 | 非必填 | 非必填 | 非必填 | 非必填 | 非必填 | 非必填 |

有两条身份规则写在矩阵之外的字段定义本身里：

| 国家 | 规则 |
| - | - |
| 中国大陆（`CHN`） | `payeeIDType` 为**必填**——传 `ID` 或 `PASSPORT`，并附上匹配的 `payeeIDNumber`。银行 Payout 还有额外的本地规则。 |
| 巴西（`BRA`） | `payeeIDType` 为**必填**，取值为 CPF / CNPJ。 |

对于其他所有通道，收款人字段由下游校验而非按国家规则校验，
所以请把你持有的信息全部传上。随着通道的接入，矩阵中会不断增加行
——把它当作下限而不是上限，让拒绝结果告诉你到底缺了什么。

### 哪些字段应放在 `payoutMethodProperty` 里而不是顶层？

`payoutMethodProperty` 是一个 **JSON 字符串**（最长 512 个字符），不是对象，而且它是
唯一接受银行路由信息的地方：

| 键 | 何时使用 | 说明 |
| - | - | - |
| `bankCode` | `payoutMethodType = BANK_ACCOUNT` 时必填 | 请求顶层不接受该字段 |
| `bankBranch` | 可选 | 省略时默认为空 |
| `bankCity` | 可选 | 如有提供，查询时会返回 |

收款人的账户标识本身**不在** `payoutMethodProperty` 里——它是
`payoutInfo.payoutMethodUserAccountNo`，其格式取决于
`payoutMethodType`：`BANK_ACCOUNT` 为银行账号，`EWALLET` 为
钱包自身的账号或公开用户标识。`payoutMethodName` 在 `EWALLET` 时为钱包
名称，在 `BANK_ACCOUNT` 时为**空**。

创建 / 查询 / 通知循环本身请参见 [Payout FAQ](/docs/zh/support/payout-faq)。

## Payout 的 `purpose` 可以取哪些值？

`/api/v1/payout/create` 上的 `purpose` 在**向中国大陆 Payout 时为必填**，此时
必须是下列值之一；对于其他通道它是可选的，会按你传入的原样透传给
收款方。可接受的值：

| 值 | 含义 |
| - | - |
| `SALARY_PAYMENT` | 工资 |
| `SERVICE_CHARGES` | 服务费 |
| `ADVISORY_FEES` | 顾问 / 咨询费 |
| `ADVERTISING_EXPENSES` | 广告与公关 |
| `CONSTRUCTION_EXPENSES` | 建筑费用 |
| `PROPERTY_RENTAL` | 物业租金 |
| `TAX_PAYMENT` | 缴税 |
| `LIBERALIZED_REMITTANCE` | 自由汇款 |

请选择真正符合该笔付款性质的值。某些通道——尤其是中国大陆——
会据此进行校验。

相邻的两个自由文本字段经常与它混淆。`description`（最长 128
个字符）会打印在收款人的银行或钱包账单上，所以请保持简短：银行
和钱包会截断它，实际上限大约是 16 个英文单词或 10 个中文字符。
`extendInfo`（最长 128 个字符，JSON）会原样回传给你，
不会到达收款人。

## `/api/v1/order/create` 上哪些"可选"字段对某些支付方式来说会变成必填？

收单规范把 `goodsInfo`、`addressInfo` 和 `userInfo` 的大部分字段标记为
可选，因为是否必填取决于实际使用的支付方式。
按 `payMethodType` 汇总如下：

| `payMethodType` | `userFirstName` | `userLastName` | `userPhone` | `goodsInfo` | `addressInfo` |
| - | - | - | - | - | - |
| `BNPL` | 必填 | 必填 | 必填 | 必填 | 必填 |
| `ONLINE_BANKING` | 必填 | 必填 | 视市场而定 | 视市场而定 | 非必填 |
| `EWALLET` | 非必填 | 非必填 | 视市场而定 | 非必填 | 非必填 |
| `VA` | 必填 | 必填 | 非必填 | 非必填 | 非必填 |
| `OTC` | 必填 | 必填 | 非必填 | 非必填 | 非必填 |
| `CREDITCARD`、`DEBITCARD` | 非必填 | 非必填 | 非必填 | 非必填 | 非必填 |

请把这张表当作评估工作量的信息，而不是契约：同一个 `payMethodType` 在不同
市场之间可能不同，这也是为什么有几个单元格写着*视市场而定*。`BNPL` 是唯一
在所有提供它的地方都要求完整逐项商品清单的类型。

**如果你使用 Waffo 托管的收银台，通常可以忽略这张表。** 当所选
方式需要你未提供的用户信息时，买家会被重定向到收银台，
由收银台收集。只有在流程中没有收银台时，这张表才重要。

关于权威做法——提交、读取返回的缺失字段列表、重新发送——以及
可能被要求的全部字段路径，请参见
[按支付方式划分的条件必填字段](/docs/zh/support/conditional-required-fields-faq)。

## `orderAction.actionData` 里有什么？

当 `orderStatus = AUTHORIZATION_REQUIRED`（即买家还有事情要做）时，
`/api/v1/order/create` 和 `/api/v1/order/inquiry` 会返回 `orderAction`。
`actionType` 为 `WEB`（把买家重定向到 `webUrl`）或 `DEEPLINK`（打开 `deeplinkUrl`）。

`actionData` 是重定向之外的另一种选择：它携带原始的支付凭据，让
你可以渲染自己的收银台页面。任何一次响应中**只会出现与所选支付
方式相关的子集**，所以请把每个字段都视为可选，有什么就渲染什么。

### 支付凭证字段

| 字段 | 类型 | 何时出现 | 如何处理 |
| - | - | - | - |
| `paymentExpiryTime` | String | 大多数凭证类方式 | ISO 8601（`2023-04-01T03:00:00.000Z`），过期后买家将无法再支付。显示倒计时或过期提示。 |
| `paymentQr` | String | 基于二维码的方式 | **原始二维码字符串**，不是图片。在客户端把它渲染成可扫描的二维码。 |
| `paymentCode` | String | 输码类和柜台（OTC）类方式 | 买家在其银行 / 钱包 App 中输入、或在柜台报出的数字或字母数字码。 |
| `paymentBarCode` | String | 柜台（OTC）类方式 | **原始条形码字符串**。把它渲染成一维条形码（例如 Code 128），供买家在实体扫码器前出示。 |

### 金额与汇率字段

| 字段 | 类型 | 何时出现 | 如何处理 |
| - | - | - | - |
| `paymentCurrency` | String | 当该方式以自己的币种收款时 | ISO 4217。当该方式只支持特定本地币种时，可能与 `orderCurrency` 不同。 |
| `paymentAmount` | String | 随 `paymentCurrency` 出现 | 买家实际将支付的金额，以 `paymentCurrency` 计。当它与订单金额不同时，把**这个**作为你页面上的主要金额。 |
| `userFeeAmount` | String | 当存在买家侧附加费时 | 由买家而非你承担的费用。请单独列出——不要悄悄地并进总额。 |
| `userFeeCurrency` | String | 随 `userFeeAmount` 出现 | ISO 4217。通常等于 `paymentCurrency`，但在跨境流程中可能不同。 |
| `exchangeRate` | String | 仅当 `paymentCurrency` ≠ `orderCurrency` 时 | 定义为 `paymentAmount / orderAmount`。在买家确认前予以披露。 |

### 银行转账字段

| 字段 | 类型 | 何时出现 | 如何处理 |
| - | - | - | - |
| `bankAccount` | String | 银行转账和虚拟账户方式 | 要转入的账户。视市场而定，可能是 IBAN、路由号 + 账号，或为该笔订单单独生成的虚拟账户。 |
| `bankName` | String | 随 `bankAccount` 出现 | 买家必须在其银行 App 中选择的收款银行或清算参与方。如果返回的是数字代码，请自行映射为可读名称。 |
| `bankBeneficiary` | String | 随 `bankAccount` 出现 | 买家将看到的账户持有人名称。 |
| `referenceNumber` | String | 银行转账和柜台（OTC）方式 | 对账参考号。**强烈提示买家**把它一字不差地复制到转账的*备注 / 附言 / 参考号*字段中——对账依赖于它。 |

虚拟账户（按订单生成的 `bankAccount`）仅凭账号即可对账；
共享收款账户则凭 `referenceNumber` 对账。如果两者都返回了，
两个都要展示，并把 `referenceNumber` 视为买家必须输入的内容。

## 完整错误码表——Payout

`/api/v1/payout/create`、`/api/v1/payout/inquiry` 以及 Payout 通知。

| 错误码 | 描述 | HTTP |
| - | - | - |
| `0` | 成功 | 200 |
| `A0001` | API 私钥无效 | 401 |
| `A0002` | 签名无效 | 401 |
| `A0003` | 参数校验失败 | 400 |
| `A0004` | 权限不足 | 401 |
| `A0005` | 超出商户限额 | 400 |
| `A0006` | 商户状态异常 | 400 |
| `A0007` | 不支持该 Payout 币种 | 400 |
| `A0008` | 超出 Payout 限额——金额应在范围内 | 400 |
| `A0009` | 订单不存在 | 400 |
| `A0010` | 商户合同不允许该操作 | 400 |
| `A0011` | 幂等参数不匹配 | 400 |
| `A0012` | 商户账户余额不足 | 400 |
| `A0013` | 请求过多，请稍后再试 | 400 |
| `B0001` | 用户状态异常 | 400 |
| `B0002` | 超出用户限额 | 400 |
| `B0003` | 用户不存在 | 400 |
| `B0004` | 用户信息不匹配 | 400 |
| `C0001` | 系统错误 | 500 |
| `C0002` | 商户合同无效 | 500 |
| `C0003` | 订单信息不匹配 | 500 |
| `C0004` | Payout 渠道拒绝 | 503 |
| `C0005` | Payout 渠道错误 | 503 |
| `D0001` | 风控拒绝 | 406 |
| `E0001` | 未知状态 | 500 |

注意 Payout **没有**的错误码：没有 `A0015`–`A0047`。如果你在
Payout 端点上看到其中之一，说明你看错表了。

## 完整错误码表——收单

`/api/v1/order/create`、`/inquiry`、`/cancel`、`/refund`、`/capture`、
`/api/v1/refund/inquiry` 以及支付和退款通知。

| 错误码 | 描述 | HTTP |
| - | - | - |
| `0` | 成功 | 200 |
| `A0001` | API 私钥无效 | 401 |
| `A0002` | 签名无效 | 401 |
| `A0003` | 参数校验失败 | 400 |
| `A0004` | 权限不足 | 401 |
| `A0005` | 超出商户限额 | 400 |
| `A0006` | 商户状态异常 | 400 |
| `A0007` | 不支持该交易币种 | 400 |
| `A0008` | 超出交易限额——支付金额应在范围内 | 400 |
| `A0009` | 订单不存在 | 400 |
| `A0010` | 商户合同不允许该操作 | 400 |
| `A0011` | 幂等参数不匹配 | 400 |
| `A0012` | 商户账户余额不足 | 400 |
| `A0013` | 订单无法取消——支付已成功 | 400 |
| `A0014` | 因退款规则订单无法退款 | 400 |
| `A0015` | 订单无法取消——支付方式不支持取消 | 400 |
| `A0016` | 订单无法取消——被下游拒绝 | 400 |
| `A0017` | 订单无法退款——支付方式不支持退款 | 400 |
| `A0018` | 订单中的支付方式与商户合同不匹配 | 400 |
| `A0019` | 因存在拒付争议订单无法退款 | 400 |
| `A0020` | 支付金额超出交易限额 | 400 |
| `A0021` | 累计支付金额超出每日交易限额 | 400 |
| `A0022` | 请指定产品名称——找到多个产品 | 400 |
| `A0023` | 订单无法创建——token 已过期 | 400 |
| `A0024` | 订单无法处理——汇率已过期 | 400 |
| `A0026` | 不支持指定的收银台语言 | 400 |
| `A0027` | 退款已超过最大次数 | 400 |
| `A0029` | 提供的卡数据无效 | 400 |
| `A0030` | 找不到提供的卡 BIN | 400 |
| `A0031` | 不支持提供的卡组织或卡类型 | 400 |
| `A0032` | 提供的支付 token 数据无效 | 400 |
| `A0033` | 请指定支付方式国家——找到多个支付方式 | 400 |
| `A0034` | 提供的订单过期时间已过 | 400 |
| `A0035` | 该订单不支持 capture 操作 | 400 |
| `A0036` | 当前订单状态不允许 capture | 400 |
| `A0037` | 用户支付 token 无效或已过期 | 400 |
| `A0039` | 订单已被拒付预警服务退款 | 400 |
| `A0040` | 订单不能并发创建 | 400 |
| `A0045` | MIT 无法处理——token 状态为 Unverified | 400 |
| `A0046` | 访问被拒绝——请求 IP 不在白名单中 | 400 |
| `A0047` | 收银台语言格式无效——必须遵循 IETF BCP 47（两位 ISO 639-1 语言码，可选四位 ISO 15924 文字码，可选两位 ISO 3166-1 alpha-2 地区码） | 400 |
| `B0001` | 用户状态异常 | 400 |
| `B0002` | 超出用户限额 | 400 |
| `B0003` | 用户余额不足 | 400 |
| `B0004` | 用户未在超时时间内支付 | 400 |
| `B0005` | 用户授权失败 | 400 |
| `B0006` | 电话号码无效 | 400 |
| `B0007` | 邮箱格式无效 | 400 |
| `C0001` | 系统错误 | 500 |
| `C0002` | 商户合同无效 | 500 |
| `C0003` | 订单状态无效，无法继续 | 500 |
| `C0004` | 订单信息不匹配 | 500 |
| `C0005` | 支付被下游拒绝 | 503 |
| `C0006` | 支付处理错误 | 503 |
| `C0007` | 该支付方式正在维护中 | 503 |
| `D0001` | 风控拒绝 | 406 |
| `E0001` | 未知状态 | 500 |

收单族是最宽的一族，
[快速参考](/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes)
中还包含本规范版本之外的其他收单错误码。两者不一致时，
以快速参考为较新的列表。

## 完整错误码表——订阅

`/api/v1/subscription/create`、`/inquiry`、`/cancel`、`/manage`、`/change`、
`/change/inquiry`、`/update` 以及订阅通知。

| 错误码 | 描述 | HTTP |
| - | - | - |
| `0` | 成功 | 200 |
| `A0001` | API 私钥无效 | 401 |
| `A0002` | 签名无效 | 401 |
| `A0003` | 参数校验失败 | 400 |
| `A0004` | 权限不足 | 401 |
| `A0005` | 超出商户限额 | 400 |
| `A0006` | 商户状态异常 | 400 |
| `A0007` | 不支持该交易币种 | 400 |
| `A0009` | 订单不存在 | 400 |
| `A0010` | 商户合同不允许该操作 | 400 |
| `A0011` | 幂等参数不匹配 | 400 |
| `A0014` | 因退款规则订单无法退款 | 400 |
| `A0015` | 订单无法取消——支付方式不支持取消 | 400 |
| `A0016` | 订单无法取消——被下游拒绝 | 400 |
| `A0018` | 该用户没有可用的支付方式来继续支付 | 400 |
| `A0022` | 请指定产品名称——找到多个产品 | 400 |
| `A0025` | 周期数必须大于一 | 400 |
| `A0028` | 订阅仍在进行中或已失败，管理 URL 不可用 | 400 |
| `B0001` | 用户状态异常 | 400 |
| `B0002` | 超出用户限额 | 400 |
| `B0003` | 用户余额不足 | 400 |
| `B0004` | 用户未在超时时间内支付 | 400 |
| `B0005` | 用户授权失败 | 400 |
| `B0006` | 电话号码无效 | 400 |
| `B0007` | 邮箱格式无效 | 400 |
| `C0001` | 系统错误 | 500 |
| `C0002` | 商户合同无效 | 500 |
| `C0003` | 订单状态无效，无法继续 | 500 |
| `C0004` | 订单信息不匹配 | 500 |
| `C0005` | 支付被下游拒绝 | 503 |
| `C0006` | 支付处理错误 | 503 |
| `C0007` | 该支付方式正在维护中 | 503 |
| `D0001` | 风控拒绝 | 406 |
| `E0001` | 未知状态 | 500 |

有两个错误码是这一族独有的，值得单独处理：`A0025`（订阅
必须运行超过一个周期）和 `A0028`（在首期付款完成结算之前请求管理
URL）。

## 完整错误码表——提现、余额与交易限额规则

`/api/v1/account/balance/inquiry`、`/api/v1/account/history/inquiry`、
`/api/v1/withdraw/consult`、`/create`、`/inquiry`、提现通知，以及
`/api/v1/risk/transactionlimit/create`、`/update`、`/inquiry`。

| 错误码 | 描述 | HTTP |
| - | - | - |
| `0` | 成功 | 200 |
| `A0001` | API 私钥无效 | 401 |
| `A0002` | 签名无效 | 401 |
| `A0003` | 参数校验失败 | 400 |
| `A0004` | 权限不足 | 401 |
| `A0005` | 超出商户限额 | 400 |
| `A0006` | 商户状态异常 | 400 |
| `A0007` | 不支持该提现币种 | 400 |
| `A0008` | 超出提现限额——金额应在范围内 | 400 |
| `A0009` | 订单不存在 | 400 |
| `A0010` | 商户合同不允许该操作 | 400 |
| `A0011` | 幂等参数不匹配 | 400 |
| `A0012` | 商户账户余额不足 | 400 |
| `A0013` | 请求过多，请稍后再试 | 400 |
| `A0100` | 同一个 `goodsId` 已被另一个规则 ID 配置 | 400 |
| `A0101` | 同一个 `goodsCategory` 已被另一个规则 ID 配置 | 400 |
| `A0102` | 规则不存在 | 400 |
| `C0001` | 系统错误 | 500 |
| `C0002` | 商户合同无效 | 500 |
| `C0003` | 订单信息不匹配 | 500 |
| `C0004` | 提现被下游拒绝 | 503 |
| `C0005` | 提现处理错误 | 503 |
| `D0001` | 风控拒绝 | 406 |
| `E0001` | 未知状态 | 500 |

`A0100`–`A0102` **只**存在于这里，并且只出现在交易限额规则
端点上。它们不在通用快速参考中，所以 `A0100` 不是
写错了的 `A0010`。

## 我收到了一个不在上述任何表格里的错误码，它是什么？

Waffo 在签名公共 API 上返回的每个错误码都符合以下形式之一：`0`，或
单个字母 `A`–`E` 后跟四位数字。任何其他形式的值——更长的
字符串、不同的前缀、混合的字母数字标识——都**不属于公共
错误契约**，你的集成不应基于它做分支判断。把它连同
`paymentRequestId` / `payoutRequestId` 一起记录下来，并
[联系支持](mailto:support@waffo.com)；在通过查询调用获得确定状态之前，
按 `E0001` 的方式处理该笔交易。

对于形式符合公共规范、但就是不在你所调用 API 族表格里的错误码也一样：
查询订单以获得其真实状态，而不是从错误码推断结果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.