创建收银台会话

✨ 利用 AI 安装

将此提示复制到你的 AI 代码编辑器（Cursor、Copilot 等）中，即可创建收银台集成：

Add Waffo Pancake checkout to my project using the official TypeScript SDK.

npm install @waffo/pancake-ts

Create a WaffoPancake client with WAFFO_MERCHANT_ID and WAFFO_PRIVATE_KEY.
Use client.checkout.createSession({ productId, currency: "USD" })
to get a checkoutUrl, then redirect the user with res.redirect(checkoutUrl).

For webhooks, use verifyWebhook(rawBody, signature) from the SDK — it has embedded public keys,
no secret needed. Handle events: order.completed, subscription.activated, subscription.canceled.

Read https://waffo.mintlify.app/llms-full.txt for full API reference.

你将构建什么

收银台会话是一个动态生成的支付页面。相比分享静态的产品链接，你可以：

预填客户邮箱
使用自定义 metadata 追踪订单
设置自定义成功 URL
为订阅产品启用试用期

前置条件

Waffo Pancake 账户
API 密钥（Dashboard → API 与开发）
至少创建一个产品

基础收银台会话

最简单的收银台会话需要产品 ID 和货币。

使用 TypeScript SDK（推荐）

npm install @waffo/pancake-ts

import { WaffoPancake } from "@waffo/pancake-ts";

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

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
});

// 将用户重定向到收银台页面
res.redirect(session.checkoutUrl);

直接使用 REST API

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: your-store-slug" \
  -H "X-Environment: test" \
  -d '{
    "productId": "your-product-uuid",
    "currency": "USD"
  }'

import requests

response = requests.post(
    'https://api.waffo.ai/v1/actions/checkout/create-session',
    headers={
        'Content-Type': 'application/json',
        'X-Store-Slug': 'your-store-slug',
        'X-Environment': 'test',
    },
    json={
        'productId': 'your-product-uuid',
        'currency': 'USD',
    }
)

checkout_url = response.json()['data']['checkoutUrl']
# 将客户重定向到 checkout_url

响应：

{
  "data": {
    "sessionId": "cs_xxx",
    "checkoutUrl": "https://checkout.waffo.ai/your-store/checkout/cs_xxx",
    "expiresAt": "2024-01-22T12:00:00Z"
  }
}

将客户重定向到 checkoutUrl 完成支付。

重定向最佳实践

不要使用 window.open() 打开收银台页面。 Safari 和许多移动端浏览器会拦截在异步回调中（例如 API 调用之后）打开的弹出窗口。这会导致客户的收银台流程静默失败。

推荐方式：

方式	使用场景	示例
服务端重定向	API 路由 / 服务端操作	`res.redirect(checkoutUrl)`
客户端重定向	SPA / React	`window.location.href = checkoutUrl`
链接元素	静态链接	`<a href={checkoutUrl}>`

// ✅ 推荐：服务端重定向
export async function POST(req: NextRequest) {
  const session = await client.checkout.createSession({ ... });
  return NextResponse.redirect(session.checkoutUrl);
}

// ✅ 也可以：客户端重定向
const { checkoutUrl } = await res.json();
window.location.href = checkoutUrl;

// ❌ 避免：window.open — 会被 Safari 和移动端浏览器拦截
window.open(checkoutUrl, "_blank"); // 会被拦截！

支付完成后，客户会被重定向回你的 successUrl。使用 {SESSION_ID} 占位符即可在成功页面验证付款。

预填客户邮箱

通过预填邮箱跳过邮箱输入步骤：

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  buyerEmail: "user@example.com",
});

使用场景： 用户已登录你的应用，你已知道他们的邮箱。

使用 Metadata 追踪

将收银台会话与你的内部系统关联：

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  metadata: {
    user_id: "usr_abc123",
    campaign: "black_friday_2024",
    referrer: "twitter",
  },
  successUrl: "https://yoursite.com/success",
});

Metadata 存储在收银台会话上，可通过 checkoutSession GraphQL 查询获取。Webhook 负载中传回 metadata 功能即将上线。

订阅试用

为订阅产品启用试用期：

const session = await client.checkout.createSession({
  productId: "prod_subscription",
  currency: "USD",
  withTrial: true,
  successUrl: "https://yoursite.com/welcome",
});

优惠码和按座位数量功能尚未通过 API 支持。请通过 Dashboard 管理折扣。

订阅预填账单信息

为税费计算预填消费者的账单信息：

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  billingDetail: {
    country: "US",
    isBusiness: false,
    state: "CA",
    postcode: "94105",
  },
});

动态成功 URL

将数据传递到成功页面：

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  successUrl: "https://yoursite.com/success?session_id={SESSION_ID}",
});

{SESSION_ID} 会被替换为实际的会话 ID，这样你可以在成功页面验证付款。

完整示例：SaaS 升级流程

这是一个使用 SDK 升级用户订阅的真实示例：

// app/api/upgrade/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import { WaffoPancake } from "@waffo/pancake-ts";

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

export async function POST(req: NextRequest) {
  const { userId, planId, email } = await req.json();

  const session = await client.checkout.createSession({
    productId: planId,
    currency: "USD",
    buyerEmail: email,
    metadata: { user_id: userId, action: "upgrade" },
    successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true`,
  });

  // 服务端重定向 — 兼容所有浏览器
  return NextResponse.redirect(session.checkoutUrl);
}

如果你需要在客户端处理收银台（例如 SPA）：

async function handleUpgrade(planId: string) {
  const res = await fetch("/api/upgrade", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userId: currentUser.id, planId, email: currentUser.email }),
  });
  const { checkoutUrl } = await res.json();

  // 在当前标签页跳转 — 兼容 Safari
  window.location.href = checkoutUrl;
}

参数参考

参数	类型	必填	描述
`productId`	string	是	Dashboard 中的产品 UUID
`currency`	string	是	ISO 4217 货币代码（如 `"USD"`）
`buyerEmail`	string	否	预填消费者邮箱
`successUrl`	string	否	自定义成功重定向 URL
`metadata`	object	否	自定义键值数据，存储在会话上（Webhook 传回即将上线）
`withTrial`	boolean	否	为订阅产品启用试用期

Get Started

Features

Merchant

Store

Merchant of Record

你将构建什么

前置条件

基础收银台会话

使用 TypeScript SDK（推荐）

直接使用 REST API

重定向最佳实践

预填客户邮箱

使用 Metadata 追踪

订阅试用

订阅预填账单信息

动态成功 URL

完整示例：SaaS 升级流程

参数参考

下一步

处理 Webhooks

验证支付

​你将构建什么

​前置条件

​基础收银台会话

​使用 TypeScript SDK（推荐）

​直接使用 REST API

​重定向最佳实践

​预填客户邮箱

​使用 Metadata 追踪

​订阅试用

​订阅预填账单信息

​动态成功 URL

​完整示例：SaaS 升级流程

​参数参考

​下一步

处理 Webhooks

验证支付

你将构建什么

前置条件

基础收银台会话

使用 TypeScript SDK（推荐）

直接使用 REST API

重定向最佳实践

预填客户邮箱

使用 Metadata 追踪

订阅试用

订阅预填账单信息

动态成功 URL

完整示例：SaaS 升级流程

参数参考

下一步