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

# 结算文件规范

> 三份对账报表文件以及结算账单和发票 PDF 的逐列参考：每个字段的含义、小数精度、何时为空、文件命名规则、文件投递位置，以及如何按日期范围批量下载。

[结算报表与导出](/docs/zh/support/settlement-reports-faq)解释了金额如何计算以及如何按需拉取报表。
[报表投递与邮件订阅](/docs/zh/support/report-delivery-and-subscription-faq)说明文件如何按计划送达你。
**本页是字段级的契约**：每一列是什么意思、带几位小数、什么情况下为空是正常的，以及每个文件如何命名。

## 我会收到哪些报表文件，每份分别什么时候生成？

| 报表 | 覆盖范围 | 生成时间 |
| - | - | - |
| **Transaction Details** | 交易日 T 当天的全部交易，与是否结算无关 | T+1 |
| **Settlement Details** | 一个结算周期内每笔交易一行 | 收到结算银行回单的次日 |
| **Settlement Summary** | 一个结算周期内、一种结算币种下按交易类型汇总 | 收到结算银行回单的次日 |

三份文件均为 **CSV，UTF-8 编码**。两份结算报表以结算批次为键；交易报表以交易日为键，与你的结算周期无关。

这一区分带来两种行为，也是大多数「我的文件不见了」工单的原因：

* **没有交易的日子仍会生成 Transaction Details 文件**——只含表头行。
* **没有净结算的结算日不会生成任何结算文件**，因为不存在结算批次。如果你需要在每个计划日期都收到占位文件，那是按商户的配置——见
  [结算报表与导出](/docs/zh/support/settlement-reports-faq)。

## 文件名具体是什么？

| 文件 | 名称 |
| - | - |
| Transaction Details | `transaction_details_{merchant id}_{transaction date}.csv` |
| Settlement Details | `settlement_details_{merchant id}_{settlement batch id}_{settlement date}_{settlement currency}.csv` |
| Settlement Summary | `settlement_summary_{merchant id}_{settlement batch id}_{settlement date}_{settlement currency}.csv` |
| 结算账单（PDF） | `settlement_statement_{merchant id}_{currency}_{date}.pdf` |
| 提现账单（PDF） | `{merchant id}-{withdraw order id}_{account type}.pdf`——账单重新生成时会追加时间戳；随时可在**提现历史**中再次下载 |
| 发票（PDF） | `invoice_{currency}_{date1}_{date2}.pdf` |

* `transaction date` 和 `settlement date` 为 **UTC+8** 的 `YYYYMMDD`；PDF 日期为 `YYYYMMDD`。
* `settlement currency` 出现在结算文件名中，正是因为批次按结算币种打包。如果同一个结算日有两种结算币种，你会收到**两套文件**，通过最后这一段区分。
* 需要重新生成的文件**不会被覆盖**：它会以新的版本后缀再写一份（`..._v1.0_1.csv` 之后是 `..._v2.0_1.csv`），所以你已经取走的下载内容永远不会在你不知情时改变。

## 文件投递到哪里，会保留多久？

文件可在商户 Portal 获取；如果你使用 SFTP 投递，则位于文档中说明的交易和结算目录下——具体路径见
[对账报表](/docs/zh/developer-docs/tools-and-references/references/reconciliation-reports)。

\*\*对账报表在 SFTP 服务器上仅保留有限时间。它们在商户 Portal 上始终可以下载。\*\*如果你的拉取任务离线了一段时间，请从 Portal 而不是 SFTP 补齐缺口。

SFTP 访问支持两种登录方式：**用户名加密码**或**密钥认证**。推荐使用密钥认证。

## Transaction Details 各字段是什么意思？

