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

# Payin 协议与交易限额

> 如何读懂 Service → Payin：Payin 协议列表的每一列、手续费与结算周期的记法、协议状态、金额限额——以及两个超限错误的含义、每日限额如何计数与释放、客户在收银台看到的是哪个名称。

**Service → Payin** 是 Portal 中记录你实际签约可接受内容的地方：哪些支付方式、在哪些国家和币种、按什么手续费基准、有哪些金额限额和退款规则。本页说明如何读懂它，以及当一笔支付触碰到其中某个限额时会发生什么。

订单创建本身见 [Order Create 字段指南](/docs/zh/support/order-create-field-guide)；退款行为见 [退款 FAQ](/docs/zh/support/refund-faq)；收银台页面向客户展示的内容见 [收银台展示规则](/docs/zh/support/cashier-display-rules-faq)。

## 我在哪里能看到自己签约了哪些支付方式？

**Service → Payin**。每个签约组合一行，包含以下列：

| 列 | 内容 |
| - | - |
| `Payment Method Country` | 该支付方式适用的国家或地区 |
| `Product` | 该行所属的产品（例如一次性支付或订阅产品） |
| `Payment method type` | 类别——卡、钱包、银行转账等 |
| `Payment method` | 具体的支付方式，带 logo |
| `Payment option` | 当某支付方式按选项分别定价时的子行 |
| `Fees` | 该行的手续费基准——见下文 |
| `User Fee` | 仅当至少有一行向付款人收取费用时才出现——见下文 |
| `Settlement cycle` | 诸如 `T+3` 的记法——见下文 |
| `Minimum amount` | 该行可接受的最小订单金额 |
| `Maximum amount` | 该行可接受的最大订单金额 |
| `Order Currency` | 订单创建所用的币种 |
| `User Currency` | 向付款人扣款的币种 |
| `Refundable` | 该行允许哪些退款形态——见下文 |
| `Refund Period` | 支付后多长时间内仍可退款 |
| `Additional Fields For Refunds` | 该行的退款是否需要额外字段 |
| `Order Expiry Customization` | 仅当该行支持自定义订单过期时间时才显示 |
| `Status` | 该行的协议状态 |
| `Mini Apps Info` | 仅当该行存在小程序信息时才显示 |

`Fees` 和 `Settlement cycle` 并非所有合约类型都会显示——如果你的页面上没有这两列，那是你的合约形态所致，不是缺少权限。

后端未提供的内容会渲染为 `-` 而不是留空，所以短横线表示「该行未配置任何内容」，而不是「零」。

## Fees 这一列怎么看？

Fees 单元格是组合而成的，不是单个数字。它最多由四部分拼装：

| 你可能看到的形态 | 读法 |
| - | - |
| `<percentage>% <currency>` | 仅按金额百分比收取 |
| `<amount> <currency>` | 仅按每笔固定金额收取 |
| `<percentage>%+<amount> <currency>` | 两者兼有——百分比加固定金额 |
| `… (min <amount>)` | 下限：手续费不会低于此值 |
| `… (max <amount>)` | 上限：手续费不会高于此值 |
| `… (min <amount>, max <amount>)` | 同时有下限和上限 |

当上限以比例而非固定金额表示时，`max` 部分会显示为百分比。

另有两个细节：

* 列头带有提示 **"Rounding up to 2 decimal places per transaction."**——四舍五入是按每笔交易进行的，而不是每个结算批次一次。
* 当某支付方式按支付选项分别定价时，该行会展开为每个选项一条手续费行。没有实质性按选项区分的支付选项渲染为 `-`。

你的实际费率是商务条款，只在你自己的页面上显示——不会在任何地方公开。

## User Fee 是什么列？为什么我看不到？

`User Fee` 是由**付款人**而非你承担的费用，出现在采用这种方式的支付方式上。该列是**条件显示**的：只有当你页面上至少有一行确实带有用户费用时，Portal 才会渲染它。如果没有任何一行有，该列就不存在——没有任何内容对你隐藏。

