先选接入路径
AI 集成
最快落地适合已有代码仓库,希望借助 Claude Code 等编码代理完成方案设计、接口接入和联调验证的团队。
API / SDK
最可控适合需要自定义收银台流程、服务端编排、动态定价或精细化权限控制的场景。
托管收银台
最简单适合先上线支付链接、快速验证收款闭环,后续再逐步深化集成的团队。
如何选择
很多团队的实际路径是:先用托管收银台或 AI 集成完成第一版,再逐步演进到 API / SDK 深度集成。
一次完整集成通常包含什么
大多数 Waffo Pancake 集成都会包含四部分:- 身份认证:为服务端调用准备 Merchant ID 和 API Key
- 产品与收银台:创建一次性商品或订阅商品,并生成收银台入口
- 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 事件驱动业务状态变化
- 哪些能力只在测试环境验证,哪些要等到正式环境再开启
常用能力入口
身份认证
配置 Merchant ID、API Key 和服务端认证方式。
测试模式
使用测试环境和测试卡号验证完整链路。
Webhook
接收实时事件并同步订单、退款、订阅状态。
SDKs
查看官方 SDK、框架接入方式和代码示例。
AI 集成
用 AI 编码助手完成方案设计、代码生成和联调。
快速入门
从第一笔支付开始,快速理解完整接入路径。
开发者设置
API 与开发页面提供将 Waffo Pancake 与您的应用程序集成的工具。
API 密钥
概述
API 密钥用于验证您对 Waffo Pancake API 的请求。测试环境密钥
- 创建时选择测试环境
- 用于开发和测试
- 无真实收费
生产环境密钥
- 创建时选择生产环境
- 用于真实支付
- 私钥必须保密
密钥类型
API 密钥认证
API Key 认证由 SDK 自动处理。安装
@waffo/pancake-ts 后,只需提供 Merchant ID 和私钥,SDK 会自动完成请求签名。创建 API 密钥
API 密钥用于安全的服务端认证:1
导航到开发者
前往控制台 → API 与开发 → API 密钥
2
点击'创建 API 密钥'
API 密钥生成器打开
3
生成密钥对
点击”生成”创建密钥对
- 公钥发送到服务器
- 私钥由您保管
4
命名您的密钥
给它一个描述性名称(例如,“生产服务器”)
5
选择环境
选择测试或生产环境
6
下载私钥
重要: 下载并安全存储您的私钥
管理密钥
Webhooks
什么是 Webhooks?
Webhooks 在 Waffo Pancake 中发生事件时通知您的服务器。可用事件
设置 Webhooks
1
添加端点
输入您的 webhook URL(必须是 HTTPS)
2
选择事件
选择要接收的事件
3
获取签名密钥
复制 webhook 签名密钥
4
验证签名
在您的代码中实现签名验证
Webhook 负载示例
签名验证
验证 webhook 真实性:Webhook 最佳实践
快速响应
快速响应
在 5 秒内返回 2xx 状态。异步处理重型工作。
处理重复
处理重复
事件可能会多次发送。使用事件 ID 进行去重。
重试逻辑
重试逻辑
失败的 webhooks 最多重试 5 次,采用指数退避。
监控失败
监控失败
为 webhook 投递失败设置告警。
API 文档
基础 URL
认证
使用 SDK 进行 API 密钥认证(服务器间通信):常用端点
速率限制
当被限流时,您将收到
429 响应和 Retry-After 头。
安全最佳实践
环境变量
将密钥存储在环境变量中,切勿在代码中。
密钥轮换
定期轮换密钥,特别是在团队变动后。
IP 限制
限制密钥仅用于已知 IP 地址。
最小权限
仅创建具有所需权限的密钥。
测试
测试模式
使用测试模式进行开发:- 所有端点工作方式相同
- 不处理真实收费
- 可用测试卡号
- 完整的 webhook 测试
测试卡
日志和调试
API 日志
查看最近的 API 请求:- 请求方法和端点
- 响应状态
- 时间戳
- 请求/响应体
Webhook 日志
跟踪 webhook 投递:- 事件类型
- 投递状态
- 收到的响应
- 重试次数