> ## 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.

# Mode B 卡密获取接口

> 说明 Waffo Point Topup 的 Mode B 点卡获取 API：接入流程与准备材料、跳转方式、点卡获取接口的请求与响应字段、幂等要求，以及库存不足等业务失败的返回方式。

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

## Mode B 的流程是怎样的？

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

用户购买时：用户付款成功后，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：直充接口与结果通知](https://waffo.com/docs/zh/support/point-topup-mode-c-direct-fulfillment-faq.md)）

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

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

| 项目 | 内容 |
| - | - |
| 方法 | `POST` |
| 路径 | 由你定义 |
| 鉴权 | 通用接口签名（SHA256WithRSA），见[供应商接入总览](https://waffo.com/docs/zh/support/point-topup-supplier-integration-overview-faq.md) |

**幂等要求**：你必须基于 `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) | 选填 |

### 示例

请求：

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

响应（成功）：

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

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

```json theme={null}
{
  "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`。只有系统级错误才按通用错误码返回（错误码表见[供应商接入总览](https://waffo.com/docs/zh/support/point-topup-supplier-integration-overview-faq.md)）。

## 想了解更多？

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


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