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

# 我该核对哪个金额和币种字段？

> 一笔订单带有多个金额——orderAmount、originalAmount、finalDealAmount、用户实际支付的金额，以及一笔用户手续费——最多涉及三种币种。本页说明核对订单时应比较哪个字段、应按哪个字段发货、为什么 finalDealAmount 与 orderAmount 不同是正常的，以及应该用哪个币种创建订单。

大多数金额问题最后都是同一个问题：*订单上有好几个金额，我不知道哪个是我的。* 本页逐字段回答。相邻的两个页面覆盖了相邻的内容，各自话题上读它们更快：

| 页面 | 用途 |
| - | - |
| [金额与币种](/docs/zh/developer-docs/core-concepts/currency) | 各币种的小数位规则，以及同币种与跨币种的定义 |
| [订单金额、限额与拒绝](/docs/zh/support/order-amount-precision-and-decline-faq) | 下单时金额**被拒**——精度、取整、限额 |
| [支付与结算中的汇率](/docs/zh/support/exchange-rates-faq) | 使用哪个汇率、何时固定、在哪里查看 |
| **本页** | 各金额字段分别是什么意思、该比较哪一个 |

## 一笔订单带有哪些金额字段？

| 字段 | 出现位置 | 含义 |
| - | - | - |
| `orderAmount` | 创建时由你传入；查询和支付通知中回显 | **你要求收取的金额**，以 `orderCurrency` 计 |
| `orderCurrency` | 同上 | 你的定价币种 |
| `originalAmount` | 查询 / 通知 | 应用折扣**之前**的订单金额。未应用折扣时不存在 |
| `finalDealAmount` | 查询 / 通知 | 用户支付的最终金额——为什么会与 `orderAmount` 不同见下文 |
| `userCurrency` | 创建时可选；回显 | 用户的支付币种，当它不是 `orderCurrency` 时 |
| `payMethodResponse.userPaymentAmount` | 查询 / 通知，位于 `paymentInfo.payMethodResponse` 内 | 用户在**支付方式一侧**实际支付的金额 |
| `payMethodResponse.userPaymentCurrency` | 同上 | 该笔支付的币种 |
| `orderAction.actionData.paymentAmount` / `paymentCurrency` | 仅订单创建响应 | 用户被要求支付的金额，面向自行渲染收银台的商户 |
| `orderAction.actionData.userFeeAmount` / `userFeeCurrency` | 仅订单创建响应 | 在你的金额之上向**付款人**收取的手续费，单独列出 |
| `remainingRefundAmount` | 退款响应 / 退款查询 | 该订单还可以退多少 |

所有金额都是**字符串**而不是数字——公开说明的原因是浮点精度：`0.1 + 0.2` 不等于 `0.3`，这对金额来说不可接受。请按 decimal 解析。

## 我该如何验证一笔订单就是我创建的那笔？

以你自己的 `paymentRequestId` 或 `merchantOrderId` 为键，把 **`orderAmount` + `orderCurrency`** 与你发送的值比较。这两个字段是你自己的输入回显，所以它们是唯一一对保证等于你所要求内容的字段。

**不要**通过比较 `finalDealAmount` 与你的预期金额来验证。它在设计上就是另一个量，两种完全正常的情形都会让它不同——这就是下一个问题。

> [!WARNING]
>
> 按 `orderAmount` 验证，但不要把跳转回你站点当作结果。权威的结果是Webhook 通知或[订单查询](/docs/zh/support/payment-results-faq)，无论金额显示什么。

## 为什么 `finalDealAmount` 和 `orderAmount` 不一样？

API 契约给出了两个原因，两者都是正常的：

1. **你的订单币种不是用户的支付币种。** 跨币种订单由你以一种币种定价、用户以另一种币种支付，所以两个数字单位不同，不会相等。
2. **用户额外支付了服务费。** 当支付方式向付款人收取手续费时，该手续费包含在 `finalDealAmount` 中，所以它比你的金额大。

所以 `finalDealAmount` 回答的是\*「这笔花了用户多少钱」*，`orderAmount` 回答的是*「我收了多少」\*。发货和业务校验请基于 `orderAmount`；只有在想向用户展示他们支付了多少时才用 `finalDealAmount`。

