创建收银台会话

✨ 利用 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。successUrl 原样使用，不替换任何占位符；要在成功页识别这笔购买，请在创建会话前把自己的标识（如内部订单号）写进 successUrl 的查询参数，并以 Webhook 为准确认付款。

预填客户邮箱

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

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

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

按受众定制收银台

默认情况下，托管收银台是为全球受众配置的：开放该货币支持的全部支付方式、跟随买家浏览器语言、表单留空。面向全球销售时这是合理的默认值。但如果你的买家大多来自同一个市场，就应该收窄——买家只看到自己天天在用的那一种钱包、界面是母语、邮箱已经填好，犹豫和流失都会少得多。收银台会话上有四个参数控制这件事，全部可选、互不依赖：

维度	参数	作用
货币	`currency`	决定哪些支付方式可能出现——见支付方式与币种对应表
语言	`language`	收银台默认界面语言（BCP 47，如 `zh-Hans`、`ja-JP`、`ko-KR`），买家仍可在页面上切换
支付方式	`includePaymentMethods` / `excludePaymentMethods`	白名单只开放买家认识的方式，或黑名单屏蔽你不想要的方式。两者最多传一个
邮箱	`buyerEmail`	预填邮箱，已登录的买家不用再纠结「该填哪个邮箱」

做法

用买家实际付款的货币定价。 决定收银台能开放哪些支付方式的是货币，不是买家所在地。选货币前先看对应表。
把 language 设成买家的语言。 买家分布在多个市场时可以不传，浏览器语言检测已经能处理。
把支付方式收窄到该市场在用的。 单一市场用 includePaymentMethods，只列买家认识的方式；多个市场更适合 excludePaymentMethods——该货币本就不支持的取值会被忽略，同一份黑名单可跨货币复用。
买家已登录时一律预填 buyerEmail。 买家在你这里已经有账号，再让他填一次邮箱只会引出犹豫（「要不要和注册邮箱保持一致？」）。走已认证收银台时把 buyerIdentity 和 buyerEmail 一起传。
除非需要预填税务信息，不要传 billingDetail。 传了会把收银台锁定到该国的支付市场，买家无法切换。

示例

中国大陆

买家用微信支付、读简体中文。微信支付适用于以 CNY 或 USD 定价的一次性产品，单笔上限约 ¥1,000（≈ $140）。

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "CNY",
  language: "zh-Hans",
  includePaymentMethods: ["wechat"],
  buyerEmail: user.email,
  successUrl: "https://yoursite.com/success?session_id={SESSION_ID}",
});

订阅产品不能用微信支付，所以订阅场景下去掉 includePaymentMethods，让买家用卡支付。

日本

买家习惯 JPY 定价和日文界面。卡和各钱包都支持 JPY，没有需要收窄的——设好货币和语言，支付方式保持默认即可。

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "JPY",
  language: "ja-JP",
  buyerEmail: user.email,
});

多个市场

在请求时根据你已有的信号——账号所在国家、界面语言、买家选择的套餐——按买家挑配置。推断不出来的就不传，让收银台回落到默认行为。

const MARKETS = {
  CN: { currency: "CNY", language: "zh-Hans", includePaymentMethods: ["wechat"] },
  JP: { currency: "JPY", language: "ja-JP" },
  DEFAULT: { currency: "USD" },
} as const;

const market = MARKETS[user.country as keyof typeof MARKETS] ?? MARKETS.DEFAULT;

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  ...market,
  buyerEmail: user.email,
});

支付方式筛选需要 API Key 认证。 includePaymentMethods 和 excludePaymentMethods 在 Store Slug 会话和 link 模式按钮上会被静默忽略——开放哪些支付方式是商户侧的商业决策（费率、结算），只能在服务端决定。language 和 buyerEmail 在两种模式下都有效。

includePaymentMethods 里的每个取值都必须被你传入的「产品类型 × 货币」支持，否则请求会以 400 Payment methods not supported 失败。某种方式也可能在单笔订单上被隐藏——例如微信支付超过单笔上限——所以只开放一种方式时，确保定价落在它的限额内。

使用 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 存储在收银台会话上，并在 Webhook 负载的 orderMetadata 字段中传回。商户凭证（API Key）不能用 GraphQL 查询 checkoutSession。

订阅试用

为订阅产品启用试用期：

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

按座位数量功能尚未通过 API 支持。一次性商品、新购订阅与更换方案可传 couponId 应用优惠券、传 promotionCode 预填码，或传 allowPromotionCodes: true 显示输码框 —— 见优惠与促销。

订阅预填账单信息

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

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}",
});

successUrl 会原样跳转，不会替换 {SESSION_ID} 之类的占位符。请自己把需要的标识拼进 URL，并以 Webhook 为准确认付款。

完整示例：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 负载的 `orderMetadata` 字段中传回
`withTrial`	boolean	否	为订阅产品启用试用期
`language`	string	否	收银台默认界面语言（BCP 47 枚举，如 `zh-Hans`、`ja-JP`），买家可切换
`includePaymentMethods`	string[]	否	开放的支付方式白名单（如 `card`、`applepay`、`googlepay`、`wechat`，以平台登记的取值为准）；仅 API Key
`excludePaymentMethods`	string[]	否	隐藏的支付方式黑名单，与白名单互斥；仅 API Key
`billingDetail`	object	否	预填账单国家/州/邮编用于计税；会把收银台锁定到该国支付市场
`darkMode`	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 升级流程

参数参考

下一步