其列头提示为 **"Fees charged to end users."**

存在用户费用时，该行的 `Refundable` 单元格会多出第二行，告诉你退款时该费用如何处理：

| 第二行 | 含义 |
| - | - |
| `User fee refundable`（绿色对勾） | 用户费用作为退款的一部分退回 |
| `User fee not refundable`（琥珀色警告） | 用户费用不退回 |

当你向客户报退款总额时这一点很重要：付款人的费用和你的费用遵循各自独立的规则。你自己的手续费在退款时的行为见 [退款 FAQ](/docs/zh/support/refund-faq)。

## T+3 这样的结算周期是什么意思？

记法是**一个周期字母、一个 `+`、一个数字**：

| 字母 | 周期 |
| - | - |
| `T` | 每日 |
| `W` | 每周 |
| `H` | 半月 |
| `M` | 每月 |

所以 `T+3` 是延迟 3 的每日周期，`W+1` 是延迟 1 的每周周期，`M+1` 是每月周期。每月周期还有一种变体显示为 `M+1X`。

注意每日的字母是 **`T`**，不是 `D`——如果你要映射到自己的系统里，不要假定是 `D`。周期如何变成实际的打款见 [结算周期](/docs/zh/support/settlement-cycle-faq)。

## 协议状态分别是什么意思？

`Status` 列取五个值之一，按颜色区分：

| 显示的状态 | 颜色 |
| - | - |
| `Active` | 绿色 |
| `Initial` | 黄色 |
| `Onboarding` | 黄色 |
| `Suspended` | 红色 |
| `Terminated` | 红色 |

把颜色当作实际信号来读：绿色是稳定、在服务中的状态；黄色表示该行仍在开通中；红色表示不在服务中。Portal 无法识别的值会原样显示而不是隐藏，空值显示为 `-`。

如果你预期要交易的某一行不是绿色，先联系你的 Waffo 对接人，再去排查自己的集成——协议状态是在 Waffo 侧设置的，不是通过 API 设置的。

## Refundable 的几个值是什么意思？

四个值，说的是**形态**，而不是某笔具体订单现在能否退款：

| 值 | 该行允许的内容 |
| - | - |
| `No` | 该支付方式不允许退款 |
| `Only Full Refund` | 一次退款，退全额 |
| `Full Refund or One-time Partial Refund` | 一次全额退款，或一次部分退款 |
| `Full Refund or Multiple Partial Refunds` | 一次全额退款，或多次部分退款 |

旁边的 `Refund Period` 是支付后仍可接受退款的时间窗口。二者共同决定 Portal 中每笔订单的退款控制——见 [为什么退款按钮不见了或变灰了？](/docs/zh/support/transaction-field-reference-faq)。

## 这个页面有哪些筛选条件？能导出吗？

六个筛选条件：`Payment Method Country`、`Payment method type`、`Payment method`、`Order Currency`、`User Currency` 和 `Status`。`Product` 是**列，不是筛选条件**——要按产品缩小范围，先用其他字段筛选，再看 Product 列。

**Export** 会生成当前视图的 CSV：

| 行为 | 说明 |
| - | - |
| 范围 | 当前筛选条件选中的内容 |
| 行数上限 | 每次导出最多 2,000 行 |
| 交付方式 | 直接下载——这不属于排队的报表导出 |
| 表头 | 使用后端表头名称，与屏幕上的标签不完全一致——尤其是币种列导出为 *acquiring currency* 和 *local currency*，而页面显示的是 `Order Currency` 和 `User Currency` |

Portal 其他地方的排队异步导出行为不同；见 [导出与报表下载](/docs/zh/support/export-center-faq)。

## 为什么行的顺序和 Payment Method Country 列对不上？

行按**国家 → 支付方式类型 → 支付方式名称 → 产品**升序排列。

