> ## 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 状态、通知与报表

> 每个 Payout 状态和子状态的含义、为什么 DEDUCTED 永远不会到达你、Payout Webhook 何时触发以及完全不触发的两种情况、如何发现冲正，以及每日、每周和每月 Payout 报表包含什么、何时出现。

本页介绍创建 Payout 之后如何读取它：它的状态、如何得知它已完成，以及周期性报表在哪里。创建 Payout 见 [Payout FAQ](/docs/zh/support/payout-faq)；请求字段见 [Payout 请求字段指南](/docs/zh/support/payout-request-field-guide)；批量 Payout 在[批量 Payout 状态与资金](/docs/zh/support/batch-payout-faq)中有自己的状态。

## 创建 Payout 是同步还是异步的？

在所有实际情况下都是异步的。创建成功返回一个 `status: IN_PROGRESS` 的订单和 Waffo 的 `payoutOrderId`；结果稍后到达。得知结果恰好有三种方式，你应该至少基于其中两种来构建：

| 途径 | 用途 |
| - | - |
| **`/api/v1/payout/inquiry`** | 任何时候按 `payoutRequestId` 或 `payoutOrderId` 获取权威的当前状态 |
| **Payout Webhook** | 无需轮询即可及时获知——见下文的限制 |
| **Portal** | 手工排查单个订单 |

创建也可能直接返回终态：对一个原始订单已完成的 `payoutRequestId` 做完全相同的重发，会立即返回该终态；在预检步骤失败的 Payout 会同步失败。把创建响应上的 `SUCCESS` 和 `FAILURE` 当作真实结果。

## Payout 有哪些状态，哪些是终态？

| `status` | 含义 | 是否终态 |
| - | - | - |
| `IN_PROGRESS` | 处理中 | 否 |
| `SUCCESS` | Payout 成功 | 是 |
| `FAILURE` | Payout 失败——读取 `failureCode` 和 `failureReason` | 是 |

三个值，只有两个是终态。API 中没有单独的"已提交"、"已扣款"或"记账中"值。

## Portal 显示的状态和 API 不一样，哪个是对的？

它们是一致的——Portal 的 Payout 列表和详情渲染的是 API 返回的**同样三个值**，列表上的筛选也提供同样三个。Payout 流转过程中 Waffo 跟踪更细的内部阶段，而每一个都向你报告为 `IN_PROGRESS`；两个界面都不暴露它们。如果两者确实不同，那么其中一个是过期的——重新查询，并以查询响应为权威。

## 我在某处看到了 `DEDUCTED`，钱已经出去了吗？

`DEDUCTED` 是内部阶段名称，不是你能收到的 Payout 状态：它是 `IN_PROGRESS` 内部的一个位置。它意味着资金已从你的结算账户扣出并转入 Payout Wallet——**不是**收款人已收到款。从那时起直到 Payout 到达终态，资金在钱包中处于 *In Transit*，这就是为什么一笔 Payout 可以在你的余额上显示为已扣款、之后仍然失败并退回金额。该机制见 [Payout Wallet 与覆盖范围](/docs/zh/support/payout-wallet-and-coverage-faq)。

## `subStatus` 是什么？`CONSULT_SUCCESS` 和 `CONSULT_FAILURE` 呢？

`subStatus` **仅在**发生冲正时存在，且只会携带两个值之一：

| `subStatus` | 含义 |
| - | - |
| `FULL_REVERSED` | 整个 Payout 金额被冲正 |
| `PARTIAL_REVERSED` | Payout 金额的一部分被冲正 |

`CONSULT_SUCCESS` 和 `CONSULT_FAILURE` 是预检步骤的内部标记，**在构建响应之前就被过滤掉**——API 只对两个冲正值返回 `subStatus`，所以你永远不会收到它们中的任何一个。如果你见过它们，它们来自 Payout API 之外的地方，且不携带任何你需要处理的含义。

## Payout 成功了，还会被冲正吗？

会。接收方可以在 Payout 已到达 `SUCCESS` 之后退回它。发生时：

* `status` **保持** `SUCCESS`。它不会变成失败或冲正状态。
* `subStatus` 变为 `FULL_REVERSED` 或 `PARTIAL_REVERSED`。
* 冲正金额贷记回为该 Payout 出资的账户——你的结算账户，以出资币种计。部分冲正只退回被冲正的部分，因此请对照冲正金额而不是原 Payout 金额对账。

\*\*冲正不会发送 Webhook。\*\*Payout 被冲正时不会推送任何类型的通知。发现它的唯一方法是重新查询订单，或查看 Payout Wallet 账户历史，冲正会在那里记入自己的一对行。如果冲正对你的账本重要，请定期重新查询成功的 Payout，而不是把 `SUCCESS` 当作订单的终点。

## 手续费字段怎么读？

| 字段 | 含义 |
| - | - |
| `feeCurrency` | 收取手续费的币种 |
| `actFeeAmount` | 订单终态后实际收取的手续费 |
| `feeStatus` | `DEDUCTED`、`RETURNED` 或 `NONE` |

`actFeeAmount` 和 `feeStatus` 一起变动：