| 列 | 含义 | 格式 / 精度 | 何时为空 |
| - | - | - | - |
| `Merchant Id` | Waffo 分配给你的标识 | 字符串，最长 64 | 永不为空 |
| `Sub Merchant Id` | Waffo 分配给直接提供商品或服务的二级商户的标识 | 字符串，最长 64 | 你未使用子商户时 |
| `Order Id` | Waffo 对该交易的标识——按 `Transaction Type` 分别为支付 id、退款 id 或拒付 id | 字符串，最长 32 | 永不为空 |
| `Merchant Order Id` | 你自己对该交易的标识 | 字符串，最长 32 | 你未传时 |
| `Payment Request Id` | 你自己对支付请求的标识 | 字符串，最长 32 | 你未传时 |
| `Original Order Id` | 原支付交易 id | 字符串，最长 32 | **`Transaction Type` 为 `PAYMENT` 时始终为空**；`REFUND` 和 `CHARGEBACK` 时有值 |
| `Order Amount` | 以订单币种计的交易金额 | 订单币种的小数位 | 永不为空 |
| `Order Currency` | `Order Amount` 的币种 | ISO 4217 三字母代码 | 永不为空 |
| `Transaction Type` | `PAYMENT`、`REFUND` 或 `CHARGEBACK` | 枚举 | 永不为空 |
| `Payment Method` | 使用的支付方式 | 字符串，最长 32；取值与 API 一致 | 永不为空 |
| `Payment Option` | 支付方式下的子方式——例如用钱包余额而非绑定卡支付 | 字符串，最长 32 | 该支付方式没有子方式时 |
| `Payment Request Datetime` | Waffo 收到你的支付请求的时间 | `YYYY-MM-DD hh:mm:ss`，UTC+8 | 永不为空 |
| `Payment Date` | 交易成功的日期 | `YYYY-MM-DD`，UTC+8 | 永不为空 |
| `Payment Time` | 交易成功的当日时间 | `hh:mm:ss`，UTC+8 | 永不为空 |
| `Order Description` | 你对该交易的描述 | 字符串，最长 128 | 你未传时 |
| `Product Name` | 签约的支付产品，如 `ONE_TIME_PAYMENT` | 枚举 | 永不为空 |
| `Merchant User Id` | 你自己对终端用户的标识 | 字符串，最长 64 | 你未传时 |

`Payment Date` 和 `Payment Time` 有意拆成两列：日期列决定一笔交易属于哪个交易日——从而属于哪次结算——因此可以直接作为分组键使用，无需解析时间戳。

## Settlement Details 各字段是什么意思？

行粒度与 Transaction Details 相同，另加每笔交易的结算结果。

| 列 | 含义 | 格式 / 精度 | 何时为空 |
| - | - | - | - |
| `Merchant Id` | 你的商户标识 | 字符串，最长 64 | 永不为空 |
| `Sub Merchant Id` | 子商户标识 | 字符串，最长 64 | 你未使用子商户时 |
| `Settlement Batch Id` | Waffo 对该周期内本次结算的标识 | 字符串，最长 64 | 永不为空（全零值标记占位文件——见下文） |
| `Settlement Date` | 结算文件生成的日期 | `YYYY-MM-DD`，UTC+8 | 永不为空 |
| `Order Id` | 按 `Transaction Type` 分别为支付、退款或拒付 id | 字符串，最长 32 | 永不为空 |
| `Merchant Order Id` | 你自己的交易标识 | 字符串，最长 32 | 你未传时 |
| `Payment Request Id` | 你自己的支付请求标识 | 字符串，最长 32 | **`Transaction Type` 为 `CHARGEBACK` 时始终为空**，以及你未传时 |
| `Original Order Id` | 原支付交易 id | 字符串，最长 32 | **`PAYMENT` 时始终为空**；`REFUND` 和 `CHARGEBACK` 时有值 |
| `Order Amount` | 以订单币种计的交易金额 | 订单币种的小数位 | 永不为空 |
| `Order Amount (Settlement Currency)` | 同一金额折算为结算币种 | 你的结算小数位——2 或 6，补零 | 永不为空 |
| `Order Currency` | `Order Amount` 的币种 | ISO 4217 | 永不为空 |
| `Transaction Type` | `PAYMENT`、`REFUND`、`CHARGEBACK` 或 `CHARGEBACK_ALERT` | 枚举 | 永不为空 |
| `Event Type` | `PAY_SUCCESS`，或失败尝试行上被计费的失败阶段——见[失败卡交易计费](/docs/zh/support/failed-transaction-billing-faq) | 枚举 | 永不为空 |
| `Payment Method Type` | 支付方式的类别 | 字符串，最长 32 | 永不为空 |
| `Payment Method` | 使用的支付方式 | 字符串，最长 32 | 永不为空 |
| `Payment Option` | 支付方式下的子方式 | 字符串，最长 32 | 该支付方式没有子方式时 |
| `Payment Request Datetime` | Waffo 收到你的支付请求的时间 | `YYYY-MM-DD hh:mm:ss`，UTC+8 | 永不为空 |
| `Payment Date` | 交易成功的日期 | `YYYY-MM-DD`，UTC+8 | 永不为空 |
| `Payment Time` | 交易成功的时间 | `hh:mm:ss`，UTC+8 | 永不为空 |
| `Product Name` | 签约的支付产品 | 枚举 | 永不为空 |
| `Forex Currency Pair` | 本行换汇步骤使用的货币对，形如 `AAA/BBB` | ISO 4217 代码，斜杠分隔 | 未涉及换汇时——见下方优先级表 |
| `Forex Rate` | `Forex Currency Pair` 对应的汇率，由外汇合作方提供 | 8 位小数，补零 | `Forex Currency Pair` 为空时 |
| `Fee Amount` | Waffo 的处理费，以费用币种计 | 6 位小数，补零 | 永不为空 |
| `Fee Amount (Settlement Currency)` | 同一费用折算为结算币种 | 结算小数位，补零 | 永不为空 |
| `Fee Currency` | `Fee Amount` 的币种 | ISO 4217 | 永不为空 |
| `Tax Amount` | 本笔交易的交易税（VAT 和/或预提税），以税费币种计 | 6 位小数，补零 | 你不适用任何交易税时 |
| `Tax Amount (Settlement Currency)` | 同一税额折算为结算币种 | 结算小数位 | 不适用交易税时 |
| `Tax Currency` | `Tax Amount` 的币种 | ISO 4217 | 不适用交易税时 |
| `Settlement Amount` | 本行的净结算额 | 结算小数位，补零；**`REFUND` 和 `CHARGEBACK` 为负数** | 永不为空 |
| `Settlement Currency` | `Settlement Amount` 的币种 | ISO 4217 | 永不为空 |
| `Comments` | 属于退款备用金结算的行上的标记 | 字符串 | 普通结算时 |

