Skip to main content
本页适用于 Mode B 与 Mode C 集成。Mode A 不涉及 API，无需关注本页。

​
共通接口信息

接口响应通过 HTTP 状态码表达请求是否被成功处理：
HTTP 200 不代表业务成功。 它只说明通讯层面正常——请求送达、被受理、响应回来了。真正的业务结果必须再看两处：
  1. 响应体的 code——0 才是受理成功，其余按错误码处理；
  2. data 里的业务状态字段，例如 status、fulfillmentStatus。
举例：一笔履行失败的订单同样会以 HTTP 200 + code 为 0 返回，失败信息在 fulfillmentStatus 为 PAY_SUCCESS_SUPPLY_FAILED、以及 failureCode / failureReason 里。只看 HTTP 状态码会把它误判成成功。

​
API 消息结构

请求与响应消息均为 JSON、UTF-8 编码，由 header 与 body 两部分组成。 分销方（Waffo Point Topup）发给供应商的请求示例：
其中 X-SIGNATURE 是 Waffo Point Topup 用自己的私钥对整个 body 消息的签名。 供应商的响应示例：
这里的 X-SIGNATURE 是供应商用自己的私钥对整个 body 消息的签名。请求失败时 data 为空。

​
API 安全

Waffo Point Topup 与供应商之间通过交易签名与验签，保证消息的不可否认性。签名算法为 SHA256WithRSA。
1

供应商入网阶段

Waffo 与供应商先交换 RSA 公钥。双方各自保管自己的 RSA 私钥，只把公钥给对方。
2

API 请求阶段

Waffo 用自己的 RSA 私钥对消息签名并发送给供应商。供应商用 Waffo 的公钥验签：验签通过则处理该请求；验签失败则向 Waffo 返回 Invalid Signature 错误。
3

API 响应阶段

供应商用自己的 RSA 私钥对响应消息签名并返回给 Waffo。Waffo 用供应商的公钥验签：验签通过则处理该响应。验签失败时，Waffo 会排查并联系供应商，在问题解决前暂停向该供应商发送新交易。 因为供应商可能已经处理了这笔请求，只是 Waffo 因验签失败没能处理响应。
Waffo Point Topup 与供应商之间的 SHA256WithRSA 签名与验签流程

​
错误码

错误码前缀分类：
收到 E0001 未知状态时，不要把交易直接判为失败。持续重试查询，直到拿到明确的成功或失败终态。

​
生成 RSA 密钥

供应商可以用 openssl 生成一对 RSA 密钥。
1

安装 openssl

从 openssl.org/source 下载并安装 openssl。
2

生成密钥对

3

交换公钥

把 supplier_public_key.pem 交给 Waffo，并从 Waffo 取得 Waffo 侧的公钥。
私钥必须妥善保管，绝不能向任何第三方泄露。

​
下一步

Mode B：点卡获取 API

实时点卡获取接口的请求、响应与幂等要求。

Mode C：即时履行 API

URL 签名跳转、即时履行与履行结果查询。