> ## 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 Point Topup** 是 Waffo 的点卡充值 API 与白标点卡充值方案。作为**供应商（Supplier）**，你把自己的点卡库存或充值能力接进来，Waffo Point Topup 代为运营面向终端用户的销售侧：独立子域名上的多语言店面、全球支付方式、作为该笔销售的 merchant-of-record，以及定期结算。

本组文档面向供应商的技术接入。产品视角的介绍见[点卡充值](/docs/zh/essentials/point-topup)。

## 术语

| 术语                    | 说明                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Waffo Point Topup** | Waffo 的点卡充值 API 与白标点卡充值方案。通过 URL 跳转简化集成，在多语言站点上提供全球支付方式，并作为点卡/额度销售的 merchant-of-record。每个供应商集成会分配独立子域名：`https://{supplier}.waffoplay.com/{site_code}/` |
| **Supplier**（供应商）     | 向 Waffo Point Topup 提供点卡或即时履行服务的上游服务方，例如游戏发行商、点卡发行方                                                                                                    |
| **Distributor**（分销方）  | 在本文语境下，Waffo Point Topup 作为供应商的官方分销方                                                                                                                   |
| **End User**（终端用户）    | 在 Waffo Point Topup 平台上购买点卡或充值服务的消费者                                                                                                                   |

## 三种集成模式

| 模式    | 名称       | 说明                                   | 是否需要 API  | 适用场景            |
| ----- | -------- | ------------------------------------ | --------- | --------------- |
| **A** | 离线点卡导入   | 供应商离线提供点卡，Waffo Point Topup 导入库存     | 不需要 API   | 无 API 集成、希望快速上线 |
| **B** | 点卡获取 API | Waffo Point Topup 调供应商 API 实时获取点卡    | 供应商提供 API | 由供应商掌握点卡安全与有效期  |
| **C** | 即时履行 API | Waffo Point Topup 调供应商 API 直接给用户账户充值 | 供应商提供 API | 追求用户体验与转化率，直接到账 |

<Frame>
  <img src="https://mintcdn.com/waffo-docs/hUiobY-hbNbq3QYe/images/developer-docs/point-topup/integration-mode-decision.png?fit=max&auto=format&n=hUiobY-hbNbq3QYe&q=85&s=97a31807d3e13d0dbb2361eb251eb480" alt="按供应商系统条件选择 Waffo Point Topup 集成模式的决策图" width="1057" height="609" data-path="images/developer-docs/point-topup/integration-mode-decision.png" />
</Frame>

<Card title="在线 Demo 站点" icon="monitor-play" href="https://waffoplay-demo-01.waffo.dev/">
  想看这三种模式实际怎么跑，可以在 Demo 站点走完整的端到端流程。
</Card>

### 模式对比

| 对比项               | Mode A（离线）                 | Mode B（点卡获取 API）           | Mode C（即时履行）  |
| ----------------- | -------------------------- | -------------------------- | ------------- |
| API 开发            | 不需要                        | 需要                         | 需要            |
| 实时履行              | 是，发送到用户邮箱                  | 是，发送到用户邮箱                  | 是，即时到账        |
| 库存管理              | Waffo 负责                   | 供应商负责                      | 无库存概念         |
| 供应商 → Waffo 的集成方式 | 指向 Waffo Point Topup 的静态链接 | 指向 Waffo Point Topup 的静态链接 | 带订单参数与签名的动态链接 |
| Waffo → 供应商的集成方式  | 无                          | 供应商的点卡获取 API               | 供应商的即时履行 API  |
| 最适合               | 无 API 集成的快速上线              | 供应商掌握点卡安全与有效期              | 用户体验与转化率      |

## 谁提供哪些接口

Waffo 侧只提供两个接口和一个 Webhook，它们在 [API 参考](/docs/api-reference/zh/introduction) 的「点卡充值」分组中。

供应商侧的接口**全部是可选集成**：本文档给出的规范只是示例。如果你已有等价的接口，直接把自己的接口文档给 Waffo Point Topup，Waffo 会适配你的既有接口。

| 接口                                                | 提供方            | 集成要求          |
| ------------------------------------------------- | -------------- | ------------- |
| `GET /redirect` 签名跳转                              | Waffo          | Mode C **必需** |
| `POST /api/v1/gamepin/fulfillment-inquiry` 履行结果查询 | Waffo          | 可选            |
| `FULFILLMENT_RESULT_NOTIFY` 履行结果通知 Webhook        | Waffo 发送、供应商接收 | 可选            |
| 点卡获取                                              | 供应商            | 可选集成（示例规范）    |
| 即时履行                                              | 供应商            | 可选集成（示例规范）    |
| 履行结果查询                                            | 供应商            | 可选集成（示例规范）    |

<Note>
  Mode C 的最小集成是「`GET /redirect` 签名跳转 + 履行结果通知 Webhook」，不实现任何履行接口。这种情况下 Webhook 只会返回 `PAY_SUCCESS` 与 `PAYMENT_FAILED` 两种状态，由你在收到 `PAY_SUCCESS` 后走自己的发货流程。
</Note>

## 按模式看接入准备

