本章你能收获什么
读完本章，你可以：- 根据你的商品定价方式，以及是否需要申报自己计算的税额，选择税前定价、两价齐传或含税定价。
- 知道哪些税项需要由 Waffo 配置，以及接入前需要确认哪些业务规则。
- 正确构造支付和退款请求，处理查询与 Webhook 中的金额变化、空值和错误。
ONE_TIME_PAYMENT）支持税前定价、两价齐传和含税定价三种方式。
下文的支付请求示例使用 POST /api/v1/order/create，结果通过 POST /api/v1/order/inquiry 查询。
Subscription 仅支持税前定价，不支持两价齐传和含税定价；请求字段请参阅 Subscription 创建 API。
选择传参方式
先判断你的商品价格是否已经含税，再判断是否需要向 Waffo 申报你计算的税额。三种方式由请求中的金额字段组合决定。
自算税额时，请确认 自算税额校验策略。
传入含税价后，优惠、换汇和手续费仍可能影响用户最终实付金额。字段组合及示例见下文“集成细节”。
由 Waffo 配置的税项
以下税项由 Waffo 配置。请向 Waffo 说明所需的交易行为，并分别确认 Sandbox 和 Production 的配置。税服务选项的区别
Calculation Only：Waffo 计算税额并在支付时向用户代收，通过 Settlement 将代收税款划付给你；你负责向税务机关缴纳。拆税完成后，每笔税额可从 订单查询 API 的orderTaxAmount和对应 Webhook 中读取。Full Tax Service：Waffo 负责税额计算、税款收取及缴纳；接入前请与 Waffo 确认适用范围和分工。
自算税额校验策略
此配置仅适用于两价齐传。税前定价和含税定价不使用这项申报税额校验。- Strict
- Loose
比较你申报的税额与 Waffo 计算值。不一致时，可由 Waffo 配置为拒绝交易，或使用 Waffo 计算值覆盖。
集成细节
准备接入
税配置由 Waffo 管理。接入前，请提供 Merchant ID、Sandbox 或 Production 环境、销售国家和商品类别，并确认该环境已具备所需的税协议和支付方式。 本页的含税价是订单币种下的价格。它不表示 Merchant 承担税，也不保证等于经过换汇、手续费和优惠处理后的用户实付金额。创建订单传参
金额都使用字符串，币种取orderCurrency。至少提供一个金额基数；含税价必须大于零，并符合币种精度要求。国家代码使用 ISO 3166-1 alpha-3，例如 PHL。详见 金额与币种。
税前定价时，请省略整个
taxInfo；传空对象 {} 也会因字段组合不合法返回 A0003。省略 taxInfo 不代表要求免税。
以下 JSON 只展示创建订单请求中的税相关片段。你仍需补全 Merchant、支付方式、用户、请求标识、时间和签名等通用参数。
为比较三种方式，假设订单与支付币种均为 USD、适用税率为 10%、没有优惠和额外手续费。以下税率及金额仅用于解释计算，不代表 PHL 的实际税率或你的税协议；两价齐传的结果取决于你实际配置下的申报校验策略。
- 税前定价
- 两价齐传
- 含税定价
10.00，用户支付 110.00。如果没有匹配的应税配置，不能仅凭此示例认定一定加收 10.00。读取支付结果
创建响应返回订单标识、状态和后续动作，不包含本节的税金额字段。创建订单后，请使用POST /api/v1/order/inquiry 读取这些字段。订单查询和 PAYMENT_NOTIFICATION 返回下表中的税字段；查询字段位于响应的 data 对象中，Webhook 外层结构请参阅 事件类型文档。
税前定价的响应可以有
orderTaxAmount，同时没有 taxInfo。因此，taxInfo 是否存在不能用于判断是否收税。
含税定价的中间态也可能同时出现 orderAmount = "110.00"、orderTaxAmount 为空和 taxInfo.orderAmountInclTax = "110.00"。此时不要再次减税或加税。保存你的请求原值，并以最终查询或 Webhook 中的状态和金额核对结果。
完整字段和响应示例请参阅 订单查询 API。
orderTaxAmount 已包含在含税总价的表达中，不要再次加到 finalDealAmount 上。支付未完成时，不要把当前计算金额当成已扣款金额。Webhook 的验签和状态处理见 Webhook 概览。
退款如何传参
退款金额同样使用订单币种。refundAmount 表示税前退款金额；是否可以传 taxInfo.refundAmountInclTax，由原支付单的传参方式决定。
以下为
POST /api/v1/order/refund 的局部请求；你仍需补齐原单号、退款请求标识、原因等通用参数。
- 仅税前金额
- 同时传两价
- 仅含税金额
适用于三种原支付单。只传
refundAmount，由 Waffo 计算相应退税。POST /api/v1/refund/inquiry 和 REFUND_NOTIFICATION 中，重点读取：
退款进行中或失败时，返回的计算金额不代表用户已经收到退款；请结合最终成功状态核对到账。
重试同一
paymentRequestId 或 refundRequestId 时，请保持原金额、含税金额及传参方式不变。先查询未知结果，再决定下一步，详见 幂等性。
常见错误
接入核对
- 在目标环境向 Waffo 确认税协议、商品信息和账单资料要求。
- 按一种定价方式构造请求，并验证无税、应税、缺邮编，以及申报不符时各已开通策略的结果。
- 分别保存请求原值、订单币种金额与用户支付币种金额。
- 校验含税定价在创建中间态和支付完成后的字段变化。
- 按原支付单类型验证全额及部分退款，并核对查询和 Webhook。