细微之处在于：排序键是协议自身的国家字段，而第一列显示的是支付方式的国家。大多数行二者一致；不一致时，按你所看的列来读，可见顺序就不会是严格的字母序。排序也是按每页结果进行的，所以翻页不会对整个集合重新排序。

## `Order Expiry Customization` 这一列到底告诉我什么？

它是该行**允许你请求的订单过期时间范围**——不是单一默认值。当某支付方式接受自定义过期时间时，单元格显示一个时间范围；不接受时，单元格显示 `-`，过期时间以合约设定为准。

决定如何读它的两个细节：

* 显示的范围是该行在移动 App 上允许的范围与在桌面浏览器上允许的范围的**交集**，因此无论购物者在哪种终端上，这个窗口都是安全的。某一行对某一种终端的实际允许范围可能比显示的更宽。
* 除非你页面上至少有一行支持自定义过期时间，否则整列**隐藏**。该列不存在表示「你的行都不支持此功能」，不是缺少权限。

## 我能自己设置订单过期时间吗？冲突时以哪个为准？

在 `order/create` 上发送 `orderExpiredAt`。不传则应用合约的过期时间——这是文档中的默认行为。

你传的值会怎样处理：

| 你传的值 | 结果 |
| - | - |
| 不传 | 应用合约的过期时间 |
| 已经过去的时间 | 该值被**丢弃**，应用合约的过期时间。订单正常创建；不会被拒绝 |
| 只有几分钟之后的时间 | 按原样接受。注意购物者需要时间完成支付，有些支付方式需要的时间比其他更长 |
| 超出该行允许范围的时间 | 把范围当作硬性要求，保持在范围内。传超出范围的值与传过去的时间是两种不同情况，而订单创建响应不会告诉你发生的是哪一种 |

有一个错误码不要误读：**`A0034`** 是当订单被处理时你提供的过期时间**已经过期**才返回的。它不是「你的过期时间超出允许范围」的错误码。

订单过期时间一经设定，就是购物者的支付窗口——窗口关闭后会发生什么、哪些订单状态是终态，见 [支付超时与终态](/docs/zh/support/payment-timeout-and-finality-faq)。

## `Mini Apps Info` 是什么列？

该行注册的钱包小程序。每一项是一个小程序名称；悬停可看到该小程序的 ID 和名称。该列固定在表格右侧，且**只有当你页面上至少有一行有小程序条目时才渲染**——否则整列不存在，没有条目的行显示 `-`。

当你在钱包小程序内收款时需要用到它，因为小程序 ID 就是向支付方式标识你小程序的凭据。集成本身，包括产品（`MINI_PROGRAM_PAYMENT`）和要传的终端值，见 [小程序支付](/docs/zh/support/mini-program-payments-faq)。

## 我的订单因为超限被拒绝了，是哪个限额？

有三种，报错信息会告诉你是哪一种：

| 信息 | 错误码 | 含义 |
| - | - | - |
| `Payment amount should be within the range` | `A0008` | 订单金额超出了 **Service → Payin 行**的 `Minimum amount` / `Maximum amount`——这是支付方式加币种维度的范围 |
| `Payment amount exceeds transaction limit.` | `A0020` | 这**单笔**订单超出了为该**订单币种**设置的**账户级**单笔交易限额。与支付方式无关 |
| `Accumulative payment amount exceeds daily transaction limit.` | `A0021` | 订单在单笔限额之内，但你在该订单币种下、**跨所有支付方式的当日累计总额**会超过上限 |

对 `A0008`，把订单金额与对应的 Service → Payin 行比对。对 `A0020` 和 `A0021`，看那一行是找错了地方：这些限额只以**商户 ID + 订单币种**为键，所以让付款人在同一币种下换一种支付方式没有用，调高一个币种的限额对另一个币种也没有作用。对 `A0021`，问题不在订单大小——而在当天。三者都在订单创建时返回，所以不会留下半创建的订单。