无论是哪种税，税费都以单一的 `Tax Amount` 列报告；没有单独的 VAT 或预提税列——见[费用与税费处理](/docs/zh/support/fee-and-tax-treatment-faq)。

## Settlement Summary 各字段是什么意思？

针对单一结算币种，每种交易类型一行，另加一行 `TOTAL`。

| 列 | 含义 | 格式 / 精度 | 何时为空 |
| - | - | - | - |
| `Merchant Id` | 你的商户标识 | 字符串，最长 64 | 永不为空 |
| `Settlement Batch Id` | 本次结算的标识 | 字符串，最长 64 | 永不为空 |
| `Settlement Date` | 文件生成的日期 | `YYYY-MM-DD`，UTC+8 | 永不为空 |
| `Transaction Type` | `TOTAL`（全部交易）、`PAYMENT`、`REFUND`、`CHARGEBACK`、`CHARGEBACK_ALERT` | 枚举 | 永不为空 |
| `Transaction Count` | 该类型的交易笔数 | 整数 | 永不为空 |
| `Fee Amount (Settlement Currency)` | 该类型的处理费，以结算币种计 | 结算小数位 | 该类型没有费用时 |
| `Tax Amount (Settlement Currency)` | 该类型的交易税，以结算币种计 | 结算小数位 | 不适用交易税时 |
| `Settlement Amount` | 该类型的净结算合计 | 结算小数位；`REFUND` 和 `CHARGEBACK` 为负数 | 永不为空 |
| `Settlement Currency` | 各金额的币种 | ISO 4217 | 永不为空 |
| `Comments` | 退款备用金结算的标记 | 字符串 | 普通结算时 |

\*\*汇总表中没有 `Order Amount` 列。\*\*每一个金额列都已经以结算币种表示，这正是各行可以相加的原因——不同订单币种、费用币种和税费币种的金额从不以原币种求和。

## 币种只有两位小数，为什么我的文件显示六位？

因为结算精度是按商户的配置。你的账户被设为 **2 位或 6 位小数**之一，配置后固定不变。在 6 位小数的账户上，结算币种金额以六位小数书写并**补零**到该宽度，
所以整数会显示为 `99.000000`。以*原*订单币种计的 `Order Amount` 保留该币种自身的小数位，不补零。

固定宽度，数值较短时一律补零：

| 数值 | 小数位 |
| - | - |
| 汇率 | 8 |
| 费用和税费金额 | 6 |
| 结算币种金额 | 你的结算小数位（2 或 6） |

在 6 位小数的账户上，正是这一点让明细行与批次精确对上：明细 `Settlement Amount` 之和等于批次金额，没有尾差。

## Forex Currency Pair 什么时候有值，是哪个货币对？

费用和税费可能以既非订单币种也非结算币种的币种计费，所以货币对按优先级解析——**第一个匹配的条件生效**：

| 判定顺序 | 条件 | 货币对 |
| - | - | - |
| 1 | Settlement Currency ≠ Order Currency | `Settlement/Order` |
| 2 | Settlement Currency ≠ Fee Currency | `Settlement/Fee` |
| 3 | Settlement Currency ≠ Tax Currency | `Settlement/Tax` |
| — | 以上均不满足 | 为空——未涉及换汇 |

没有订单金额的行——被计费的失败尝试，或拒付预警——只判定费用币种；已胜诉的拒付只判定订单币种。

