创建收银台会话

创建收银台会话，锁定商品版本、定价和货币。这是一次性商品和订阅商品收银台流程的第一步。典型流程为：

商户在服务端创建收银台会话
将 checkoutUrl 返回给前端
Customer 点击链接进入托管收银台页面
Customer 填写账单信息、预览税费并完成订单

POST /v1/actions/checkout/create-session

认证方式： API Key 或 Store Slug

请求体（API Key）

字段	类型	必需	说明
`productId`	string	是	商品 ID（Short ID 格式 `PROD_xxx`）
`currency`	string	是	ISO 4217 货币代码（例如 `USD`、`EUR`、`JPY`）
`priceSnapshot`	object	否	在会话创建时覆盖定价（仅 API Key，见下方）
`withTrial`	boolean	否	启用试用期（仅订阅商品）
`buyerEmail`	string	否	在收银台页面预填 customer 邮箱
`billingDetail`	object	否	预填账单详情（见下方）
`successUrl`	string	否	覆盖支付成功后的跳转 URL
`expiresInSeconds`	number	否	会话 TTL（秒）（默认 `2700` = 45 分钟，仅 API Key）
`darkMode`	boolean	否	启用收银台页面暗色模式
`metadata`	object	否	附加到会话的自定义键值对
`orderMerchantExternalId`	string	否	商户业务侧订单编号（最大 128 字符）
`language`	string	否	收银台语言（IETF BCP 47），必须是受支持的枚举值之一：en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY。设置收银台页面默认语言，消费者可在页面自行切换
`includePaymentMethods` / `excludePaymentMethods`	string[]	否	二选一，互斥。include 是白名单：只开放这些（`card`、`applepay`、`googlepay`、`wechat`），每个取值都必须被「产品类型 × 货币」组合支持。exclude 是黑名单：开放该货币支持的全部方式但排除这些，该货币本就不支持的取值会被忽略，因此同一份黑名单可跨货币复用。两者都不传则开放该货币支持的全部方式

请求体（Store Slug）

字段	类型	必需	说明
`productId`	string	是	商品 ID（Short ID 格式 `PROD_xxx`）
`currency`	string	是	ISO 4217 货币代码
`buyerEmail`	string	否	预填 customer 邮箱
`billingDetail`	object	否	预填账单详情（见下方）
`successUrl`	string	否	覆盖支付成功后的跳转 URL
`darkMode`	boolean	否	启用收银台页面暗色模式
`language`	string	否	收银台语言（IETF BCP 47），必须是受支持的枚举值之一：en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY。设置收银台页面默认语言，消费者可在页面自行切换

Store Slug 认证不支持 priceSnapshot、expiresInSeconds、metadata、orderMerchantExternalId、withTrial、includePaymentMethods 和 excludePaymentMethods。这些字段会被静默忽略，以防止客户端篡改价格和操纵会话。支付方式属于商户侧的商业决策（渠道费率、结算周期），浏览器不得收窄或放宽——Store Slug 创建的 session 一律开放该货币支持的全部方式。

ID 命名约定：同一组扁平双 key 名（checkout 端的 orderMerchantExternalId、退款工单端的 refundTicketMerchantExternalId）贯穿请求体、webhook 载荷以及承载这些值的每个 GraphQL 类型 — 在 checkout 创建时写入的值可在 Order、Payment、Refund 及 webhook 载荷中以相同的字段名读回。

价格快照对象

字段	类型	必需	说明
`amount`	string	是	显示格式的价格字符串（例如 “29.00” = $29.00）
`taxIncluded`	boolean	否	金额是否已包含税费（默认 `false`）
`taxCategory`	string	是	用于税率计算的税务类别（例如 `saas`、`digital_goods`）

账单详情对象

字段	类型	必需	说明
`country`	string	是	ISO 3166-1 alpha-2 国家代码（例如 `US`、`JP`、`DE`）
`isBusiness`	boolean	是	是否为企业购买
`postcode`	string	否	邮政编码
`state`	string	否	州/省代码（例如 `CA`、`NY`、`ON`）。某个账单国家是否需要该字段，由 `preview-tax` 端点返回的 `rules.requiredFields` 给出
`businessName`	string	否	企业法定名称。与 `isBusiness: true` 一起提供，即可显示在发票上
`taxId`	string	否	税务登记号，例如欧盟 VAT 号码。某个账单国家是否需要该字段，由 `preview-tax` 端点返回的 `rules.requiredFields` 给出

传入 billingDetail 会把收银台与订单的账单国家挂钩：收银台只提供该国家所属市场的支付方式，买家无法切换市场。起作用的是订单最终的账单国家，而非你传入的值；账单国家不在我们覆盖的支付市场内时不产生限制。启用前请对照店铺开放的支付方式 —— 若挂钩后的市场不提供其中任何一种，该笔订单将无法支付。不传 billingDetail 则收银台不受限制，这是默认行为。

会话锁定

创建收银台会话时，以下值被锁定，在会话有效期内无法更改： productVersionId、productName、priceInfo、storeName、billingPeriod、withTrial、theme、buyerEmail、billingDetail 邮箱规范化：所有邮箱字段（email / buyerEmail / contactEmail）在服务端会被规范化（trim().toLowerCase()）后再用于存储、cache、下游调用。Foo@Bar.COM 与 foo@bar.com 视为同一账户。

请求示例

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_7J3K5L8M2N4P6Q9R",
  currency: "USD",
  buyerEmail: "customer@example.com",
  language: "en",
  successUrl: "https://example.com/thank-you",
});

