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

# 跨币种订阅与 Portal FAQ

> 以一种币种定价、以另一种币种扣款的订阅其外汇如何运作、换算后的金额和汇率在哪里可见，以及如何在商户 Portal 中找到订阅、扣款和退款。

以一种币种定价、以另一种币种扣款的订阅，以及如何在商户 Portal 中再次找到其中的任何内容。

金额配置见
[订阅金额与按期排期 FAQ](/docs/zh/support/subscription-amount-scheduling-faq)；
创建规则见
[订阅创建与校验 FAQ](/docs/zh/support/subscription-creation-validation-faq)。
一次性订单的一般外汇行为见
[汇率 FAQ](/docs/zh/support/exchange-rates-faq)。

## 跨币种订阅的汇率在我创建时就锁定了吗？

**没有。** 跨币种订阅**每个周期单独换算**。创建时没有任何东西被锁定，也没有单一汇率适用于
订阅的整个生命周期。

这在实践中意味着：

| | 行为 |
| - | - |
| 汇率作用范围 | 每个账单周期一次换算 |
| 汇率何时确定 | 当该周期的扣款由 Waffo **发起**时 |
| 与扣款日期的关系 | 汇率属于扣款发起的那一刻，**不**一定是扣款结算的日历日期 |
| 汇率跨周期复用 | 否 |
| 商户侧金额 | 不变——你继续以你的定价币种按相同金额计费 |
| 用户侧金额 | 随汇率变动而逐周期变化 |

所以一个以你的币种固定金额定价的订阅，会在**不同周期显示不同的本地币种金额**，这是正确
行为，不是定价错误。不要构建假设用户侧金额恒定的对账逻辑，也不要向用户报出未来周期的固定
本地币种价格。

如果在某周期扣款发起时无法获取该货币对的汇率，该周期不会以过时的汇率扣款——尝试会失败，
而不是以未知汇率换算。

## 在跨币种周期中用户实际支付多少？

以用户币种扣款的金额是换算后的金额**加上任何适用的用户费用**，取整到用户币种的精度。
两部分都与汇率一起逐周期重新计算，所以用户侧总额是一个按周期的数字。

你自己这一侧的账本不受影响：订阅的 `amount`（或按期排期金额）保持在你的定价币种。

## 我在哪里能看到换算后的金额和所用的汇率？

按扣款查看，不是按订阅。订阅查询响应报告 `userCurrency`——用户被扣款的币种——但不携带
换算后的金额、汇率或费用明细。

要获取那些，请查看单笔扣款：

| 你想要什么 | 从哪里获取 |
| - | - |
| 该周期的扣款 ID | 带 `paymentDetails=1` 的 `/api/v1/subscription/inquiry`——每一项有 `acquiringOrderId` 和 `period`，当该周期有额外扣款时还有一个 `topupDetails` 列表 |
| 用户实际支付的金额 | 对该 `acquiringOrderId` 做订单查询：`finalDealAmount`，连同 `userCurrency` |
| 你自己在该周期的计费金额 | 订单查询：`orderAmount` 与 `orderCurrency` |
| 付款时向用户展示的汇率和用户费用 | 订单等待授权期间的订单查询 `orderAction.actionData`——它携带 `paymentAmount`、`paymentCurrency`、`userFeeAmount`、`userFeeCurrency` 和 `exchangeRate`。面向自行渲染收银台的商户。 |

只要币种不同或有用户费用适用，`finalDealAmount` 就与 `orderAmount` 不同——这一差异正是
该字段的意义所在，它也是用来核对用户银行账单的数字。

在 Portal 中，同样的信息位于单笔**支付详情**页面（可从订阅的支付历史进入），
而不是订阅详情页面。

## 我能找到某个 Order ID 属于哪个订阅吗？

可以。在 **Subscription → Agreements** 中，搜索框有一个维度选择器，**Order ID** 是其中一个
选项。输入订单 ID，就会返回该笔扣款所属的订阅。

该列表上搜索维度的完整集合：

| 维度 | 说明 |
| - | - |
| Subscription Id | 默认选择 |
| User Id | 你的 `merchantUserId` |
| User Email | |
| Card Last 4 Digits | 必须恰好是 4 位数字，否则搜索返回空 |
| Order ID | 反向查找——找到某笔扣款所属的订阅 |

不是订阅扣款的订单 ID 只会返回**无结果**——一次性订单没有可指向的订阅。不存在的 ID，
或属于另一个商户的 ID，也一样。