<AccordionGroup>
  <Accordion title="Mode A：离线点卡导入" icon="file-spreadsheet">
    需要供应商提供的材料：

    | 序号 | 材料     | 内容           | 备注                     |
    | -- | ------ | ------------ | ---------------------- |
    | 1  | 点卡数据文件 | Excel/CSV 格式 | 按 Waffo Point Topup 模板 |
    | 2  | SKU 信息 | 商品类型、面额、币种   | 与 Waffo Point Topup 确认 |
    | 3  | 结算信息   | 银行账户、结算周期    | 用于结算                   |

    接入步骤：

    <Steps>
      <Step title="提供点卡数据">供应商以 Excel/CSV 离线提供点卡数据。</Step>
      <Step title="导入库存">Waffo Point Topup 把点卡导入库存系统。</Step>
      <Step title="拿到购买链接">Waffo Point Topup 向供应商提供购买链接。</Step>
      <Step title="埋设链接">供应商在自己的网站上埋设购买链接。</Step>
      <Step title="发货">用户购买后，Waffo Point Topup 把点卡发送到用户邮箱。</Step>
      <Step title="结算">Waffo Point Topup 提供定期结算报表。</Step>
    </Steps>

    详见 [Mode A：离线点卡导入](/docs/zh/developer-docs/point-topup/mode-a-offline-import)。
  </Accordion>

  <Accordion title="Mode B：点卡获取 API" icon="package-search">
    需要供应商提供的材料：

    | 序号 | 材料             | 内容              | 备注                                 |
    | -- | -------------- | --------------- | ---------------------------------- |
    | 1  | RSA 公钥         | 用于 API 签名验证     | 2048 位                             |
    | 2  | API Key        | `X-API-KEY`     | 由供应商提供给 Waffo Point Topup          |
    | 3  | API 端点 URL     | 点卡获取 API 地址     | 生产环境 + 测试环境                        |
    | 4  | SKU 信息         | 商品类型、面额清单       | 与 Waffo Point Topup 确认             |
    | 5  | Distributor ID | `distributorId` | 供应商分配给 Waffo Point Topup 的唯一分销方 ID |
    | 6  | 结算信息           | 银行账户、结算周期       | 用于结算                               |

    接入步骤：

    <Steps>
      <Step title="交换 RSA 公钥">供应商与 Waffo Point Topup 互换 RSA 公钥。</Step>
      <Step title="提供 API 资料">供应商提供 API Key 与接口文档。</Step>
      <Step title="联调">联调点卡获取 API。</Step>
      <Step title="拿到购买链接">Waffo Point Topup 提供购买链接（静态链接）。</Step>
      <Step title="埋设链接">供应商在自己的网站上埋设链接。</Step>
      <Step title="上线">正式上线。</Step>
    </Steps>

    详见 [Mode B：点卡获取 API](/docs/zh/developer-docs/point-topup/mode-b-point-code-api)。
  </Accordion>

  <Accordion title="Mode C：即时履行 API" icon="zap">
    需要供应商提供的材料：

    | 序号 | 材料               | 内容              | 备注                |
    | -- | ---------------- | --------------- | ----------------- |
    | 1  | RSA 公钥           | 用于 API 签名验证     | 2048 位            |
    | 2  | `SECRET_KEY`     | 用于 URL 签名       | 跳转链接签名用           |
    | 3  | API 端点 URL       | 履行 API + 查询 API | 生产环境 + 测试环境       |
    | 4  | Supplier ID      | `supplierId`    | Waffo 分配的供应商唯一标识  |
    | 5  | 支持的 site code 清单 | `siteCode`      | 例如 `US`、`JP`、`HK` |
    | 6  | 结算信息             | 银行账户、结算周期       | 用于结算              |
    | 7  | Webhook URL      | 履行结果通知端点        | 用于接收履行状态          |

    接入步骤：

    <Steps>
      <Step title="交换 RSA 公钥">供应商与 Waffo Point Topup 互换 RSA 公钥。</Step>
      <Step title="提供密钥与资料">供应商提供 `SECRET_KEY`、API Key 与接口文档。</Step>
      <Step title="实现 URL 签名">供应商在后端实现 URL 签名逻辑。</Step>
      <Step title="联调">联调 URL 签名验证、即时履行 API、查询 API（可选）、履行结果通知 Webhook（可选）。</Step>
      <Step title="埋设跳转链接">供应商在网站上集成带签名的跳转链接。</Step>
      <Step title="上线">正式上线。</Step>
    </Steps>

    详见 [Mode C：即时履行 API](/docs/zh/developer-docs/point-topup/mode-c-direct-fulfillment)。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="Mode A：离线点卡导入" icon="file-spreadsheet" href="/docs/zh/developer-docs/point-topup/mode-a-offline-import">
    点卡 CSV 格式、购买链接埋点与结算报表。
  </Card>

  <Card title="Mode B：点卡获取 API" icon="package-search" href="/docs/zh/developer-docs/point-topup/mode-b-point-code-api">
    实时点卡获取接口的请求、响应与幂等要求。
  </Card>

  <Card title="Mode C：即时履行 API" icon="zap" href="/docs/zh/developer-docs/point-topup/mode-c-direct-fulfillment">
    URL 签名跳转、即时履行与履行结果查询。
  </Card>

  <Card title="API 共通规范" icon="shield-check" href="/docs/zh/developer-docs/point-topup/api-common">
    消息结构、RSA 签名验签、错误码与密钥生成。
  </Card>
</CardGroup>