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

# Payout FAQ

> 解答关于 Waffo Payout 最常见的问题：创建并跟踪一笔 Payout、通知、各国收款人字段要求、幂等性以及错误码。

本页解答商户关于 Waffo Payout 最常问的问题。
字段级契约见
[Payout API 规范](/docs/api-reference/introduction)。

## 怎么创建一笔 Payout 并跟踪到完成？

三个集成点，全部必需：

1. **创建**——调用 `/api/v1/payout/create`，传入唯一的 `payoutRequestId`、
   Payout 金额和币种、收款 `country` 以及收款人信息。部分通道还要求
   汇款 `purpose`——向中国大陆的 Payout 必须从固定列表中选择一个。响应
   返回 Waffo 的 `payoutOrderId` 和初始 `status`。
2. **查询**——调用 `/api/v1/payout/inquiry`，传入 `payoutRequestId`
   或 `payoutOrderId`，可随时获取完整的 Payout 对象。
3. **监听**——在您提供的 `notifyUrl` 上接收 **Payout 通知**回调，
   在 Payout 完成或失败时推送。

## Payout 有哪些状态？

| 状态 | 含义 |
| - | - |
| `IN_PROGRESS` | Payout 正在处理中。 |
| `SUCCESS` | Payout 成功。 |
| `FAILURE` | Payout 失败——请查看 `failureCode` 和 `failureReason`。 |

`subStatus` 字段仅在成功后发生冲正时出现
（`status` 保持 `SUCCESS`）：`FULL_REVERSED` 表示全额被冲正；
`PARTIAL_REVERSED` 表示仅部分被冲正。大多数订单永远不会带
`subStatus`。

## 幂等性是怎么工作的？重试创建请求会怎样？

`payoutRequestId` 是您的幂等键。用**相同**的 `payoutRequestId` 重试
`/api/v1/payout/create`：

* 且金额、币种和收款账户**相同**时，返回**普通成功码**，
  携带*原*订单的数据——包括其当前状态，以及如果已失败则包含
  原始失败码。不会创建第二笔 Payout。请通过比较返回的 `payoutOrderId`
  与您已持有的那个来识别这种情况；没有单独的幂等码。
* 但金额、币种或收款账户**不同**时，返回 `A0011`
  （幂等参数不匹配），请求被拒绝。注意比较只覆盖这三个字段——
  如果您编辑了收款人后重发，这意味着什么，请参见
  [Payout 请求字段指南](/docs/zh/support/payout-request-field-guide)。

如果您收到 `Exxxxx` 未知错误，说明最终结果尚未确定——
请持续重试查询，直到收到最终的 `SUCCESS`
或 `FAILURE` 状态。不要把未知结果当作失败处理。

## 哪些收款人姓名字段是必填的？

`payeeFirstName`、`payeeMiddleName` 和 `payeeLastName` 是**条件必填**：
是否必填取决于收款国家和 Payout 方式。
`payeeIDType` 同理：目前 `CHN` 是有强制要求的国家
（必须提供身份证或护照，且银行 Payout 还有额外的本地规则）。
其他国家由通道校验而非国家专属规则，因此请按照您所用
通道的字段要求表填写。对于印度尼西亚（`IDN`），`IDN_BANK` 银行 Payout
和 `DANA` 电子钱包 Payout 都不要求姓名字段，但
银行 Payout 要求在 `payoutMethodProperty` 中提供 `bankCode`。

请在
[Payout API 规范](/docs/api-reference/introduction)
的 Payout 创建字段要求表中查看您所用国家和方式的要求；您可用的方式取决于
您合同中的配置。

## Payout 通知是怎么工作的？

当 Payout 完成或失败时，Waffo 向您的
`notifyUrl` 发送一个 HTTPS POST，其中 `eventType` 为 `PAYOUT_NOTIFICATION`。`result`
对象与 `/api/v1/payout/inquiry` 响应结构相同。

处理完成后请返回 `message` 为 `success`。如果 Waffo 收到
`failed` 或 `unknown`，Waffo 会按固定退避计划重试通知；重试次数和间隔见[Webhook 通知重试](/docs/zh/developer-docs/webhook/retry)。
在信任报文之前，请用 Waffo 的公钥验证 `X-SIGNATURE` 请求头
（签名算法：`SHA256WithRSA`）。

## 常见错误码是什么意思？

错误码按前缀分组：`A` 商户相关，`B` 用户相关，
`C` 系统相关，`D` 风控拒绝，`E` 未知（重试直到最终结果）。

| 错误码 | 含义 | 应对 |
| - | - | - |
| `A0007` | 不支持该 Payout 币种 | 使用您合同配置中覆盖的币种。 |
| `A0012` | 商户账户余额不足 | 为账户充值后重新提交。 |
| `A0008` | 超出 Payout 限额 | 将金额控制在您账户允许的范围内。 |
| `A0013` | 请求过多 | 退避后稍后重试。 |
| `A0011` | 幂等参数不匹配 | 同一个 `payoutRequestId` 被复用，但金额、币种或收款账户不同。 |
| `E0001` | 未知状态 | 重试查询直到得到最终的 `SUCCESS` / `FAILURE`。 |

Payout 错误码集**不同于**支付的错误码集——若干错误码
含义不同，且 Payout 没有 `A0014`。完整表格，
以及哪四个错误码可以安全重试，见
[Payout 错误码与重试](/docs/zh/support/payout-error-codes-and-retry-faq)。

## 从我余额里扣的是什么金额？

查询响应把金额分开返回：`payoutAmount`（您要求付出的金额）、
`prefundAmount`（从您账户扣除的金额，**含手续费**）和
`payeeAmount`（收款人收到的金额——跨币种
Payout 的确切到账金额可能无法得知）。如果 Payout 失败，剩余金额
会退回给您；手续费视情况仍可能被收取，
体现在 `feeStatus`（`DEDUCTED`、
`RETURNED` 或 `NONE`）中。


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