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:接收支付、退款、订阅生命周期事件
- 环境切换:先在测试环境验证,再发布到生产环境
你不需要一开始就把所有层都做完。很多团队会先从托管收银台或 AI 集成开始,后续再逐步深化 API 能力。
每条路径通常会交付什么
AI 集成
- 让 AI 编码助手阅读
llms-full.txt和官方 skill 上下文 - 结合你的技术栈生成接入代码、Webhook 处理和联调建议
- 适合已有代码仓库,希望缩短从设计到落地的时间
API / SDK
- 由你的服务端控制商品、结账、Webhook 和状态同步
- 适合需要动态定价、细粒度权限控制、内部业务编排的场景
- 更适合长期演进、深度定制和复杂计费模型
托管收银台
- 直接使用控制台生成的结账链接或公开支付入口
- 适合先验证产品是否能收款,再决定是否继续投入工程资源
- 最适合作为第一阶段接入方案
推荐实施顺序
创建账户
在 Merchant Dashboard 注册并创建第一个商店。
端到端测试
使用 沙盒环境 和测试卡号验证完整流程。
实施前准备
在真正写代码前,建议先明确这几项:- 你卖的是一次性商品、订阅,还是两者组合
- 是否需要动态定价,例如超额用量、充值包、按报价收费
- 成功支付后,系统需要开通什么权限或发放什么资源
- 你希望通过哪些 Webhook 事件驱动业务状态变化
- 哪些能力只在测试环境验证,哪些要等到正式环境再开启
常用能力入口
身份认证
配置 Merchant ID、API Key 和服务端认证方式。
沙盒环境
使用测试环境和测试卡号验证完整链路。
Webhook
接收实时事件并同步订单、退款、订阅状态。
SDKs
查看官方 SDK、框架接入方式和代码示例。
AI 集成
用 AI 编码助手完成方案设计、代码生成和联调。
快速入门
从第一笔支付开始,快速理解完整接入路径。
开发者设置
开发者页面提供将 Waffo Pancake 与您的应用程序集成的工具。
API 密钥
概述
API 密钥用于验证您对 Waffo Pancake API 的请求。测试环境密钥
- 创建时选择测试环境
- 用于开发和测试
- 无真实收费
生产环境密钥
- 创建时选择生产环境
- 用于真实支付
- 私钥必须保密
密钥类型
| 密钥类型 | 使用场景 | 描述 |
|---|---|---|
| API 密钥 | 仅服务器端 | 签名请求,完全 API 访问 |
API 密钥认证
API Key 认证由 SDK 自动处理。安装
@waffo/pancake-ts 后,只需提供 Merchant ID 和私钥,SDK 会自动完成请求签名。创建 API 密钥
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
Webhook 负载示例
签名验证
验证 webhook 真实性:Webhook 最佳实践
快速响应
快速响应
在 5 秒内返回 2xx 状态。异步处理重型工作。
处理重复
处理重复
事件可能会多次发送。使用事件 ID 进行去重。
重试逻辑
重试逻辑
失败的 webhooks 最多重试 5 次,采用指数退避。
监控失败
监控失败
为 webhook 投递失败设置告警。
API 文档
基础 URL
认证
使用 SDK 进行 API 密钥认证(服务器间通信):常用端点
| 端点 | 方法 | 描述 |
|---|---|---|
/v1/actions/onetime-product/create-product | POST | 创建一次性产品 |
/v1/actions/subscription-product/create-product | POST | 创建订阅 |
/v1/actions/onetime-order/create-order | POST | 创建结账会话 |
/v1/graphql | POST | 查询数据 (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 投递:- 事件类型
- 投递状态
- 收到的响应
- 重试次数