在搜索框旁边，列表按 **Period**、**Payment Method**、**Status**（全部九种订阅状态均可选）
和 **Created Datetime** 筛选。Created Datetime 是必填的，可选跨度上限约为两个月，所以在你
所选窗口之外创建的订阅无论用哪个搜索维度都不会出现——当查找意外返回空时，先放宽日期范围。

## Portal 订阅列表显示什么？

| 列 | 说明 |
| - | - |
| Subscription Id | Waffo 的 ID |
| Merchant Subscription Id | 你的 ID |
| Period Interval | 由周期类型 + 间隔渲染为周期 |
| Payment Method | |
| Card Number | 掩码；仅卡类订阅 |
| User Id | |
| User Email | |
| Subscription Amount | 附带订阅币种 |
| Status | |
| Created Datetime | |
| Action | 打开订阅详情页 |

双击一行会打开与 Action 链接相同的详情页。

## 谁可以在 Portal 中查看和取消订阅？

拥有 Subscription 菜单访问权限的 Portal 角色可以查看 Agreements 列表和订阅详情页。

**取消**还额外需要你角色上的订阅取消权限，所以只读用户能看到订阅但没有取消按钮。
在权限之外，取消按钮只在 Waffo 将该特定订阅标记为可取消时才出现——已到达终态的订阅
不提供取消操作。取消会要求确认，然后立即取消；没有撤销，重新订阅意味着创建新订阅。

## 我能列出一个订阅下的所有退款或扣款吗？

可以，在两个交易列表上都可以。在 **Transactions → Refunds** 和 **Transactions → Payments**
中，搜索维度选择器包含 **Subscription Id**。选择它，粘贴订阅 ID，列表会返回所有匹配记录。

两个列表还带有 **Subscription Id** 列，让你一眼分辨订阅流量和一次性流量：

| 情形 | 列值 |
| - | - |
| 记录属于某个订阅 | 订阅 ID |
| 一次性订单，非订阅产生 | `-` |

在此基础上构建流程之前值得了解的行为：

* 不存在或属于另一个商户的订阅 ID 返回**空列表而不是错误**。因此空结果不能证明该订阅
  没有退款。
* 以这种方式筛选的退款记录包括你发起的退款**以及**因争议产生的退款；筛选不区分来源。
* 一次性退款没有订阅 ID，所以永远无法被此筛选匹配。
* 直接打开 Refunds 列表时它会应用自己的默认日期范围（大约最近三个月），所以查找较早的
  退款时请放宽范围。

## 我如何从订阅跳转到它的退款？

订阅详情页显示该订阅的 **Refund count**。当计数大于零时它是一个链接；点击它会打开
**Transactions → Refunds**，并已应用 Subscription Id 筛选。

该跳转应用的日期范围是**订阅的开始日期到现在**——有意放宽，以覆盖订阅的整个生命周期，
而不是最近的一段。计数为零时是纯文本，没有链接。

两点注意：

* 计数汇总该订阅上的所有退款，无论来源，与筛选后列表显示的内容一致。
* 如果订阅的扣款涉及多种币种，计数是**退款笔数**，不是金额之和——请从列表本身读取金额。

## 为什么周期筛选里没有"Yearly"选项？

因为不存在 `YEARLY` 周期。周期筛选是一个两级选择器，顶层正好是 Waffo 支持的三种周期类型——
**Weekly**、**Monthly**、**Daily**——第二级是间隔。

年度订阅是 `MONTHLY` 且间隔为 `12`，所以这样筛选它：选择 **Monthly**，然后 **12**。
季度是 Monthly + 3，半年是 Monthly + 6，双周是 Weekly + 2。完整映射见
[订阅创建与校验](/docs/zh/support/subscription-creation-validation-faq)。

导出文件中也是同样的形态，它把周期渲染为间隔加单位（`1 Month`、`12 Month`、`3 Week`），
而不是有名字的套餐。页面和导出有意使用相同的措辞，所以你筛选的值就是你在文件中会找到的值。

## 我如何导出订阅列表？文件出现在哪里？

在 **Subscription → Agreements** 上设置筛选，然后使用 **Export**。导出是**服务端任务，
不是直接下载**：提交后会把你带到 **Subscription → Reports** Tab，那里列出你的导出记录及其
状态，就绪后提供下载。

