Mode B 卡密获取接口

本页说明 Mode B（点卡获取 API）：用户付款后，Waffo Point Topup 实时调用你的点卡获取接口取得点卡，再发送给用户。适合已有点卡库存系统并带 API 的供应商，例如有数字点卡生成系统的游戏发行商，或已有 API 的点卡分销商。

Mode B 的流程是怎样的？

你和 Waffo Point Topup 互换 RSA 公钥。
你把 API Key 和 API 文档提供给 Waffo Point Topup。
双方联调点卡获取接口。
Waffo Point Topup 把购买链接（静态链接）提供给你。
你把链接嵌入自己的网站。
上线。

用户购买时：用户付款成功后，Waffo Point Topup 实时调用你的接口取得点卡，并发送到用户邮箱。

优点	适用场景
实时获取点卡	有数字点卡生成系统的游戏发行商
无需人工管理库存	已有 API 的点卡分销商
库存自动同步

接入前要准备什么？

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

我已经有点卡获取接口了，要按文档重做吗？

不需要。本页的规范只是示例。如果你已有点卡获取接口，把你自己的 API 文档交给 Waffo Point Topup，Waffo 会适配你现有的接口。

用户怎么从我的网站跳到 Waffo？

两种方式：

直接提供一个不带签名的静态链接：https://{supplier}.waffoplay.com/{site_code}/
使用 Mode C 的 URL 签名方式（见Mode C：直充接口与结果通知）

点卡获取接口长什么样？

用户付款后由 Waffo Point Topup 调用，向你获取点卡。

项目	内容
方法	`POST`
路径	由你定义
鉴权	通用接口签名（SHA256WithRSA），见供应商接入总览

幂等要求：你必须基于 distributorOrderId + distributorId 实现幂等。同一个请求重复到达时，返回同样的点卡，不得再次扣减库存。

请求字段

字段	说明	类型	是否必填
`distributorId`	你分配给 Waffo Point Topup 的分销方 ID	String(64)	必填
`distributorOrderId`	Waffo Point Topup 的订单 ID，与 `distributorId` 一起作为幂等键	String(64)	必填
`skuId`	SKU 标识	String(128)	必填
`quantity`	获取的点卡数量，通常为 1	Integer	必填
`faceValue`	面额，用于面额可变的商品	String(32)	选填
`requestedAt`	Waffo Point Topup 侧的请求时间	String(32)	必填

响应字段

字段	说明	类型	是否必填
`distributorOrderId`	Waffo Point Topup 的订单 ID	String(64)	必填
`status`	订单状态：`SUCCESS` 获取点卡成功，`FAILURE` 获取失败	String(24)	必填
`pointList`	点卡列表，仅在 `status` 为 `SUCCESS` 时返回	Array	选填
`pointList[].pointCode`	点卡	String(128)	必填
`pointList[].expiryDate`	有效期截止日	String(32)	选填
`pointList[].faceValue`	面额	String(32)	选填
`failureCode`	失败码，`status` 为 `FAILURE` 时返回	String(24)	选填
`failureReason`	失败原因	String(128)	选填

示例

请求：

{
  "distributorId": "WAFFO_POINT_TOPUP_001",
  "distributorOrderId": "WP202501050001",
  "skuId": "SUPPLIER_POINT_001",
  "quantity": 1,
  "faceValue": "1000",
  "requestedAt": "2025-01-05T10:30:00.000Z"
}

响应（成功）：

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "SUCCESS",
    "pointList": [
      {
        "pointCode": "ABCD-1234-EFGH-5678",
        "expiryDate": "2026-12-31",
        "faceValue": "1000"
      }
    ]
  }
}

响应（失败，例如库存不足）：

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "FAILURE",
    "failureCode": "INSUFFICIENT_INVENTORY",
    "failureReason": "No available points in inventory"
  }
}

库存不足这类失败，应该返回 HTTP 错误吗？

不应该。status 为 FAILURE 是业务失败：HTTP 状态码和外层 code 仍然表示成功（200 和 0），失败原因放在 data 里的 failureCode 和 failureReason。只有系统级错误才按通用错误码返回（错误码表见供应商接入总览）。

想了解更多？

官网：Mode B：点卡获取 API (https://waffo.com/docs/zh/developer-docs/point-topup/mode-b-point-code-api.md)

产品与服务

收单与支付

结算与资金

增值服务

高级功能

点卡充值

Mode B 的流程是怎样的？

接入前要准备什么？

我已经有点卡获取接口了，要按文档重做吗？

用户怎么从我的网站跳到 Waffo？

点卡获取接口长什么样？

请求字段

响应字段

示例

库存不足这类失败，应该返回 HTTP 错误吗？

想了解更多？

​Mode B 的流程是怎样的？

​接入前要准备什么？

​我已经有点卡获取接口了，要按文档重做吗？

​用户怎么从我的网站跳到 Waffo？

​点卡获取接口长什么样？

​请求字段

​响应字段

​示例

​库存不足这类失败，应该返回 HTTP 错误吗？

​想了解更多？

Mode B 的流程是怎样的？

接入前要准备什么？

我已经有点卡获取接口了，要按文档重做吗？

用户怎么从我的网站跳到 Waffo？

点卡获取接口长什么样？

请求字段

响应字段

示例

库存不足这类失败，应该返回 HTTP 错误吗？

想了解更多？