## `orderCurrency` 和 `userCurrency` 真的可以不同吗？

可以——这正是跨币种订单的定义：你以自己的币种定价，用户以他们的币种支付。这不是错误状态，也不限于某一类支付方式。公开的定义及配套参数见[金额与币种](/docs/zh/developer-docs/core-concepts/currency)；下单时的实际规则是，当你没有固定 `payMethodType` 或 `payMethodName` 时，跨币种订单需要 `payMethodCountry`，而 `userCurrency` 本身仍是可选的。

如果你的对账假设每笔订单只有一种币种，请从一开始就按三个字段来设计：`orderCurrency`（你的）、`userCurrency` / `userPaymentCurrency`（用户的），以及你的结算币种（见[结算计算说明](/docs/zh/support/settlement-calculation-explained)）。它们是三个独立的东西，下单时只有第一个由你控制。

## 用户以自己的币种到底付了多少？

`paymentInfo.payMethodResponse.userPaymentAmount` 加 `paymentInfo.payMethodResponse.userPaymentCurrency`。该块是支付方式自身对这笔交易的视图，还带有：

| `payMethodResponse` 中的键 | 含义 |
| - | - |
| `payMethodRefId` | **用户**在自己支付记录中看到的参考号——当用户质疑是否付过款时引用这个 |
| `exchangeRate` | 用户支付时支付方式使用的汇率 |
| `maskCardData` | 卡支付成功时，卡号前六位和后四位 |
| `userOpenId` | 用户在该支付方式的唯一 id |
| `userPaymentAmount` / `userPaymentCurrency` | 实际支付的金额和币种 |

它是一个 JSON 字符串，具体包含哪些键取决于支付方式——请防御性地读取，不要假设固定结构。

## 我能用 `finalDealAmount` 减去用户手续费算出用户净支付吗？

不能——至少不能从查询响应算。`userFeeAmount` 和 `userFeeCurrency` 返回在**订单创建响应的 `orderAction.actionData`** 中，而不是作为订单查询或支付通知的顶层字段。所以在你对账的那一刻，通常手上没有单独的手续费数字可减，而且跨两种币种做减法本来就是错的。

请改用：

* **我收到的金额对吗？** → `orderAmount` + `orderCurrency`。
* **用户总共付了多少？** → `finalDealAmount`，或支付方式一侧的数字 `userPaymentAmount`。
* **手续费是多少？** → 在创建时捕获 `actionData.userFeeAmount` 并存下来，如果之后需要。

## 用户手续费只在柜台（over-the-counter）支付时收取吗？

API 没有这样限定。`userFeeAmount` / `userFeeCurrency` 位于 `orderAction.actionData`，这是面向自建收银台商户的块，契约中没有任何内容把它们限制在某一个 `payMethodType`。把付款人手续费当作在任何支付方式上都*可能*出现，读字段本身，而不是按支付方式类别去判断——与 `finalDealAmount` 的建议一样：读它，不要推断它。

如果你使用 Waffo 收银台页面，用户会在收银台上直接看到手续费；你不需要渲染它。

## `originalAmount` 是什么？折扣应该按哪个金额校验？

`originalAmount` 是应用折扣**之前**的订单金额。使用了促销码或优惠券时，`orderAmount` 是折后应付金额，`originalAmount` 是你定价的折前数字。

所以对于业务校验——权益、履约、「他们为这个 SKU 付够了吗」——用 `orderAmount`，因为那是实际收取的金额。`originalAmount` 只用于展示或衡量折扣影响。优惠券和促销码的机制，包括退款时折扣如何处理，见[优惠券与促销码](/docs/zh/support/coupons-and-promotion-codes-faq)。

## 我的财务应该按哪个金额对账？

`orderAmount` 和 `finalDealAmount` 单独哪个都不行——它们是订单级字段，在手续费和结算换汇之前。资金对账请使用结算报表，它把金额、手续费和结算币种放在一起：[结算报表](/docs/zh/support/settlement-reports-faq)和[结算计算说明](/docs/zh/support/settlement-calculation-explained)。

订单级字段用于*订单*对账——证明你创建的订单就是被支付的那笔。把两件事分开做；这是「你的数字和我的对不上」最常见的单一原因。

