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

# 商户申报税与含税下单

> 解答商户自行算税或以含税价下单时最常见的问题：三种金额传法、严格与宽松校验、税额在哪里读取、含税订单如何退款、订阅的限制，以及 A0003、A0051–A0053 的处理。

本页回答商户在「我自己算税 / 我的价格是含税的」场景下最常问的问题：下单时怎么传价格、Waffo 怎么校验、含税订单怎么退款、报 `A0051`–`A0053` 怎么办。字段级契约以官网 API 文档为准；完整的税务集成说明见官网税务集成 ([https://waffo.com/docs/zh/developer-docs/use-cases/tax.md](https://waffo.com/docs/zh/developer-docs/use-cases/tax.md))。

谁承担税费、税费如何出现在结算文件里，见[手续费与税费处理](https://waffo.com/docs/zh/support/fee-and-tax-treatment-faq.md)；税费算不出来、拒付退税等边缘情形见[税费、折扣与 Topup 边缘情形](https://waffo.com/docs/zh/support/tax-coupon-and-topup-edges-faq.md)。

## 我的商品价格是含税的，下单时该传含税价还是不含税价？

三种方式都可以，由请求里金额字段的**组合**决定，没有单独的开关：

| 你的情况 | 选哪种 | 怎么传 |
| - | - | - |
| 你维护税前价，希望由 Waffo 按适用配置计算税费 | **税前定价** | 只传 `orderAmount`（不含税价） |
| 你自己的系统算税，并在支付前向用户展示税额和含税总价 | **两价齐传** | 同时传 `orderAmount`（不含税价）、`taxInfo.orderAmountInclTax`（含税价）和 `taxInfo.taxCountry` |
| 你维护的是含税总价，希望 Waffo 拆出税前价和税额 | **含税定价** | 只传 `taxInfo.orderAmountInclTax`，不传 `orderAmount` 和 `taxCountry` |

补充几点：

* 金额都用**字符串**，币种是 `orderCurrency`；含税价必须大于 0，并符合该币种的小数位要求。
* `taxCountry` 使用 ISO 3166-1 alpha-3 三位国家码，例如 `PHL`。
* 含税价是**订单币种**下的价格。它不代表由商户承担税费，也不保证等于用户最终实付——折扣、换汇和手续费仍会影响实付金额。

## 三种传法的请求长什么样？

下面只展示与税有关的片段，商户、支付方式、用户、请求号和签名等公共参数仍需按创建订单 API ([https://waffo.com/docs/api-reference/order-create/create-new-order.md](https://waffo.com/docs/api-reference/order-create/create-new-order.md)) 补齐。为便于对比，假设订单币种为 USD、税率 10%、无折扣无额外费用；税率和金额只用于说明，不代表任何国家的实际税率。

**税前定价**

```json theme={null}
{
  "orderCurrency": "USD",
  "orderAmount": "100.00"
}
```

在上述假设下，税费为 `10.00`，用户支付 `110.00`。如果没有匹配的计税配置，不能由此推断一定会加上 `10.00`。

**两价齐传**

```json theme={null}
{
  "orderCurrency": "USD",
  "orderAmount": "100.00",
  "taxInfo": {
    "taxCountry": "PHL",
    "orderAmountInclTax": "110.00"
  }
}
```

两个价格的差额 `10.00` 就是你申报的税额。含税价不能小于不含税价。Waffo 按你账户上的校验策略处理这个申报值（见下文），传两价不会修改你的税率配置。

**含税定价**

```json theme={null}
{
  "orderCurrency": "USD",
  "taxInfo": {
    "orderAmountInclTax": "110.00"
  }
}
```

Waffo 从含税价中拆出税费；拆分完成后，不含税价 `100.00` 和税额 `10.00` 会在查询结果里返回，不会在 `110.00` 之上再加一次税。

## 税前定价时可以传一个空的 `taxInfo` 吗？

不可以。税前定价要**整个省略** `taxInfo`；传空对象 `{}` 同样会因为字段组合非法返回 `A0003`。省略 `taxInfo` 也**不等于**申请免税。

## 「严格」和「宽松」校验是什么？谁来设置？

两价齐传时，Waffo 怎么对待你申报的税额，由你账户上的「自算税额校验策略」决定。这项配置由 Waffo 设置，不是请求参数；Sandbox 和 Production 要分别确认。

| 策略 | 行为 |
| - | - |
| `Strict`（严格） | 把你申报的税额与 Waffo 计算值比较。不一致时，可配置为拒绝交易，或用 Waffo 计算值覆盖 |
| `Loose`（宽松） | 接受你申报的税额，不与 Waffo 计算值比较；仍会检查金额组合、税配置和必需参数 |

两点注意：

* 税前定价和含税定价**不使用**这项校验，它只适用于两价齐传。
* 创建订单时接受了申报值，并不代表最终税额或用户实付已确定，请以订单查询或 Webhook 为准。

接入前请向 Waffo 提供商户 ID、环境（Sandbox / Production）、销售国家和商品类别，确认该环境已有对应的税务安排和支付方式；商品名称到税类的映射也由 Waffo 配置，商品名称变化可能影响计税。

## Waffo 的税服务有哪两种范围？谁负责向税务机关缴税？

税服务范围由 Waffo 按你的合同配置，分两种：

* `Calculation Only`：Waffo 计算税额并在支付时向用户代收，再通过 Settlement 把代收的税款划付给你；向税务机关缴纳由你负责。拆税完成后，每笔税额可从订单查询的 `orderTaxAmount` 和对应 Webhook 中读取。
* `Full Tax Service`：Waffo 负责税额计算、税款收取和缴纳；适用范围和分工请在接入前与 Waffo 确认。

商品名称到税类的映射、没有匹配到税类时是拒绝交易还是使用默认税类，同样由 Waffo 配置，请分别在 Sandbox 和 Production 与 Waffo 确认。官网说明见 [税费使用场景（官网）](https://waffo.com/docs/zh/developer-docs/use-cases/tax.md)。

## 下单后在哪里看税额？

创建订单的响应只返回订单标识、状态和下一步动作，**不含**税额字段。请用订单查询 ([https://waffo.com/docs/api-reference/order-inquiry/order-inquiry.md](https://waffo.com/docs/api-reference/order-inquiry/order-inquiry.md))或支付通知（`PAYMENT_NOTIFICATION`）读取：

| 字段 | 含义 | 使用提示 |
| - | - | - |
| `orderAmount` | 拆税完成后的不含税订单金额 | 含税定价在拆税完成前，可能暂时等于含税金额，不要用中间值推断最终不含税价 |
| `orderTaxAmount` | 订单币种下的税额 | 可能为空：表示尚未拆税或没有计税结果，不要直接当作「已确认税额为 0」 |
| `taxInfo.orderAmountInclTax` | 当前最终的折后含税订单金额 | 仅两价齐传和含税定价返回；拆税完成后等于 `orderAmount + orderTaxAmount`，不是请求里折扣前的原值 |
| `taxInfo.taxCountry` | 创建时申报的计税国家 | 只有两价齐传有申报值；含税定价下可能为空 |
| `finalDealAmount`、`userCurrency` | 用户实际支付的金额及币种 | 用来核对用户实付；不要把订单币种的税额直接加到另一种币种的金额上 |

几个容易误读的地方：

* 税前定价的响应里可能有 `orderTaxAmount` 却没有 `taxInfo`，所以不能用「有没有 `taxInfo`」判断是否收了税。
* 含税定价的中间状态可能同时出现 `orderAmount = "110.00"`、`orderTaxAmount` 为空、`taxInfo.orderAmountInclTax = "110.00"`。这时不要再加税或减税，保留你的原始请求值，以最终查询或 Webhook 的状态和金额对账。
* `orderTaxAmount` 已经包含在含税总额里，不要再和 `finalDealAmount` 相加。支付未完成时，当前计算出的金额不代表已经扣款。

## 含税订单怎么退款？退款金额传含税的还是不含税的？

`refundAmount` 永远表示**不含税**的退款金额（订单币种）。能不能再传 `taxInfo.refundAmountInclTax`，取决于**原支付订单**是怎么提交的：

| 原支付订单的方式 | 允许的退款传法 | 不允许 |
| - | - | - |
| 税前定价 | 只传 `refundAmount` | 传含税退款金额 |
| 两价齐传 | 只传 `refundAmount`；或同时传 `refundAmount` 和 `taxInfo.refundAmountInclTax` | 只传含税退款金额 |
| 含税定价 | 只传 `refundAmount`，或只传 `taxInfo.refundAmountInclTax`，二选一 | 两个同时传 |

请求片段（原单号、退款请求号、原因等公共参数仍需补齐，见退款 API ([https://waffo.com/docs/api-reference/order-refund/order-refund.md](https://waffo.com/docs/api-reference/order-refund/order-refund.md))）：

```json theme={null}
{ "refundAmount": "50.00" }
```

只传不含税金额，三种原单都适用，Waffo 自行计算对应的退税。

```json theme={null}
{
  "refundAmount": "50.00",
  "taxInfo": { "refundAmountInclTax": "55.00" }
}
```

只适用于两价齐传的原单：申报不含税 `50.00` 和含税 `55.00`，差额仍按你的校验策略处理。

```json theme={null}
{
  "taxInfo": { "refundAmountInclTax": "55.00" }
}
```

只适用于含税定价的原单：只传含税退款金额，Waffo 换算出不含税退款金额。

还有几点：

* 全额退款请以原订单的**最终金额**和当前剩余可退金额为准，不要照抄折扣前的原始请求值。
* 部分退款的税额由 Waffo 计算并校验累计金额；不要自己按订单比例取整后当作权威退税结果。
* 重试同一个 `paymentRequestId` 或 `refundRequestId` 时，金额、含税金额和提交方式必须与原请求完全一致；结果不明先查询，再决定下一步。

读取退款结果时（退款查询 ([https://waffo.com/docs/api-reference/refund-inquiry/refund-inquiry.md](https://waffo.com/docs/api-reference/refund-inquiry/refund-inquiry.md))和 `REFUND_NOTIFICATION`）：

| 字段 | 含义 |
| - | - |
| `refundAmount` | 规范化后的不含税退款金额（原订单币种）；含税入参可能被换算成不同的值 |
| `orderTaxAmount` | 本次退款退还的税额（订单币种），不是整笔订单的原始税额；可能为空，零税也可能显式返回 `"0"` |
| `taxInfo.refundAmountInclTax` | 有退税结果且原单为两价齐传或含税定价时返回，等于本次 `refundAmount + orderTaxAmount`；不要假设每个中间状态都有 |
| `finalDealAmount`、`userCurrency` | 用户实际收到的退款金额及币种，可能含已退税费和可退手续费，不能只用 `refundAmount` 核对到账 |
| `remainingRefundAmount` | 剩余可退的不含税订单金额（原订单币种），不是含税余额，也不是用户支付币种下的余额 |

退款处理中或失败时返回的计算金额不代表用户已经收到退款，请以最终成功状态为准。

## 订阅可以用含税价吗？

不可以。订阅**只支持税前定价**，不支持两价齐传和含税定价；一次性支付（`ONE_TIME_PAYMENT`）三种方式都支持。订阅的请求字段见订阅创建 API ([https://waffo.com/docs/api-reference/subscription-create/create-subscription.md](https://waffo.com/docs/api-reference/subscription-create/create-subscription.md))。

## 报 `A0003`、`A0051`、`A0052`、`A0053` 怎么办？

| 错误码 | 含义与处理 |
| - | - |
| `A0003` | 参数校验失败。检查金额格式、字段组合和国家码：税前定价要省略 `taxInfo`（空对象 `{}` 也不行），含税定价不要传 `taxCountry` |
| `A0051` | 申报税额与该订单计算出的税额不一致，被 Waffo 拒绝（例如严格校验后按拒单策略处理）。检查两个价格、国家、计税细节和协议策略；不要只换幂等键重发同一个错误金额 |
| `A0052` | 没有可用的支付方式支持该订单的申报税额，或者传了 `taxInfo` 但没有对应的税务安排。请联系 Waffo 核对配置和支持范围 |
| `A0053` | 缺少校验申报税额所需的账单信息，例如邮编。按创建订单 API 补齐必需参数后重新提交 |

## 接入前后的核对清单

* 在目标环境向 Waffo 确认税务安排、商品信息和账单信息要求。
* 选定一种定价方式构造请求，并分别验证：无税、有税、缺少邮编，以及你启用的校验策略下申报不一致的情形。
* 分开保存原始请求值、订单币种金额和用户支付币种金额。
* 验证含税定价的字段在「创建中间状态」和「支付完成后」之间的变化。
* 按原单类型验证全额和部分退款，并检查退款查询与 Webhook。


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