跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

先选接入路径

AI 集成

最快落地适合已有代码仓库,希望借助 Claude Code 等编码代理完成方案设计、接口接入和联调验证的团队。

API / SDK

最可控适合需要自定义收银台流程、服务端编排、动态定价或精细化权限控制的场景。

托管收银台

最简单适合先上线支付链接、快速验证收款闭环,后续再逐步深化集成的团队。

如何选择

如果你当前更关心建议路径原因
尽快完成首个可用版本AI 集成适合直接把现有代码仓库交给编码代理生成接入方案和代码
对支付流程和服务端逻辑有完整控制权API / SDK适合自定义结账、动态定价、权限控制和内部编排
先验证收款闭环,再决定是否深入开发托管收银台适合低工程投入、快速上线
很多团队的实际路径是:先用托管收银台或 AI 集成完成第一版,再逐步演进到 API / SDK 深度集成。

一次完整集成通常包含什么

大多数 Waffo Pancake 集成都会包含四部分:
  • 身份认证:为服务端调用准备 Merchant ID 和 API Key
  • 产品与结账:创建一次性商品或订阅商品,并生成结账入口
  • Webhook:接收支付、退款、订阅生命周期事件
  • 环境切换:先在测试环境验证,再发布到生产环境
你的应用
    |
    +-- 身份认证 --> API / SDK 调用
    |
    +-- 商品与结账 --> 收款
    |
    +-- Webhook --> 同步订单与订阅状态
你不需要一开始就把所有层都做完。很多团队会先从托管收银台或 AI 集成开始,后续再逐步深化 API 能力。

每条路径通常会交付什么

AI 集成

  • 让 AI 编码助手阅读 llms-full.txt 和官方 skill 上下文
  • 结合你的技术栈生成接入代码、Webhook 处理和联调建议
  • 适合已有代码仓库,希望缩短从设计到落地的时间

API / SDK

  • 由你的服务端控制商品、结账、Webhook 和状态同步
  • 适合需要动态定价、细粒度权限控制、内部业务编排的场景
  • 更适合长期演进、深度定制和复杂计费模型

托管收银台

  • 直接使用控制台生成的结账链接或公开支付入口
  • 适合先验证产品是否能收款,再决定是否继续投入工程资源
  • 最适合作为第一阶段接入方案

推荐实施顺序

1

创建账户

Merchant Dashboard 注册并创建第一个商店。
2

设置身份认证

在商户控制台准备 Merchant ID 与 API Key。
3

创建商品

先定义商品类型、价格和计费周期,再通过控制台或 API 创建商品。
4

实现结账

通过 API 创建 Checkout Session,或直接使用控制台生成的结账链接。
5

处理 Webhook

设置 Webhook 端点,处理支付、退款和订阅事件。
6

端到端测试

使用 沙盒环境 和测试卡号验证完整流程。
7

上线

发布商品并切换到生产环境。

实施前准备

在真正写代码前,建议先明确这几项:
  • 你卖的是一次性商品、订阅,还是两者组合
  • 是否需要动态定价,例如超额用量、充值包、按报价收费
  • 成功支付后,系统需要开通什么权限或发放什么资源
  • 你希望通过哪些 Webhook 事件驱动业务状态变化
  • 哪些能力只在测试环境验证,哪些要等到正式环境再开启
如果这些问题还没完全想清楚,优先走 AI 集成路径会更高效;如果这些规则已经很清晰,直接进入 API / SDK 路径更合适。

常用能力入口

身份认证

配置 Merchant ID、API Key 和服务端认证方式。

沙盒环境

使用测试环境和测试卡号验证完整链路。

Webhook

接收实时事件并同步订单、退款、订阅状态。

SDKs

查看官方 SDK、框架接入方式和代码示例。

AI 集成

用 AI 编码助手完成方案设计、代码生成和联调。

快速入门

从第一笔支付开始,快速理解完整接入路径。

开发者设置

开发者页面提供将 Waffo Pancake 与您的应用程序集成的工具。
Developer API Keys

