> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 供应商接入总览

> 面向 Waffo Point Topup 供应商：三种接入模式的区别与选择、Waffo 与供应商各自提供的接口、准备材料，以及签名、幂等和错误码等通用规范。

本页面向 Waffo Point Topup（点卡充值）的供应商，回答三个问题：三种接入模式怎么选、Waffo 和你各自要提供哪些接口、所有接口共用的规范（签名、幂等、错误码）。各模式的细节分别见 [Mode A](https://waffo.com/docs/zh/support/point-topup-mode-a-offline-import-faq.md)、[Mode B](https://waffo.com/docs/zh/support/point-topup-mode-b-point-code-api-faq.md)、[Mode C](https://waffo.com/docs/zh/support/point-topup-mode-c-direct-fulfillment-faq.md) 三篇。

## 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](https://waffo.com/docs/zh/essentials/point-topup.md))；技术接入规范见官网 点卡充值 API 集成总览 ([https://waffo.com/docs/zh/developer-docs/point-topup/overview.md](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/](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 形如：

```json theme={null}
{
  "code": "0",
  "msg": "success",
  "data": {}
}
```

请求失败时 `data` 为空。

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

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

1. 响应 body 里的 `code`：只有 `0` 表示请求被接受，其他值按下方错误码处理。
2. `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** 签名，保证报文不可抵赖：

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

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

注意区分两种签名：

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

跳转链接的签名算法见 [Mode C](https://waffo.com/docs/zh/support/point-topup-mode-c-direct-fulfillment-faq.md) 一篇。

## 怎么生成 RSA 密钥？

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

```bash theme={null}
# 生成私钥
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](https://waffo.com/docs/zh/developer-docs/point-topup/overview.md))
* 点卡充值 API 通用规范 ([https://waffo.com/docs/en/developer-docs/point-topup/api-common.md](https://waffo.com/docs/en/developer-docs/point-topup/api-common.md))
* API Reference · Point Topup ([https://waffo.com/docs/api-reference/introduction.md](https://waffo.com/docs/api-reference/introduction.md))


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.