跳转到主要内容

开发者设置

开发者页面提供将 Waffo Pancake 与您的应用程序集成的工具。
Developer API Keys

API 密钥

概述

API 密钥用于验证您对 Waffo Pancake API 的请求。

测试环境密钥

  • 创建时选择测试环境
  • 用于开发和测试
  • 无真实收费

生产环境密钥

  • 创建时选择生产环境
  • 用于真实支付
  • 私钥必须保密

密钥类型

密钥类型使用场景描述
API 密钥仅服务器端签名请求,完全 API 访问

API 密钥认证

API Key 认证由 SDK 自动处理。安装 @waffo/pancake-ts 后,只需提供 Merchant ID 和私钥,SDK 会自动完成请求签名。
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
切勿在客户端代码、版本控制或公共仓库中暴露您的私钥。

创建 API 密钥

API 密钥用于安全的服务端认证:
1

导航到开发者

前往控制台 → 开发者 → API 密钥
2

点击'创建 API 密钥'

API 密钥生成器打开
3

生成密钥对

点击”生成”创建密钥对
  • 公钥发送到服务器
  • 私钥由您保管
4

命名您的密钥

给它一个描述性名称(例如,“生产服务器”)
5

选择环境

选择测试或生产环境
6

下载私钥

重要: 下载并安全存储您的私钥
您的私钥只显示一次。请安全存储 - 您需要它进行 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

1

添加端点

输入您的 webhook URL(必须是 HTTPS)
2

选择事件

选择要接收的事件
3

获取签名密钥

复制 webhook 签名密钥
4

验证签名

在您的代码中实现签名验证

Webhook 负载示例

{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 9900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

签名验证

验证 webhook 真实性:
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Webhook 最佳实践

在 5 秒内返回 2xx 状态。异步处理重型工作。
事件可能会多次发送。使用事件 ID 进行去重。
失败的 webhooks 最多重试 5 次,采用指数退避。
为 webhook 投递失败设置告警。

API 文档

基础 URL

https://waffo-pancake-auth-service.vercel.app/v1

认证

使用 SDK 进行 API 密钥认证(服务器间通信):
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { store } = await client.stores.create({ name: "My Store" });

常用端点

端点方法描述
/v1/actions/onetime-product/create-productPOST创建一次性产品
/v1/actions/subscription-product/create-productPOST创建订阅
/v1/actions/onetime-order/create-orderPOST创建结账会话
/v1/graphqlPOST查询数据 (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 投递:
  • 事件类型
  • 投递状态
  • 收到的响应
  • 重试次数