跳转到主要内容

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

​
适用场景

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

​
接入路线图

1

选择产品方案

一次性支付适合单次收款订单；订阅支付适合周期扣款场景。
2

接入必需接口

一次性支付必接创建订单、查询订单和支付结果通知。订阅支付必接创建订阅、查询订阅、订阅状态通知和订阅支付通知。
3

按业务需要接入条件接口

只有业务流程需要时，再接入取消、退款、退款查询、退款通知、订阅管理页或订阅升降级。
4

使用 API Reference 查看字段细节

请求字段、响应字段、枚举和签名规则以 API Reference 为准，不要从离线 PDF 复制字段定义。
5

在沙盒测试

使用 沙盒与测试。如需 Apple Pay 或 Google Pay，请完成对应检查。
6

提交验收材料

下载 一次性支付验收用例模板 或 订阅支付验收用例模板，填写已执行用例，并提交给 Waffo 技术对接群。

​
Base URL

环境URL
Sandboxhttps://api-sandbox.waffo.com
Productionhttps://api.waffo.com

​
请求格式

  • Content-Type: application/json（UTF-8 编码）
  • 所有请求使用 HTTP POST
  • 需携带 X-API-KEY 和 X-SIGNATURE 请求头

​
响应格式

{
  "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 集成和沙盒测试后，下载并填写对应模板： 填写完成后，将验收结果提交给 Waffo 技术对接群确认。上线前验收标准参见 集成验收标准。