开发者设置
开发者页面提供将 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 测试
测试卡
| 卡号 | 行为 |
|---|---|
| 4242 4242 4242 4242 | 成功 |
| 4000 0000 0000 0002 | 被拒 |
| 4000 0000 0000 9995 | 余额不足 |
日志和调试
API 日志
查看最近的 API 请求:- 请求方法和端点
- 响应状态
- 时间戳
- 请求/响应体
Webhook 日志
跟踪 webhook 投递:- 事件类型
- 投递状态
- 收到的响应
- 重试次数