所以即使你的订单币种已经等于结算币种，一行也可能带有货币对：该行的换汇步骤是针对费用或税费，而不是订单。`Forex Rate` 恰在货币对为空时为空。

## 我收到一份批次号全是零的结算文件，这是什么？

那是**占位文件**，只有当你的账户被配置为在每个计划结算日都生成文件（而不是只在发生结算时生成）时才会产生：

```
settlement_details_{merchant id}_S000...000_{settlement date}_{settlement currency}.csv
settlement_summary_{merchant id}_S000...000_{settlement date}_{settlement currency}.csv
```

它只包含表头行，别无其他。全零批次号是有意为之——不存在结算批次，所以没有真实 id 可填，并且**商户 Portal 中不会出现结算批次记录**。
请把它当作区分「没有可结算的内容」与「文件没有送达」的投递心跳，而不是一次结算事件。

## 我能一次下载整个月的结算明细吗？

能，从结算批次列表下载。选择一段**实际结算日期**范围，把这些批次一起下载：

| 规则 | 值 |
| - | - |
| 每次请求最大跨度 | **1 个月**——更长的选择会在任务创建前被拒绝 |
| 行顺序 | 按结算日期**升序** |
| 每个文件行数 | **60,000** 行数据，不含表头 |
| 单文件结果 | `settlement_details_{merchant id}_{min settlement date}_{max settlement date}.csv`，无序号后缀，直接下载 |
| 多文件结果 | `settlement_details_{merchant id}_{min settlement date}_{max settlement date}.zip`，内含 `..._001.csv`、`..._002.csv`、…… |

`min settlement date` 和 `max settlement date` 是你所选范围内最早和最晚的结算日期，`YYYYMMDD` UTC+8。请求异步执行——到 Reports 模块领取结果，见
[导出与报表下载](/docs/zh/support/export-center-faq)。

如果你想按不同维度切分——按支付日期、按订单币种，或按日汇总而不是逐笔——请改用自定义导出；其选项列在
[结算报表与导出](/docs/zh/support/settlement-reports-faq)。

## PDF 文件遵循什么格式约定？

结算账单、提现账单和发票共用同一套布局和约定，所以同一个值在三者中含义相同：

| 约定 | 规则 |
| - | - |
| 金额 | 千位分隔符，**2 位小数** |
| 币种位置 | 在金额**之前**：`{Currency} {Amount}` |
| 国家/地区 | **ISO 3166-1 alpha-3**——`USA`、`CHN`、`HKG` |
| 标签 | 每个单词首字母大写 |
| 合计 | `Total` **不是**表格内的一行；单独列在表格下方 |
| 汇率列名 | 始终为 **`Forex Rate`**——绝不用 `Fx` |
| 无换汇时的汇率 | 显示为 `--`；该列保留而不删除 |

页面顺序同样固定：开具方 Waffo 实体的名称和地址，然后是单据信息块（日期和编号），然后是你的公司名称和地址，最后是业务明细表。

## 结算账单里有什么，汇率是怎么算的？

列为 **Country/Region、Transaction Amount、Fee Amount、Tax Amount、Avg. Forex Rate 和 Settlement Amount**，合计列在表格下方。`Tax Amount` 的格式与其他金额一致，即 `{Tax Currency} {Tax Amount}`。

`Avg. Forex Rate` 是**加权平均，不是简单平均**。每个分项汇率按其自身的结算金额加权：

```
Avg. Forex Rate = Σ (settlement amount ᵢ × forex rate ᵢ) / Σ (settlement amount ᵢ)
```

保留 8 位小数。用原始金额合计除以结算金额合计会得到略有不同的数字，这就是按那种方式重算无法复现账单的原因。

## 发票里有什么，为什么有好几个附件？

发票覆盖**费用**，按费用币种分组：

| 字段 | 规则 |
| - | - |
| `Invoice No` | 你的商户 ID + 所覆盖集合中最新的实际结算时间 + 费用币种 |
| `Invoice Date` | 所覆盖各次结算中**最新的实际结算日期** |
| `Commission` | 费用金额及其币种 |
| 多种费用币种 | **每种费用币种一个附件**——金额绝不跨币种合并 |

账单和发票邮件由 Waffo 财务邮箱发出；如有疑问请回复[支持](mailto:support@waffo.com)，而不是回复发件人。

\*\*IOF 不在发票上。\*\*当某笔交易适用 IOF 时，Waffo 无法为其开具发票，因此它被排除在发票文件之外。它仍会出现在结算计算中。

***

对某个具体文件做对账时仍然对不上？
[联系支持](mailto:support@waffo.com)并提供文件名——其中的结算批次 id 和结算币种足以定位该次结算。


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