供应商接入总览

本页面向 Waffo Point Topup（点卡充值）的供应商，回答三个问题：三种接入模式怎么选、Waffo 和你各自要提供哪些接口、所有接口共用的规范（签名、幂等、错误码）。各模式的细节分别见 Mode A、Mode B、Mode C 三篇。

Waffo Point Topup 是什么？我作为供应商能得到什么？

Waffo Point Topup 是 Waffo 的点卡充值 API 与白标点卡充值方案。你把自己的点卡库存或充值能力接进来，面向终端用户的销售侧由 Waffo 代为运营：

独立子域名上的多语言店面，地址形如 https://{supplier}.waffoplay.com/{site_code}/（{supplier} 是接入时 Waffo 分配给你的子域名）
全球支付方式
Waffo 作为这笔销售的 merchant-of-record
定期向你结算

几个术语：

术语	说明
供应商（Supplier）	向 Waffo Point Topup 提供点卡或直充服务的上游服务方，例如游戏发行商、点卡发行方
分销方（Distributor）	在这套方案里，Waffo Point Topup 是供应商的官方分销方
终端用户（End user）	在 Waffo Point Topup 平台上购买点卡或充值的消费者

产品层面的介绍见官网点卡充值 (https://waffo.com/docs/zh/essentials/point-topup.md)；技术接入规范见官网点卡充值 API 集成总览 (https://waffo.com/docs/zh/developer-docs/point-topup/overview.md)。

三种接入模式有什么区别？

模式	名称	是否需要你开发 API	适用场景
A	离线点卡导入	不需要	想快速上线、不做 API 集成
B	点卡获取 API	需要（你提供点卡获取接口）	点卡安全与有效期由你自己掌控
C	直充 API	需要（你提供直充接口）	追求用户体验与转化率，直接到账

更细的对比：

对比项	Mode A	Mode B	Mode C
是否需要开发 API	不需要	需要	需要
是否实时交付	是，点卡发到用户邮箱	是，点卡发到用户邮箱	是，直接到账
库存由谁管理	Waffo	你	无库存
你跳转到 Waffo 的方式	静态链接	静态链接	带订单参数和签名的动态链接
Waffo 调用你的接口	无	你的点卡获取接口	你的直充接口

我该选哪种模式？

按你的系统条件来选：

没有 API 能力，想尽快上线：选 Mode A，只需按模板提供点卡文件。
已有点卡库存系统并带 API，希望点卡生成与有效期仍由你控制：选 Mode B，用户付款后 Waffo 实时向你的接口获取点卡。
能直接给用户账号充值：选 Mode C，用户付款后 Waffo 调用你的直充接口，用户不需要接触点卡。

官网提供了一个在线演示站点 (https://waffoplay-demo-01.waffo.dev/)，可以走完三种模式的端到端流程。

Waffo 提供哪些接口，我要提供哪些？

Waffo 只提供两个接口和一个 Webhook（在官网 API Reference 的 Point Topup 分组中）。供应商一侧的接口都是可选集成：文档里的规范只是示例，如果你已有功能等价的接口，把你自己的接口文档交给 Waffo，Waffo 会适配你现有的接口，不需要按示例重做。

接口	提供方	是否必须
`GET /redirect` 签名跳转	Waffo	Mode C 必须接入
`POST /api/v1/gamepin/fulfillment-inquiry` 履约结果查询	Waffo	可选
`FULFILLMENT_RESULT_NOTIFY` 履约结果通知（Webhook）	Waffo 发送，你接收	可选
点卡获取接口	你	可选集成（示例规范，Mode B）
直充接口	你	可选集成（示例规范，Mode C）
履约查询接口	你	可选集成（示例规范，Mode C）

Mode C 的最小接入只需要 GET /redirect 签名跳转加上履约结果通知，不需要自己提供履约接口。这种情况下通知只会上报 PAY_SUCCESS 和 PAYMENT_FAILED，你在收到 PAY_SUCCESS 后走自己的发货流程。

每种模式接入前要准备哪些材料？

Mode A

材料	说明
点卡数据文件	Excel/CSV，按 Waffo 模板
SKU 信息	商品类型、面额、币种，与 Waffo 确认
结算信息	银行账户、结算周期

Mode B

材料	说明
RSA 公钥	用于接口验签，2048 位
API Key	即请求头 `X-API-KEY`，由你提供给 Waffo
接口地址	点卡获取接口的生产与测试环境地址
SKU 信息	商品类型、面额列表，与 Waffo 确认
分销方 ID	`distributorId`，由你分配给 Waffo 的唯一分销方标识
结算信息	银行账户、结算周期

Mode C

材料	说明
RSA 公钥	用于接口验签，2048 位
`SECRET_KEY`	用于对跳转链接签名
接口地址	直充接口与查询接口的生产与测试环境地址
供应商 ID	`supplierId`，由 Waffo 分配的唯一标识
支持的站点代码列表	`siteCode`，例如 `US`、`JP`、`HK`
结算信息	银行账户、结算周期
Webhook 地址	接收履约状态通知的地址

接口的通用格式是什么？

以下通用规范适用于 Mode B 和 Mode C；Mode A 没有 API，不涉及。

项目	说明
协议	RESTful
报文格式	JSON 请求体（`Content-Type: application/json`），UTF-8 编码
提交方式	HTTP `POST`
传输安全	HTTPS，TLS 1.2 及以上
时间	ISO 8601，精确到毫秒，例如 `2023-04-01T03:00:00.000Z`
币种	ISO 4217 币种代码，字符串类型
金额	法币精度为 2 位小数，字符串类型，例如 `2.27`
国家代码	ISO 3166-1 alpha-3，例如 `IDN`、`PHL`、`HKG`

Waffo 发给你的请求，以及你返回的响应，都由 header 和 body 两部分组成，签名放在 header 的 X-SIGNATURE 中，是对整个 body 报文的签名。你的响应 body 形如：

{
  "code": "0",
  "msg": "success",
  "data": {}
}

请求失败时 data 为空。

HTTP 200 就代表业务成功吗？

不是。HTTP 200 只说明传输成功：请求到了、被接收了、有响应返回。业务结果还要再看两处：

响应 body 里的 code：只有 0 表示请求被接受，其他值按下方错误码处理。
data 里的业务状态字段，例如 status 或 fulfillmentStatus。

例如履约失败同样以 HTTP 200、code 为 0 返回，失败体现在 fulfillmentStatus 为 PAY_SUCCESS_SUPPLY_FAILED，并带有 failureCode 和 failureReason。只看 HTTP 状态码会把它误读成成功。 HTTP 状态码本身的分类：

类别	状态码
2XX 成功	`200`
4XX 客户端错误	`400`、`401`、`403`、`404`、`405`
5XX 服务端错误	`500`、`502`、`503`、`504`

接口怎么签名、验签？

Waffo 与供应商之间的接口使用 SHA256WithRSA 签名，保证报文不可抵赖：

接入阶段：双方互换 RSA 公钥，各自保管自己的私钥，只共享公钥。
请求阶段：Waffo 用自己的私钥对报文签名后发给你；你用 Waffo 的公钥验签，通过才处理请求，不通过就返回 Invalid Signature 错误。
响应阶段：你用自己的私钥对响应签名后返回；Waffo 用你的公钥验签，通过才处理响应。

如果验签失败，Waffo 会排查并联系你，并在问题解决前停止向你发送新交易——因为你可能已经处理了请求，而 Waffo 因验签失败没能处理响应。注意区分两种签名：

场景	算法	密钥
Waffo 与你之间的接口报文（Mode B、Mode C 的接口调用）	SHA256WithRSA	RSA 密钥对
你的站点跳转到 Waffo 的 Mode C 签名链接	HMAC-SHA256	共享的 `SECRET_KEY`

跳转链接的签名算法见 Mode C 一篇。

怎么生成 RSA 密钥？

用 openssl 生成一对 2048 位的密钥：

# 生成私钥
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out supplier_private_key.pem

# 生成公钥
openssl rsa -in supplier_private_key.pem -pubout > supplier_public_key.pem

把 supplier_public_key.pem 交给 Waffo，同时拿到 Waffo 的公钥。私钥必须妥善保管，不得泄露给任何第三方。

幂等有什么要求？

你侧的接口必须支持幂等：同一个请求重复到达时，返回相同的结果，不重复扣库存、不重复充值。

接口	幂等键	重复请求时
点卡获取接口（Mode B）	`distributorOrderId` + `distributorId`	返回同样的点卡，不再次扣减库存
直充接口（Mode C）	`salesOrderId` + `supplierId`	返回同样的成功响应
履约结果通知（Mode C，你接收）	`salesOrderId` + `supplierId`	返回同样的成功响应

接口返回了错误码，怎么处理？

错误码前缀表示类别：

前缀	类别
`A`xxxx	供应商相关错误
`B`xxxx	用户相关错误
`C`xxxx	系统相关错误
`D`xxxx	风险拒绝
`E`xxxx	未知错误，由供应商或第三方系统内部状态未知导致。需要持续重试交易，直到拿到最终的成功或失败状态

错误码	说明	HTTP 状态码
`0`	成功	200
`A0001`	API 密钥无效	401
`A0002`	签名无效	401
`A0003`	参数校验失败	400
`A0004`	无权限	401
`A0005`	购买面额超过允许的最大值	400
`A0006`	订单不存在	400
`A0007`	幂等参数不一致	400
`A0008`	请求过于频繁，请稍后重试	400
`B0001`	买家信息不存在	400
`B0002`	买家信息不匹配	400
`C0001`	系统错误	500
`C0002`	订单信息不一致	500
`D0001`	风险拒绝	406
`E0001`	未知状态	500

收到 E0001（未知状态）时，不要把交易当作失败，要持续查询，直到拿到明确的成功或失败状态。

想看英文原文或完整字段？

细节以官网为准：

点卡充值 API 集成总览 (https://waffo.com/docs/zh/developer-docs/point-topup/overview.md)
点卡充值 API 通用规范 (https://waffo.com/docs/en/developer-docs/point-topup/api-common.md)
API Reference · Point Topup (https://waffo.com/docs/api-reference/introduction.md)

产品与服务

收单与支付

结算与资金

增值服务

高级功能

点卡充值

Waffo Point Topup 是什么？我作为供应商能得到什么？

三种接入模式有什么区别？

我该选哪种模式？

Waffo 提供哪些接口，我要提供哪些？

每种模式接入前要准备哪些材料？

接口的通用格式是什么？

HTTP 200 就代表业务成功吗？

接口怎么签名、验签？

怎么生成 RSA 密钥？

幂等有什么要求？

接口返回了错误码，怎么处理？

想看英文原文或完整字段？

​Waffo Point Topup 是什么？我作为供应商能得到什么？

​三种接入模式有什么区别？

​我该选哪种模式？

​Waffo 提供哪些接口，我要提供哪些？

​每种模式接入前要准备哪些材料？

​接口的通用格式是什么？

​HTTP 200 就代表业务成功吗？

​接口怎么签名、验签？

​怎么生成 RSA 密钥？

​幂等有什么要求？

​接口返回了错误码，怎么处理？

​想看英文原文或完整字段？

Waffo Point Topup 是什么？我作为供应商能得到什么？

三种接入模式有什么区别？

我该选哪种模式？

Waffo 提供哪些接口，我要提供哪些？

每种模式接入前要准备哪些材料？

接口的通用格式是什么？

HTTP 200 就代表业务成功吗？

接口怎么签名、验签？

怎么生成 RSA 密钥？

幂等有什么要求？

接口返回了错误码，怎么处理？

想看英文原文或完整字段？