## 我必须用本地币种创建订单吗？

不必。`orderCurrency` 是**你的定价币种**，跨币种订单——你以一种币种定价、用户以另一种币种支付——是受支持的一等流程。某个支付方式能否服务某个订单币种取决于你账户上的合约，这是一次查询，不是猜测：

| 查看位置 | 告诉你什么 |
| - | - |
| `/api/v1/paymethodconfig/inquiry` | 你账户上每份生效的支付方式合约各一条记录，各带其 `currency` 以及 `orderAmountMin` / `orderAmountMax` |
| Portal → Payin | 同样的合约，以可读可筛选的页面呈现——见[Payin 协议与交易限额](/docs/zh/support/payin-agreements-and-limits-faq) |
| [支付方式](/docs/zh/essentials/payment-methods) | 公开列表，可按国家、类型和支付币种筛选 |

由于该响应以**合约**为键，同一个支付方式可能出现多次——每个币种一次。`payMethodName` 不是唯一键。详情见[支付方式配置与限额](/docs/zh/support/payment-method-config-and-limits-faq)。

## 某个支付方式只列了一种币种，我还能用另一种币种定价吗？

把两种币种分开看：

* **支付币种**——向用户收取时用的币种。对本地支付方式来说，这实际上由支付方式本身固定。
* **订单币种**——你定价用的币种，也是向你计费和结算的币种。

一个支付币种是单一本地币种的支付方式，仍然可以服务你以另一种币种定价的订单；这就是跨币种情形，汇率就是用来做这个换算的。你不能做的是想当然：请检查你打算发送的组合对应的合约记录，并处理组合未配置时的拒绝码——它返回的是 `A0018`，即合约不匹配码，而不是币种专属错误；见[限额、币种与配置类错误](/docs/zh/support/error-codes-and-limits-supplement)。

## 跨币种订单的汇率在哪里看？

两个不同的汇率，两个不同的字段：

| 字段 | 含义 |
| - | - |
| `orderAction.actionData.exchangeRate` | 契约中定义为 `paymentAmount / orderAmount`，当 `orderCurrency` 与 `paymentCurrency` 不同时存在 |
| `payMethodResponse.exchangeRate` | 用户支付时支付方式自身使用的汇率 |

它们回答不同的问题，可能不一样。汇率何时固定、有效多久、退款用哪个汇率，都在[支付与结算中的汇率](/docs/zh/support/exchange-rates-faq)。

## 我可以传几位小数？取决于币种吗？

是的，取决于币种，而且同币种和跨币种订单的规则不同。公开的规则是：大多数币种按 ISO 4217 取两位小数，一组币种在同币种订单中必须**不带**任何小数，而在跨币种订单中每种币种都必须遵循其 ISO 4217 精度，没有例外。完整列表和拒绝行为见[金额与币种](/docs/zh/developer-docs/core-concepts/currency)和[订单金额、限额与拒绝](/docs/zh/support/order-amount-precision-and-decline-faq)。

各支付方式的金额范围是与精度独立的另一项检查：它们来自合约上的 `orderAmountMin` / `orderAmountMax`，所以请在创建订单前按这两个值校验，而不是从错误码里发现限额。

## 一笔退款带有哪些金额字段？

| 字段 | 含义 |
| - | - |
| `refundAmount` | 你要求退的金额，以订单币种计 |
| `finalDealAmount` | **用户收到**的金额。它可能不含用户原先支付的服务费或税费，所以可能小于对应的订单金额 |
| `remainingRefundAmount` | 本次退款后该订单仍可退的金额 |
| `userCurrency` | 当订单币种不是用户支付币种时存在 |

`remainingRefundAmount` 是你自己「还能不能退」逻辑应依据的字段，而不是从自己的记录重新计算——它已经把该订单上的每一笔退款都算进去了，包括不是你自己发起的那些。退款规则本身见[退款 FAQ](/docs/zh/support/refund-faq)和[各支付方式的退款限制](/docs/zh/support/payment-method-refund-limits-faq)。

***

还是不确定该比较哪个字段？[联系支持](mailto:support@waffo.com)，附上你的 `paymentRequestId` 和两个不一致的数字。


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