Waffo Pancake API 允许您：
- 创建和管理产品（一次性和订阅）
- 处理支付和退款
- 管理订阅和账单
- 访问客户和订单数据
- 生成结账会话
基础 URL：https://waffo-pancake-auth-service.vercel.app/v1
认证方式
Waffo Pancake 使用 API Key 认证进行所有程序化 API 访问。API Key 提供安全的服务器间通信。
API Key 认证由 SDK 自动处理。安装 @waffo/pancake-ts 后，只需提供 Merchant ID 和私钥，SDK 会自动完成请求签名。
X-Store-Slug 请求头。
保护好您的私钥。切勿在客户端代码或版本控制中暴露。
请求格式
- Content-Type：
application/json
- 所有时间戳使用 ISO 8601 格式（UTC）
- 货币金额使用最小单位（例如：
2900 = $29.00）
- ID 使用 UUID v4 格式
常用请求头
| 请求头 | 必需 | 说明 |
|---|
Content-Type | 是 | application/json |
X-Store-Slug | 条件 | 商店 slug（公开结账流程） |
X-Environment | 条件 | test 或 prod（Store Slug 认证必需） |
X-Idempotency-Key | 可选 | 写操作的唯一请求 ID |
import { WaffoPancake } from "@waffo/pancake-ts";
const client = new WaffoPancake({
merchantId: process.env.WAFFO_MERCHANT_ID!,
privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
const { store } = await client.stores.create({ name: "My Store" });
响应格式
成功响应
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Pro Plan",
"prices": {
"USD": { "amount": 2900, "taxIncluded": false, "taxCategory": "saas" }
},
"status": "active",
"createdAt": "2024-01-15T10:30:00.000Z"
}
}
错误响应
{
"data": null,
"errors": [
{
"message": "Missing required field: name",
"layer": "product"
}
]
}
gateway、user、store、product、order、graphql
HTTP 状态码
| 状态码 | 说明 |
|---|
| 200 | 成功 |
| 400 | 错误请求（参数无效） |
| 401 | 未授权（认证失败） |
| 403 | 禁止访问（权限不足） |
| 404 | 未找到 |
| 409 | 冲突（幂等请求正在处理） |
| 429 | 请求频率限制 |
| 500 | 服务器错误 |
| 环境 | 请求头值 | 说明 |
|---|
| 测试 | X-Environment: test | 开发和测试 |
| 生产 | X-Environment: prod | 正式交易 |
- 不处理真实扣款
- 数据与生产环境分离
- 完整 API 功能
主要端点
| 端点 | 方法 | 说明 |
|---|
/v1/actions/onetime-product/create-product | POST | 创建一次性产品 |
/v1/actions/subscription-product/create-product | POST | 创建订阅 |
/v1/actions/onetime-product/update-product | POST | 更新产品 |
/v1/actions/onetime-product/update-status | POST | 激活/停用 |
| 端点 | 方法 | 说明 |
|---|
/v1/actions/onetime-order/create-order | POST | 创建结账 |
/v1/actions/subscription-order/create-order | POST | 创建订阅 |
/v1/actions/refund-ticket/create-ticket | POST | 请求退款 |
GraphQL
| 端点 | 方法 | 说明 |
|---|
/v1/graphql | POST | 查询数据（只读） |
GraphQL
使用 GraphQL 进行读取操作：
query {
stores {
id
name
status
}
onetimeProducts(filter: { storeId: { eq: "..." } }) {
id
name
prices
status
}
}
merchants、stores、onetimeProducts、subscriptionProducts、orders、payments、refundTickets
SDK
Node.js
官方 Node.js SDK（即将推出）
Python
官方 Python SDK（即将推出）
Webhooks
接收事件的实时通知：
order.completed — 订单完成subscription.past_due — 订阅逾期未付subscription.activated — 订阅已激活subscription.canceled — 订阅已取消refund.succeeded — 退款已完成
了解更多关于 Webhooks → 