API 密钥

概述

API 密钥用于验证您对 Waffo Pancake API 的请求。

测试环境密钥

  • 创建时选择测试环境
  • 用于开发和测试
  • 无真实收费

生产环境密钥

  • 创建时选择生产环境
  • 用于真实支付
  • 私钥必须保密

密钥类型

密钥类型使用场景描述
API 密钥仅服务器端签名请求,完全 API 访问

API 密钥认证

API Key 认证由 SDK 自动处理。安装 @waffo/pancake-ts 后,只需提供 Merchant ID 和私钥,SDK 会自动完成请求签名。
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
切勿在客户端代码、版本控制或公共仓库中暴露您的私钥。

创建 API 密钥

API 密钥用于安全的服务端认证:
1

导航到开发者

前往控制台 → 商户 → 集成 → API 密钥
2

点击'创建 API 密钥'

API 密钥生成器打开
3

生成密钥对

点击”生成”创建密钥对
  • 公钥发送到服务器
  • 私钥由您保管
4

命名您的密钥

给它一个描述性名称(例如,“生产服务器”)
5

选择环境

选择测试或生产环境
6

下载私钥

重要: 下载并安全存储您的私钥
您的私钥只显示一次。请安全存储 - 您需要它进行 API 认证。

管理密钥

操作描述
查看查看密钥名称、创建日期
删除永久移除密钥(通过 delete-key API)

Webhooks

什么是 Webhooks?

Webhooks 在 Waffo Pancake 中发生事件时通知您的服务器。

可用事件

事件触发条件
order.completed订单完成
subscription.activated订阅已激活
subscription.payment_succeeded订阅扣费成功
subscription.updated订阅已更新
subscription.canceling订阅取消已安排
subscription.canceled订阅结束
subscription.uncanceled订阅取消已撤回
subscription.past_due订阅扣费逾期
refund.succeeded退款处理成功
refund.failed退款处理失败

设置 Webhooks

1

添加端点

输入您的 webhook URL(必须是 HTTPS)
2

选择事件

选择要接收的事件
3

获取签名密钥

复制 webhook 签名密钥
4

验证签名

在您的代码中实现签名验证

Webhook 负载示例

{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 9900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

签名验证

验证 webhook 真实性:
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Webhook 最佳实践

在 5 秒内返回 2xx 状态。异步处理重型工作。
事件可能会多次发送。使用事件 ID 进行去重。
失败的 webhooks 最多重试 5 次,采用指数退避。
为 webhook 投递失败设置告警。

API 文档

基础 URL

https://waffo-pancake-auth-service.vercel.app/v1

认证

使用 SDK 进行 API 密钥认证(服务器间通信):
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" });

常用端点

端点方法描述
/v1/actions/onetime-product/create-productPOST创建一次性产品
/v1/actions/subscription-product/create-productPOST创建订阅
/v1/actions/onetime-order/create-orderPOST创建结账会话
/v1/graphqlPOST查询数据 (GraphQL)

速率限制

模式限制
测试100 请求/分钟
正式1000 请求/分钟
当被限流时,您将收到 429 响应和 Retry-After 头。

安全最佳实践

环境变量

将密钥存储在环境变量中,切勿在代码中。

密钥轮换

定期轮换密钥,特别是在团队变动后。

IP 限制

限制密钥仅用于已知 IP 地址。

最小权限

仅创建具有所需权限的密钥。

测试

测试模式

使用测试模式进行开发:
  • 所有端点工作方式相同
  • 不处理真实收费
  • 可用测试卡号
  • 完整的 webhook 测试

测试卡

卡号行为
4576 7500 0000 0110成功(Visa)
2226 9000 0000 0110成功(Mastercard)
4576 7500 0000 0220拒绝

日志和调试

API 日志

查看最近的 API 请求:
  • 请求方法和端点
  • 响应状态
  • 时间戳
  • 请求/响应体

Webhook 日志

跟踪 webhook 投递:
  • 事件类型
  • 投递状态
  • 收到的响应
  • 重试次数