API 参考

概述

Waffo Pancake API 允许您以编程方式管理整个支付基础设施：

创建和管理门店
创建商品（一次性和订阅）
生成收银台会话和处理订单
管理订阅和计费
通过 GraphQL 查询数据
处理退款

基础 URL

所有 API 请求发送至：

https://api.waffo.ai/v1

架构

API 采用混合架构：

REST 端点 (/v1/actions/...) 用于所有写操作（创建、更新、删除）
GraphQL (/v1/graphql) 用于所有读操作（查询）

所有 REST 端点仅使用 POST 方法。没有 GET、PUT、PATCH 或 DELETE 方法。

TypeScript SDK

官方 @waffo/pancake-ts SDK 提供完整类型安全的 API 封装。它自动处理认证、请求签名、幂等键和 Webhook 验签。

npm install @waffo/pancake-ts

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

以下文档的每个端点都包含 SDK 示例和 REST/cURL 示例。查看完整 SDK 文档 ->

认证

Waffo Pancake 使用 API Key 认证 进行所有编程式 API 访问。SDK 自动处理 API Key 认证。对于面向公众的收银台流程，使用 Store Slug 认证，通过 X-Store-Slug 请求头访问。了解更多认证信息 ->

通用请求头

请求头	必需	说明
`Content-Type`	是	始终为 `application/json`
`X-Store-Slug`	条件性	Store Slug（用于公开收银台流程）
`X-Environment`	条件性	`test` 或 `prod`（使用 Store Slug 认证时必需，API Key 不需要）
`X-Idempotency-Key`	可选	每个写操作全局唯一的 ID（缓存 24 小时）

API Key 认证请求头（X-Merchant-Id、X-Timestamp、X-Signature）由 SDK 自动处理。您只需在初始化客户端时提供 Merchant ID 和私钥。

请求格式

方法: 所有写端点使用 POST
请求体: JSON
时间戳: ISO 8601 UTC（例如 2026-01-23T00:00:00.000Z）
金额: 显示格式字符串（例如 "29.00" = $29.00 USD）
货币: ISO 4217 代码（例如 USD、EUR、JPY）
状态值: 始终小写（例如 active，不是 ACTIVE）

ID 格式

所有对外实体 ID 使用 Short ID 格式：{PREFIX}_{base62}。

前缀	实体	示例
`MER`	Merchant	`MER_2D5F8G3H1K4M6N9P`
`STO`	Store	`STO_3bVzrkD0FJjFdZNLk8Ualx`
`PROD`	Product / Version	`PROD_4cWAslE1GKkGeaOMl9Vbmy`
`ORD`	Order	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`PAY`	Payment	`PAY_6eYCunG3IMmIgcQOnaXdoA`
`REF`	Refund	`REF_7fZDvoH4JNnJhdRPobYepB`
`TKT`	Ticket	`TKT_8gAEwpI5KOoKieSQL1ZfqC`
`KEY`	API Key	`KEY_4F7H0I5J3K6M8N1P`

Checkout Session ID 使用特殊格式：cs_ + UUID（例如 cs_550e8400-e29b-41d4-a716-446655440000）。它们不属于 Short ID 体系。

响应格式

成功

{
  "data": {
    "store": {
      "id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
      "name": "My Store",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
}

错误

{
  "data": null,
  "errors": [
    {
      "message": "Store slug already exists",
      "layer": "store"
    }
  ]
}

在 errors 数组中，errors[0] 是故障的根因。后续条目代表请求链中更高层的调用方。

错误 `layer` 字段

每个错误包含一个 layer 字符串，指示系统的哪个部分产生了该错误。调试时可用于定位根因。该值始终是预定义的层名称之一（例如 "gateway"、"store"、"product"）。

HTTP 状态码

状态码	说明
200	成功
400	请求错误 — 参数无效
401	未授权 — 认证失败
403	禁止访问 — 权限不足
404	未找到
409	冲突 — 幂等请求正在处理中
429	频率限制 — 请求过多
500	内部服务器错误
501	未实现
502	网关错误

环境

API Key 认证根据成功验证的密钥自动确定环境。Store Slug 认证需要 X-Environment 请求头：

环境	请求头值	说明
测试	`X-Environment: test`	无真实扣费，数据隔离
生产	`X-Environment: prod`	真实交易

幂等性

通过 X-Idempotency-Key 请求头防止重复写操作：

项目	规格
请求头	`X-Idempotency-Key`
唯一性	在您的商户账户内，每个请求全局唯一
最大长度	256 字符
允许字符	字母、数字、连字符 (`-`)、下划线 (`_`)
缓存时长	24 小时

尽可能让 SDK 生成幂等键 —— 它将 merchantId + 路径 + 请求体计算为确定性哈希，因此天然做到每个请求唯一。如果自行构造，请将 merchantId 与 UUID 组合：

X-Idempotency-Key: MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67

简短、易猜的键可能与另一个请求已使用的键相同，此时您收到的是那个请求的缓存响应。完整要求见错误处理 -> 幂等性保障安全重试。

场景	行为	状态码
首次请求	正常执行，缓存 2xx 响应	原始状态码
重复（已完成）	返回缓存响应，不重新执行	原始状态码
重复（处理中）	返回冲突错误	409
原始请求失败（非 2xx）	同一个键可以重试	—

端点分组

认证

为收银台流程签发 Session Token

门店

创建、更新和删除门店

一次性商品

创建和管理一次性购买商品

订阅商品

创建分层订阅商品和产品组

订单

创建收银台会话和订单

退款

请求和处理退款

GraphQL

通过 GraphQL 查询所有数据

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

概述

基础 URL

架构

TypeScript SDK

认证

通用请求头

请求格式

ID 格式

响应格式

成功

错误

错误 `layer` 字段

HTTP 状态码

环境

幂等性

端点分组

认证

门店

一次性商品

订阅商品

订单

订阅

退款

GraphQL

​概述

​基础 URL

​架构

​TypeScript SDK

​认证

​通用请求头

​请求格式

​ID 格式

​响应格式

​成功

​错误

​错误 layer 字段

​HTTP 状态码

​环境

​幂等性

​端点分组

认证

门店

一次性商品

订阅商品

订单

订阅

退款

GraphQL

概述

基础 URL

架构

TypeScript SDK

认证

通用请求头

请求格式

ID 格式

响应格式

成功

错误

错误 `layer` 字段

HTTP 状态码

环境

幂等性

端点分组