Skip to main content

先选接入路径

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 事件驱动业务状态变化
  • 哪些能力要留在测试模式,直到正式上线才开启
如果这些决策还没完全想清楚,优先走 AI 集成路径;如果这些规则已经很清晰,API / SDK 路径通常是更好的选择。

常用能力入口

身份认证

配置 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

下载私钥

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

管理密钥

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 响应
  • 重试次数和时间戳