先选接入路径
AI 集成
最快落地适合已有代码仓库,希望借助 Claude Code 等编码代理完成方案设计、接口接入和联调验证的团队。
API / SDK
最可控适合需要自定义收银台流程、服务端编排、动态定价或对集成行为有更精细控制的场景。
托管收银台
最简单适合先快速上线支付链接,后续再逐步深化集成的团队。
如何选择
很多团队的实际路径是:先用托管收银台或 AI 集成完成第一版,再随着需求增长逐步演进到 API / SDK 深度集成。
一次完整集成通常包含什么
大多数 Waffo Pancake 集成都会包含四部分:- 身份认证:用于服务端请求
- 产品与收银台:用于一次性或订阅计费
- 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 创建收银台会话,或直接使用仪表盘生成的收银台链接。
5
处理 Webhook
设置 Webhook 端点,处理支付、退款和订阅事件。
6
端到端测试
使用测试模式和测试卡号验证完整流程。
7
上线
发布商品并切换到生产环境。
实施前准备
在写代码前,先明确这几项:- 你卖的是一次性商品、订阅,还是两者组合
- 是否需要动态定价,例如超额用量、充值包、按报价收费
- 成功支付后,系统需要授予什么访问权限、资格或资源
- 你希望通过哪些 Webhook 事件驱动业务状态变化
- 哪些能力要留在测试模式,直到正式上线才开启
常用能力入口
身份认证
配置 Merchant ID、API Key 和服务端认证方式。
测试模式
在无真实扣款的情况下测试完整集成流程。
Webhook
接收实时事件并保持订单和订阅同步。
SDKs
查看官方 SDK、框架接入模式和代码示例。
AI 集成
用 AI 编码助手完成方案设计、代码实现和验证。
快速入门
从第一笔支付开始,快速理解完整接入路径。
开发者设置
API 与开发页面提供将 Waffo Pancake 与您的应用程序集成的工具。API 密钥
概述
API 密钥用于验证对 Waffo Pancake API 的服务器间请求。测试密钥
- 为
test环境创建 - 用于开发
- 无真实收费
- 与生产数据隔离
正式密钥
- 为
prod环境创建 - 用于生产环境
- 处理真实支付
- 私钥必须妥善保管
密钥类型
API 密钥认证
API Key 认证由 SDK 自动处理。安装
@waffo/pancake-ts 后,只需提供 Merchant ID 和私钥,SDK 会自动完成请求签名。创建 API 密钥
1
导航到 API 与开发
前往仪表盘 —> API 与开发 —> API 密钥
2
点击'创建 API 密钥'
API 密钥生成器打开。
3
生成密钥对
点击”生成”创建密钥对。
- 公钥发送到服务器
- 私钥由您保管
4
命名您的密钥
给它一个描述性名称(例如,“生产服务器”)。
5
选择环境
选择测试或生产环境。
6
下载私钥
重要: 下载并安全存储您的私钥。
管理密钥
Webhooks
什么是 Webhooks?
Webhooks 在 Waffo Pancake 中发生事件时通知您的服务器。可用事件
设置 Webhooks
1
添加端点
输入您的 webhook URL(必须是 HTTPS)。
2
选择事件
选择要接收的事件。
3
保存配置
保存您的 webhook 端点。
Webhook 负载示例
所有 ID 均为 UUID v4 格式。金额以最小货币单位表示。时间戳为 ISO 8601 UTC。
Webhook 最佳实践
快速响应
快速响应
在 30 秒内返回 2xx 状态。异步处理重型工作。
处理重复
处理重复
事件可能会多次发送。使用事件 ID 进行去重。
重试逻辑
重试逻辑
失败的 webhooks 最多重试 5 次,延迟递增(5 分钟、30 分钟、2 小时、24 小时)。
监控失败
监控失败
在仪表盘中检查 webhook 投递日志以排查失败。
API 文档
基础 URL
架构
Waffo Pancake 使用混合 API:- REST (POST):所有写操作通过
/v1/actions/... - GraphQL:所有读操作通过
/v1/graphql
认证示例
使用 SDK 进行 API 密钥认证(服务器间通信):常用端点
完整 API 参考
完整的端点文档,含请求/响应示例。
安全最佳实践
环境变量
将私钥存储在环境变量中,切勿写在代码中。
密钥轮换
定期轮换密钥,特别是在团队变动后。
密钥隔离
为测试和生产环境使用不同的 API 密钥。
安全存储
使用您平台的密钥管理服务存储私钥。
测试
测试模式
使用测试模式进行开发:- 所有端点工作方式相同
- 不处理真实收费
- 可用测试卡号
- 完整的 webhook 测试
测试卡
日志和调试
Webhook 日志
跟踪 webhook 投递:- 事件类型
- 投递状态(成功/失败)
- 您的端点返回的 HTTP 响应
- 重试次数和时间戳