| `feeStatus` | `actFeeAmount` | 何时 |
| - | - | - |
| `DEDUCTED` | 手续费金额 | 已收取并保留 |
| `RETURNED` | `0` | 已收取并退回 |
| `NONE` | `0` | 没有手续费 |

成功的 Payout 以 `DEDUCTED` 或 `NONE` 结束。失败的 Payout 可以是三者中的任何一个：如果订单从未到达接收方，手续费全额退回；否则只有当你对该方式的协议在 Service → Payout 页面上标记为 **Fee Refundable = Yes** 时才退回。所以 `feeStatus` 才是用来对账的字段，而不是"失败就免费"的假设。

## Payout 手续费是从金额中扣除，还是另外收取？

另外收取。`payoutAmount` 是你要求付给收款人的金额；从你的结算账户流出的是 `prefundAmount`，即换算后的 Payout 金额**加上**该订单的手续费。收款人不用自己的款项承担手续费。

## 用的是什么汇率，何时锁定？

Payout 响应不携带汇率。它携带的是两侧的金额——你请求币种的 `payoutAmount`、你被扣款币种的 `prefundAmount`，以及收款人收到币种的 `payeeAmount`——API 和 Portal 的 Payout 详情都不暴露汇率字段。请从金额对账。

对于跨币种 Payout，`payeeAmount` 在早期查询时可以合理地为空并在之后填充，因为创建订单时并不总是知道确切的收到金额。不要用创建响应中的数字向收款人报价。

## Payout Webhook 存在吗？事件叫什么？

存在：`PAYOUT_NOTIFICATION`。它投递到该订单上的 `notifyUrl`——该 URL 按请求提供，对 API Payout 是必填的，没有账户级回退。body 遵循与其他所有 Waffo Webhook 相同的信封，`result` 的结构与 `/api/v1/payout/inquiry` 响应完全一致，并在 `X-SIGNATURE` 请求头中签名。验签、响应格式和重试行为与其他事件相同——见[签名验证](/docs/zh/developer-docs/webhook/signature-verification)和 [Webhook 重试](/docs/zh/developer-docs/webhook/retry)。提现有自己独立的事件 `WITHDRAW_NOTIFICATION`；Payout Webhook 永远不会是提现 Webhook，反之亦然。

## 它何时触发？有中间通知吗？

一次，在最后，中间绝不触发：

* 当 Payout 到达 `SUCCESS` 或 `FAILURE` **且**其手续费记账已完成时推送——这就是为什么报文中 `feeStatus` 和 `actFeeAmount` 已经有值。
* `IN_PROGRESS` **没有**通知，任何内部阶段也没有。
* 冲正**没有**通知。

## 为什么我的批量 Payout 收不到 Webhook？

因为 Payout Webhook **只对通过 API 创建的 Payout** 推送。源自 Portal 批量上传中某一行的 Payout 无论如何结束都不会产生 Webhook。请从批次记录及其结果文件跟踪批量结果——见[批量 Payout 状态与资金](/docs/zh/support/batch-payout-faq)——或对每一行的 `payoutOrderId` 调用 `/api/v1/payout/inquiry`。

## 如果我漏掉了 Webhook或返回了非 200 怎么办？

Waffo 在收到 `failed` 或 `unknown` body 或投递失败时按固定退避计划重试；尝试次数和间隔见 [Webhook 重试](/docs/zh/developer-docs/webhook/retry)。存储事件后请响应 `{"message":"success"}`。

由于 Payout Webhook 只在最后触发一次，一个你从未处理的 Webhook 就是一个你永远不会听到的结果。不要只靠 Webhook 运营 Payout——对任何没有终态的订单用 `/api/v1/payout/inquiry` 对账。

## 一笔 Payout 长时间处于 `IN_PROGRESS`，什么时候该担心？

没有公布的时长阈值来判定处理中的 Payout 异常，答案也因通道而异，所以把时长本身视为不提供信息。取而代之该做的：

| 检查 | 原因 |
| - | - |
| 重新查询订单 | 状态可能已经变化，只是 Webhook 丢了 |
| `payoutUpdatedAt` | 告诉你订单上次变化的时间，比它有多久更有信息量 |
| `payoutArrivalTime` | 仅在 Payout 完成时填充——为空表示尚未完成 |
| Portal 详情上的状态时间线 | 显示已到达哪些阶段 |

**不要**创建第二笔 Payout 来强制推进。仍在进行中的 Payout 可以完成，而第二个订单就是第二笔付款。请用 `payoutOrderId` 向 Waffo 提出停滞的 Payout，而不是重发。

## Payout 失败了，我是重发原来的还是新建一个？

新建一个，使用**新的 `payoutRequestId`**。重发相同的 `payoutRequestId` 会返回原订单及其原始失败码——它不会重新尝试 Payout。先读取 `failureCode` 并修复它指出的问题；哪些码值得重发见 [Payout 错误码与重试](/docs/zh/support/payout-error-codes-and-retry-faq)。

## Payout 记录上的 `payOption` 和 `channelId` 是什么意思？