console.log(session.sessionId);   // "cs_550e8400-e29b-41d4-a716-446655440000"
console.log(session.checkoutUrl); // "https://checkout.waffo.ai/..."
console.log(session.expiresAt);   // "2026-01-22T10:30:00.000Z"

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_2D5F8G3H1K4M6N9P" \
  -H "X-Timestamp: 1711800000" \
  -H "X-Signature: BASE64_RSA_SIGNATURE" \
  -d '{
    "productId": "PROD_7J3K5L8M2N4P6Q9R",
    "currency": "USD",
    "buyerEmail": "customer@example.com",
    "language": "en",
    "successUrl": "https://example.com/thank-you"
  }'

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

import requests

response = requests.post(
    "https://api.waffo.ai/v1/actions/checkout/create-session",
    headers={
        "Content-Type": "application/json",
        "X-Merchant-Id": "MER_2D5F8G3H1K4M6N9P",
        "X-Timestamp": "1711800000",
        "X-Signature": "BASE64_RSA_SIGNATURE",
    },
    json={
        "productId": "PROD_7J3K5L8M2N4P6Q9R",
        "currency": "USD",
        "buyerEmail": "customer@example.com",
        "language": "en",
    },
)

data = response.json()["data"]
print(data["checkoutUrl"])

成功响应 (200)

{
  "data": {
    "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "checkoutUrl": "https://checkout.waffo.ai/my-store-abc123/checkout/cs_550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-22T10:30:00.000Z"
  }
}

响应字段

字段	类型	说明
`sessionId`	string	收银台会话 ID（`cs_` + UUID 格式，不是 Short ID）
`checkoutUrl`	string	将 customer 重定向到托管收银台页面的完整 URL
`expiresAt`	string	会话过期的 ISO 8601 时间戳

错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。

状态码	`errors[0].message`	含义	推荐处理
400	`Missing or invalid header: x-context-environment`	environment 请求头缺失或不是 `test` / `prod`	修正请求头后重发
400	`Invalid JSON body`	请求体不是合法 JSON	修正请求体后重发
400	`Missing required fields: productId, currency`	`productId` 或 `currency` 缺失	修正请求体后重发
400	`Invalid currency format: "X". Must be 3 uppercase letters (e.g., "USD", "EUR", "JPY")`	货币代码不是 3 位大写字母（ISO 4217）	使用合法 ISO 4217 代码后重发
400	`Invalid language, must be one of: en, pt-BR, … ms-MY`	`language` 不在受支持的收银台语言枚举内	使用受支持的 `language`，或省略该字段
400	`includePaymentMethods and excludePaymentMethods are mutually exclusive`	两个名单同时传入	只传其中一个
400	`Invalid includePaymentMethods, must be one of: card, applepay, googlepay, wechat`	含枚举外的取值	使用受支持的取值，或省略该字段
400	`Currency X is not supported for onetime payments`	货币不在支付方式矩阵内（一次性：USD、EUR、GBP、HKD、JPY、CNY；订阅：USD、EUR、GBP、HKD、JPY）	改用受支持的货币
400	`Payment methods not supported for X (onetime): wechat`	`includePaymentMethods` 要求的方式在该「产品类型 × 货币」下不可用	去掉不支持的方式
400	`No payment method remains for X (onetime) after applying excludePaymentMethods`	黑名单把可用方式排除干净了	少排除一些方式
400	`Expected format: PROD_xxx, got "..."`	`productId` Short ID 解码失败	修正 `productId` 格式后重发
400	`orderMerchantExternalId must not be empty`	字段已传但 trim 后为空	不传该字段或传入非空值
400	`orderMerchantExternalId must be at most 128 characters`	值超过 128 字符	缩短到 128 字符以内
400	`Currency X is not supported for this product`	产品在请求的货币下无 price snapshot	使用产品支持的货币
401	`Unauthorized`	API Key 签名无效或 Store Slug 无法识别	检查认证请求头
403	`Store is not active`	门店状态非 `active`	先激活门店
403	`Store is not accepting payments`	`prod` 环境下，平台未为该门店开启收款开关（`payin_enable`）	平台侧开关 —— 联系 Waffo 支持
403	`Store is not approved for production payments`	`prod` 环境下，门店未通过生产环境审批（`prod_enabled`，即 KYB 审核）	使用 `test` 环境，或完成 KYB 审核
403	`Product does not belong to this store`	产品不属于当前访问的门店	验证产品/门店配对
404	`Store not found`	没有匹配的 slug	验证 slug 和 environment
404	`Product not found`	产品不存在	验证 `productId`
404	`Product not found or not active for this environment`	该 environment 下产品无 active 版本	为此环境激活产品版本
500	`Internal server error`	服务端意外失败	指数退避重试（起步 5s，最多 3 次）

payin_enable 与 prod_enabled 是两个相互独立的条件：payin_enable 是平台侧控制的收款开关，prod_enabled 是生产环境审批（KYB）闸门。在 prod 环境下，任一条件单独不满足即返回 403。两者在 test 环境均不适用。

默认会话 TTL 为 45 分钟（2700 秒）。使用 API Key 认证时，可通过 expiresInSeconds 自定义。会话在创建时锁定商品版本和定价，因此价格变更不会影响已有会话。

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

请求体（API Key）

请求体（Store Slug）

价格快照对象

账单详情对象

会话锁定

请求示例

成功响应 (200)

响应字段

错误响应

​请求体（API Key）

​请求体（Store Slug）

​价格快照对象

​账单详情对象

​会话锁定

​请求示例

​成功响应 (200)

​响应字段

​错误响应

请求体（API Key）

请求体（Store Slug）

价格快照对象

账单详情对象

会话锁定

请求示例

成功响应 (200)

响应字段

错误响应