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

# 概览

> 一次性支付和订阅支付的手工 API 接入路线图。

API 集成适合需要完全控制支付流程的场景。你可以直接调用 Waffo REST API，并将用户支付、订阅、退款和 Webhook 处理逻辑接入到自己的系统中。

## 适用场景

* 服务端到服务端的支付处理
* 已有自建收银台或支付表单
* 需要最大灵活性的定制化集成

## 接入路线图

<Steps>
  <Step title="选择产品方案">
    一次性支付适合单次收款订单；订阅支付适合周期扣款场景。
  </Step>

  <Step title="接入必需接口">
    一次性支付必接创建订单、查询订单和支付结果通知。订阅支付必接创建订阅、查询订阅、订阅状态通知和订阅支付通知。
  </Step>

  <Step title="按业务需要接入条件接口">
    只有业务流程需要时，再接入取消、退款、退款查询、退款通知、订阅管理页或订阅升降级。
  </Step>

  <Step title="使用 API Reference 查看字段细节">
    请求字段、响应字段、枚举和签名规则以 [API Reference](/docs/api-reference/introduction) 为准，不要从离线 PDF 复制字段定义。
  </Step>

  <Step title="在沙盒测试">
    使用 [沙盒与测试](/docs/zh/developer-docs/getting-started/sandbox)。如需 Apple Pay 或 Google Pay，请完成对应检查。
  </Step>

  <Step title="提交验收材料">
    下载 <a href="/docs/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">一次性支付验收用例模板</a> 或 <a href="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">订阅支付验收用例模板</a>，填写已执行用例，并提交给 Waffo 技术对接群。
  </Step>
</Steps>

## Base URL

| 环境         | URL                             |
| ---------- | ------------------------------- |
| Sandbox    | `https://api-sandbox.waffo.com` |
| Production | `https://api.waffo.com`         |

## 请求格式

* Content-Type: `application/json`（UTF-8 编码）
* 所有请求使用 HTTP POST
* 需携带 `X-API-KEY` 和 `X-SIGNATURE` 请求头
* 每个 `/api/v1/subscription/create` 请求都必须传入 `subscriptionManagementUrl`

## 响应格式

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

* `code` 为 `"0"` 表示成功
* 失败时 `code` 为错误码（如 `"A0003"`），`data` 为空
* 响应头 `X-SIGNATURE` 包含 Waffo 签名，**必须验证**

## 核心接口

### 一次性支付

| 接口                                                  | 是否必需 | 说明                             |
| --------------------------------------------------- | ---- | ------------------------------ |
| `POST /api/v1/order/create`                         | 必接   | 创建一次性支付订单                      |
| `POST /api/v1/order/inquiry`                        | 必接   | 查询订单状态，处理跳转丢失、网络超时和 Unknown 状态 |
| Payment order notification                          | 必接   | 接收支付终态通知，并以此更新商户侧订单状态          |
| `POST /api/v1/order/cancel`                         | 条件接入 | 取消未支付订单，有取消场景时接入               |
| `POST /api/v1/order/refund`                         | 条件接入 | 发起退款，有退款场景时接入                  |
| `POST /api/v1/refund/inquiry` 或 Refund notification | 条件接入 | 查询或接收退款处理结果                    |
| `POST /api/v1/order/capture`                        | 条件接入 | 仅 Auth-Capture 手动扣款模式需要        |

### 订阅支付

| 接口                                      | 是否必需 | 说明                     |
| --------------------------------------- | ---- | ---------------------- |
| `POST /api/v1/subscription/create`      | 必接   | 创建订阅                   |
| `POST /api/v1/subscription/inquiry`     | 必接   | 查询订阅状态和主要支付信息          |
| Subscription status notification        | 必接   | 接收订阅创建、激活、取消等状态变化      |
| Subscription payment order notification | 必接   | 接收首期和后续周期扣款结果          |
| `POST /api/v1/subscription/cancel`      | 条件接入 | 商户侧取消订阅时接入             |
| `POST /api/v1/subscription/manage`      | 条件接入 | 获取订阅管理页 URL，让用户查看或管理订阅 |
| `POST /api/v1/subscription/change`      | 条件接入 | 订阅升降级或计划变更时接入          |
| `POST /api/v1/order/inquiry`            | 条件接入 | 查询订阅支付订单的详细失败原因        |

### 配置查询

| 接口                                     | 是否必需 | 说明            |
| -------------------------------------- | ---- | ------------- |
| `POST /api/v1/merchantconfig/inquiry`  | 建议接入 | 查询商户限额和配置     |
| `POST /api/v1/paymethodconfig/inquiry` | 建议接入 | 查询可用支付方式和支付限制 |

## 验收用例模板

完成 API 集成和沙盒测试后，下载并填写对应模板：

* <a href="/docs/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">一次性支付验收用例模板</a>
* <a href="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">订阅支付验收用例模板</a>

填写完成后，将验收结果提交给 Waffo 技术对接群确认。上线前验收标准参见 [集成验收标准](/docs/zh/developer-docs/tools-and-references/references/acceptance-criteria)。