`payOption` 是为该 Payout 解析出的具体接收选项——例如银行代码背后的标签。它在 Portal 的 Payout 详情上显示为 **Payment Option**，当你需要确认一笔 Payout 通过多条路线中的哪一条到达银行时很有用。

`channelId` 不是面向商户的字段：它不在 Portal 的 Payout 详情上，也不在 Payout 查询响应中。如果你从某处拿到了它，它不是你需要对账的东西。

## 我能拿到哪些周期性 Payout 报表？

三种，都在 Portal 的 **Payout → Payout Report** 下：

| 报表 | 覆盖周期 |
| - | - |
| **Daily** | 一个自然日 |
| **Weekly** | 周一至周日 |
| **Monthly** | 当月 1 日至最后一天 |

列表按报表显示 **Period**、覆盖的 **Order Count**、**Generated Time**（UTC+8）和 **File Name**（即下载链接）。可按日期范围筛选并选择报表类型。文件为 CSV。

## 我今天能拿到今天的报表吗？

对于**每日**报表，可以——它是唯一可能在其覆盖当天生成的报表，只要当天的 Payout 结算全部完成。每周和每月报表只在其周期**结束**后生成——周中不存在周报。任何情况下报表都需要**同时**满足两个条件：

1. 其周期已结束（每日：当天本身算）。
2. 该周期内的每笔 Payout 结算都已**完成结算**。周期已结束但仍有未结算 Payout 活动的会被跳过并稍后重试。

这就是为什么一个周期可能已结束而报表尚未出现，以及为什么列表只显示成功生成的报表——没有待处理或失败的行需要解读。完全没有 Payout 活动的周期不会生成报表，而不是生成一份空报表。

## Payout 报表能定时推送到 SFTP 或通过邮件发送吗？

\*\*SFTP——可以，需另行安排。\*\*Waffo 可以按日周期把你账户的定时 Payout 账单文件投递到 SFTP 位置。它由 Waffo 按商户账户设置，不是在 Portal 中开启：请联系支持，说明账户和你需要的 SFTP 详情。\*\*邮件——不行。\*\*没有 Payout 报表的邮件订阅。与两者无关，Payout 报表始终可在 Portal 下载：打开 Payout → Payout Report 并点击文件名，会给你一个限时下载链接。结算报表投递是独立功能，有自己的 SFTP 和邮件选项——见[报表投递与邮件订阅](/docs/zh/support/report-delivery-and-subscription-faq)——所以不要假设结算订阅涵盖 Payout。

## 报表下载链接失效了，怎么拿新的？

再次点击文件名。链接每次都是新生成的，并且刻意设为短期有效，所以它是用来立即使用的，而不是存储、转发或嵌入到任务里。过期的链接不是错误状态——什么都没丢。

下载需要你的 Portal 用户具有报表下载权限。没有该权限时你能看到报表行及其文件名，但名称是纯文本而不是链接；请找你的账户管理员。

## 我能导出 Payout 列表吗？是同步的吗？

能，而且是**异步**的。单笔 Payout 列表和批次列表都以任务形式导出：你启动它，文件出现在 Portal 的导出区域，而不是在浏览器中下载。状态、重试和链接过期的机制与其他所有导出相同——见[导出与报表下载](/docs/zh/support/export-center-faq)。

两个需要提前规划的限制：

| 限制 | 值 |
| - | - |
| 导出日期范围 | 最多一个月——更宽的选择在创建任务之前就被拒绝 |
| 查询日期范围 | Payout 列表查询同样限制在一个月窗口内 |

非常大的导出会拆分为多个文件而不是截断，所以在断定数据缺失之前先检查是否有多个文件。

## 我应该从报表对账还是从 API 对账？

用与你要对账的粒度匹配的那个，并预期它们描述的是不同的东西：

| 来源 | 粒度 | 最适合 |
| - | - | - |
| `/api/v1/payout/inquiry` | 单个订单，当前状态 | 按订单的事实，包括冲正 |
| Payout 列表导出 | 日期范围内的订单 | 你自己的订单级账本 |
| Payout Report | 一个已结算周期 | 把 Payout 与实际清算的金额挂钩 |

当两边不一致时，通常能解释的字段是 `prefundAmount` 与 `payoutAmount`（前者包含手续费且以出资币种计）、`actFeeAmount` 与 `feeStatus`（失败的 Payout 可能退回也可能不退回手续费），以及 `subStatus`（冲正改变资金但不改变 `status`）。在提出差异之前先检查这三项。

## Waffo 能给收款人提供发票或付款收据吗？

Payout 不会生成面向收款人的收据或发票。收款人看到的是你发送的 `description`，出现在他们的银行或钱包账单上。在你这边，Payout 的凭证是订单记录、Payout 列表导出和 Payout Report。如果你需要给收款人一份文件，请从订单数据生成——`payoutOrderId`、`payeeAmount`、`payeeCurrency`、`payoutArrivalTime` 和 `description` 是标识该笔付款的字段。

***

状态或报表与你的预期不符？请[联系支持](mailto:support@waffo.com)，附上 `payoutOrderId`，或报表周期和类型。


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