如果该订单币种未配置账户级限额，则 `A0020` / `A0021` 检查不会执行，两个错误都不会出现。账户级限额不在 Service → Payin 上显示；如需了解，请询问你的 Waffo 对接人。

## 每日限额到底怎么计数？额度什么时候释放？

| 问题 | 答案 |
| - | - |
| 哪一天？ | **UTC+8 自然日**。日界线是 `00:00 UTC+8`，不是你本地的午夜，也不是 UTC |
| 金额何时计入？ | 在**订单创建**时，订单记录后立即计入——不是支付成功时 |
| 哪些订单计入？ | 仍在进行中的订单**以及**成功的订单 |
| 额度何时释放？ | 只有当订单进入**关闭**状态时，且仅当它是在同一个 UTC+8 日创建的 |
| 退款会释放额度吗？ | **不会。** 对成功支付退款不会把当天的额度还回来 |

两个实际影响：

* 在 `00:00 UTC+8` 之前刚创建、之后才成功的订单，仍计入其**创建**当天。
* 被放弃的收银台订单在关闭前一直占用额度。如果你在接近上限时批量处理大量订单，通常吃掉差额的就是这些——而不是那些成功的支付。

## 我什么都没做，限额会自己变吗？

会。当某支付方式底层的服务商修改其限额时，Waffo 会重新计算你协议上的限额，新范围会出现在 **Service → Payin** 上。有两个机制值得了解：

* 当服务商的限额以与你协议不同的币种表示时，会先换算再应用，因此得出的数字很少是整数。
* 四舍五入刻意保守：**最小值向上取整**，**最大值向下取整**，因此得出的范围永远不会比底层范围更宽。对于没有辅币单位的币种——`JPY`、`KRW`、`VND` 等——最小值落在整数单位上。

从变更生效那一刻起，超出新范围的请求会以上述两个错误被拒绝。如果你的订单量接近某个限额，请从 Service → Payin 读取数值，而不要在集成中缓存它们。

## 我在用的某个支付方式要停用了，会怎么通知我？

当你的某个协议被终止时，一封写明该支付方式的邮件会发送给你商户账户下的管理员和超级管理员用户。细节：

| 行为 | 说明 |
| - | - |
| 触发 | 协议行进入 `Terminated` |
| 收件人 | 当时在商户账户下持有 Administrator 或 Super Administrator 角色的用户——所以收件人是你在 Portal 团队管理中放在这些角色下的人，而不是固定的联系地址 |
| 去重 | 每个商户每个支付方式一封邮件，不是每个协议行一封 |
| Sandbox | 沙箱环境不发送 |

之后，该行在 Service → Payin 上以红色显示 `Terminated`，该组合上的新订单会被拒绝。已有订单及其退款不受状态变更本身的影响。如果该支付方式对你的收银台很重要，请联系你的 Waffo 对接人申请替代方案——Portal 没有自助途径重新启用已终止的行。

## 我的客户在收银台看到的是哪个商户名称？

收银台页面显示一个**展示名称**，按以下顺序解析：

| 情况 | 显示的名称 |
| - | - |
| 你的订单创建请求显式传了展示名称 | 该名称优先于下面所有情况 |
| 单一商户账户，已配置展示名称 | 配置的展示名称 |
| 单一商户账户，**未**配置展示名称 | 订单信息行上**完全不显示商户名称** |
| 父商户下的子商户，已配置子商户名称 | 子商户的名称 |
| 父商户下的子商户，**未**配置子商户名称 | 回退到父商户的名称 |

重要的不对称之处：未配置的展示名称在主订单信息行上不会回退到你的法律实体名称——它就是什么都不显示。如果客户反馈收银台的商户名称空白或不符合预期，首先要检查的就是这个解析顺序。收银台页面的其他部分有各自的回退规则，所以名称可能在一处缺失而在另一处出现。页面还会显示什么，见 [收银台展示规则](/docs/zh/support/cashier-display-rules-faq)。


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