Skip to main content
本页回答商户在「我自己算税 / 我的价格是含税的」场景下最常问的问题:下单时怎么传价格、Waffo 怎么校验、含税订单怎么退款、报 A0051–A0053 怎么办。字段级契约以官网 API 文档为准;完整的税务集成说明见官网税务集成 (https://waffo.com/docs/zh/developer-docs/use-cases/tax.md)。 谁承担税费、税费如何出现在结算文件里,见手续费与税费处理;税费算不出来、拒付退税等边缘情形见税费、折扣与 Topup 边缘情形。

我的商品价格是含税的,下单时该传含税价还是不含税价?

三种方式都可以,由请求里金额字段的组合决定,没有单独的开关: 补充几点:
  • 金额都用字符串,币种是 orderCurrency;含税价必须大于 0,并符合该币种的小数位要求。
  • taxCountry 使用 ISO 3166-1 alpha-3 三位国家码,例如 PHL。
  • 含税价是订单币种下的价格。它不代表由商户承担税费,也不保证等于用户最终实付——折扣、换汇和手续费仍会影响实付金额。

三种传法的请求长什么样?

下面只展示与税有关的片段,商户、支付方式、用户、请求号和签名等公共参数仍需按创建订单 API (https://waffo.com/docs/api-reference/order-create/create-new-order.md) 补齐。为便于对比,假设订单币种为 USD、税率 10%、无折扣无额外费用;税率和金额只用于说明,不代表任何国家的实际税率。 税前定价
在上述假设下,税费为 10.00,用户支付 110.00。如果没有匹配的计税配置,不能由此推断一定会加上 10.00。 两价齐传
两个价格的差额 10.00 就是你申报的税额。含税价不能小于不含税价。Waffo 按你账户上的校验策略处理这个申报值(见下文),传两价不会修改你的税率配置。 含税定价
Waffo 从含税价中拆出税费;拆分完成后,不含税价 100.00 和税额 10.00 会在查询结果里返回,不会在 110.00 之上再加一次税。

税前定价时可以传一个空的 taxInfo 吗?

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

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

两价齐传时,Waffo 怎么对待你申报的税额,由你账户上的「自算税额校验策略」决定。这项配置由 Waffo 设置,不是请求参数;Sandbox 和 Production 要分别确认。 两点注意:
  • 税前定价和含税定价不使用这项校验,它只适用于两价齐传。
  • 创建订单时接受了申报值,并不代表最终税额或用户实付已确定,请以订单查询或 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/api-reference/order-inquiry/order-inquiry.md)或支付通知(PAYMENT_NOTIFICATION)读取: 几个容易误读的地方:
  • 税前定价的响应里可能有 orderTaxAmount 却没有 taxInfo,所以不能用「有没有 taxInfo」判断是否收了税。
  • 含税定价的中间状态可能同时出现 orderAmount = "110.00"、orderTaxAmount 为空、taxInfo.orderAmountInclTax = "110.00"。这时不要再加税或减税,保留你的原始请求值,以最终查询或 Webhook 的状态和金额对账。
  • orderTaxAmount 已经包含在含税总额里,不要再和 finalDealAmount 相加。支付未完成时,当前计算出的金额不代表已经扣款。

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

refundAmount 永远表示不含税的退款金额(订单币种)。能不能再传 taxInfo.refundAmountInclTax,取决于原支付订单是怎么提交的: 请求片段(原单号、退款请求号、原因等公共参数仍需补齐,见退款 API (https://waffo.com/docs/api-reference/order-refund/order-refund.md)):
只传不含税金额,三种原单都适用,Waffo 自行计算对应的退税。
只适用于两价齐传的原单:申报不含税 50.00 和含税 55.00,差额仍按你的校验策略处理。
只适用于含税定价的原单:只传含税退款金额,Waffo 换算出不含税退款金额。 还有几点:
  • 全额退款请以原订单的最终金额和当前剩余可退金额为准,不要照抄折扣前的原始请求值。
  • 部分退款的税额由 Waffo 计算并校验累计金额;不要自己按订单比例取整后当作权威退税结果。
  • 重试同一个 paymentRequestId 或 refundRequestId 时,金额、含税金额和提交方式必须与原请求完全一致;结果不明先查询,再决定下一步。
读取退款结果时(退款查询 (https://waffo.com/docs/api-reference/refund-inquiry/refund-inquiry.md)和 REFUND_NOTIFICATION): 退款处理中或失败时返回的计算金额不代表用户已经收到退款,请以最终成功状态为准。

订阅可以用含税价吗?

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

报 A0003、A0051、A0052、A0053 怎么办?

接入前后的核对清单

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