Mode C 的流程是怎样的？
- 你和 Waffo Point Topup 互换 RSA 公钥。
- 你把
SECRET_KEY、API Key 和 API 文档提供给 Waffo Point Topup。 - 你在自己的后端实现 URL 签名逻辑。
- 双方联调：URL 验签、直充接口、查询接口（可选）、履约结果通知（可选）。
- 你把签名跳转链接接入自己的网站。
- 上线。
接入前要准备什么？
Mode C 有哪些接口？最少要接哪些？
最小接入只需要第 1 项和第 4 项：签名跳转加履约结果通知，不需要提供自己的履约接口。这种情况下通知只上报
PAY_SUCCESS 和 PAYMENT_FAILED，你在收到 PAY_SUCCESS 后走自己的发货流程。
签名跳转链接怎么生成？
用户从你的网站进入 Waffo 时，通过带签名的 URL 参数传递用户信息，保证参数完整。签名必须在你的后端生成，绝不能把SECRET_KEY 暴露给前端。
链接格式：
{supplier} 是接入时 Waffo 分配给你的子域名。你也可以改用自己拥有的域名，只要把该域名指向 Waffo 的接入端点；此时签名串里的基础 URL 必须用这个自定义域名，因为签名覆盖基础 URL，域名不一致会验签失败。
有哪些跳转参数？
完整的类型和示例见官网 API Reference：签名跳转 (https://waffo.com/docs/api-reference/point-topup-redirect/signed-redirect-to-checkout.md)。
签名算法是什么？
- 去掉参数：排除
signature参数，并丢弃所有值为空或空白的参数。 - 排序：把剩余参数按 key 的 ASCII 升序排序。
- 拼接签名串：格式为
{baseUrl}?key1=value1&key2=value2&...，必须包含基础 URL（协议 + 主机 + 路径，例如https://supplier.waffoplay.com/redirect）。 - 计算签名：以共享的
SECRET_KEY作为 HMAC 密钥，对签名串计算 HMAC-SHA256。 - 转大写：十六进制编码后转为大写。
returnUrl 在签名串里是未编码的，在最终链接里是URL 编码后的。签名和传输是两个独立步骤，不要混用两种形式。
官网提供了 Java 实现示例，以及包含 HMAC-SHA256 和 RSA-SHA256 的 Node.js 签名示例包，见官网 Mode C：直充 API (https://waffo.com/docs/zh/developer-docs/point-topup/mode-c-direct-fulfillment.md)。
签名示例
假设参数如下：
签名串：
signature = HMAC_SHA256(签名串).toUpperCase()，最终链接：
用户点了签名链接之后，Waffo 做了什么？链接有问题会怎样？
Waffo Point Topup 后端会：- 接收所有 URL 参数；
- 校验必填参数齐全：
faceValue、salesOrderId、supplierId、supplierUserAccount、siteCode、timestamp、signature； - 校验
timestamp在 2 小时有效期内； - 用同样的算法重新计算签名并与请求中的签名比对；
- 通过后生成 JWT token 写入用户会话，并跳转到目标
siteCode的购买页。
直充接口长什么样？
用户付款后由 Waffo Point Topup 调用。
本节规范是示例。如果你已有直接充值接口，把你自己的 API 文档交给 Waffo Point Topup，Waffo 会适配你现有的接口。
幂等要求：你必须基于
salesOrderId + supplierId 实现幂等，同一请求重复到达时返回同样的成功响应。
强烈建议：核对同一 salesOrderId 的 faceValue、amount、currency 与你系统里的订单记录严格一致；业务校验不通过就拒绝履约。
请求字段
响应字段
你侧的履约查询接口长什么样？
由 Waffo Point Topup 调用，向你查询履约结果。同样是示例规范，方法POST、路径由你定义、鉴权为 SHA256WithRSA。如果你的直充接口本身幂等，可以不提供这个接口——Waffo 会用同一个 salesOrderId 重试，由你保证幂等处理。
请求字段：salesOrderId（必填，String(64)）、supplierId（必填，String(64)）。
响应字段：
履约结果通知（Webhook）会通知什么？我要怎么回应？
Waffo Point Topup 会把最终履约状态 POST 到你在签名链接里通过notifyUrl 传入的地址，覆盖这几种情况：付款成功但履约失败、付款失败、未付款超时。事件名为 FULFILLMENT_RESULT_NOTIFY，业务数据在 data 里。
你的接口必须基于 salesOrderId + supplierId 实现幂等：同一通知重复到达时，返回同样的成功响应。
驱动你业务逻辑的字段是 fulfillmentStatus：
failureCode 取值：
通知数据里除上述字段外，还包含
supplierId、salesOrderId、faceValue、amount、currency、requestedAt、completedTime、buyerInfo、payMethodName（用户实际使用的支付方式）、payOrderId（Waffo Point Topup 生成的支付订单号，用于追踪支付、退款和争议）、productId、failureCode、failureReason。完整字段见官网 API Reference：履约结果通知 (https://waffo.com/docs/api-reference/point-topup-fulfillment-webhook.md)。
收到通知后怎么回应？重试规则是什么？
处理成功后，返回 HTTP200 OK，并且响应 body 里包含 success，例如：
漏收了通知，能主动查履约结果吗？
可以。Waffo 提供履约查询接口，是履约结果通知的主动拉取版，常用于对账，或在漏收通知时兜底。响应里的data 结构和通知中的 data 一致。
查询键：
supplierId 必填；salesOrderId 和 payOrderId 至少传一个。订单不存在或不属于调用方供应商时，返回错误，错误码见供应商接入总览。