| 导出状态 | 含义 |
| - | - |
| Wait Export | 已排队 |
| Need Retry | 任务失败，将再次尝试 |
| Success | 可下载 |
| Failed | 未生成文件 |

当记录仍处于非终态时 Reports Tab 会自行刷新，所以你可以把它开着而不用重新加载。

导出使用**你按下按钮时已应用的筛选**，包括必填的创建时间范围。它不是"导出全部"。

## 为什么 Export 按钮是灰的？有行数限制吗？

三种不同的条件，三种不同的消息：

| 你看到什么 | 原因 | 怎么做 |
| - | - | - |
| 按钮被禁用 | 你已有一个导出在运行。一次只能一个。 | 等待 Reports Tab 上的记录到达终态。 |
| "The current query data is empty" | 你应用的筛选没有匹配任何订阅。 | 放宽筛选——创建时间范围是常见原因。 |
| "Too many records to export, please narrow your query" | 结果集超过导出上限。 | 缩小日期范围或添加筛选，然后分片导出。 |

上限本身在服务端强制且不在 Portal 中显示，所以把消息当作信号，而不是试图计算限制。
按创建时间拆分是导出大量历史的可靠方式，因为该筛选本来就是必填的。

## 我如何在交易列表中挑出自动续订？

**Transactions → Payments** 有一个 **Card Transaction Type** 筛选，两个值：

| 值 | 含义 |
| - | - |
| `CIT` | 客户发起——客户在场并自行授权了这笔支付 |
| `MIT` | 商户发起——在后台基于已存储的授权扣款 |

自动续订是 `MIT`。订阅的首次扣款，以及客户在收银台授权的套餐变更，是 `CIT`。

一个让人栽跟头的行为：**Card Transaction Type 列只在你按它筛选时才有值**。在未筛选的查询上
该列对每一行都为空——那不是数据缺失，而是只有筛选查询才请求的投影。所以要看到 CIT/MIT，
你必须按 CIT/MIT 筛选。

该筛选适用于卡流量。对于"这一行是否属于某个订阅"（无论支付方式），请使用上文描述的
**Subscription Id** 列和筛选。

## 订阅上那些不是账单周期的额外行是什么？

订阅可以附带不属于其任何周期的扣款。它们像其他订阅流量一样带着订阅 ID 出现在交易列表中，
订单查询响应通过 `subscriptionInfo.subscriptionEvent` 区分它们：

| `subscriptionEvent` | 是什么 | 有周期号吗？ |
| - | - | - |
| `PERIOD_CHARGE` | 一个账单周期 | 有 |
| `USER_ADD_PAYMENT_METHOD` | 客户添加支付方式时发起的零金额授权 | 无 |
| `TOPUP_CHARGE` | 在现有周期内收取的额外扣款，而不是一个独立周期 | 携带它所在的周期，不是自己的周期 |

正确解读这一点对对账很重要：

* **零金额验证行是一笔真实订单。** 它出现在交易列表中，有订单 ID，且不收取任何金额。
  请按金额或按事件把它从收入报告中过滤掉，而不是假设订阅只会产生周期扣款。
* **`TOPUP_CHARGE` 不是一个周期。** 它没有试用标记，也没有自己的周期起止，因为它属于一个
  已经有这些的周期。在带 `paymentDetails=1` 的 `/api/v1/subscription/inquiry` 上，它
  **嵌套在它所在的周期之下**返回，作为该周期条目上的 `topupDetails` 列表（每一项携带该
  加购的 `acquiringOrderId`、`topupRequest`、`topupAmount`、`orderCurrency` 和
  `orderStatus`；周期没有加购时该列表不存在）。所以一个订阅的总收款金额是周期金额**加上**
  它们的 `topupDetails`，而不仅是顶层行之和。
* 在 Portal 和托管管理页面上，这些额外扣款显示在它们所属的周期下，编号为 **`period-n`**——
  `5-2` 表示第 5 期内接受的第二笔加购。只有周期行带有单纯的周期号；加购行自己的周期列为 `-`。
  这就是为什么账单历史可能显示一个周期后跟着额外几行，而不是干净的每周期一行的列表。

加购通过带 `topupInfo` 块的 `/api/v1/subscription/update` 创建——它对周期性金额的影响见
金额页面。

要找到它们，按 `acquiringOrderId` 查询订单并读取 `subscriptionInfo`；没有专门的列表端点。


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