朋友，可能你看到这篇文章的时候和我写的时候相隔很久，文章中所说可能已经不是对应官网的最新信息，需要你将文章发给AI让其确认是否还可行后再去做，感谢理解

Waffo Pancake 接入指南

附上 Waffo.ai 哥飞专属注册优惠
国内个人身份的朋友注册 Waffo，用哥飞邀请码：https://waffo.ai/?ref=GEFEI01
1000 USD 交易免手续费（2027 年 3 月 31 日前有效）
审核绿色通道，1 个工作日内完成初审或反馈
社群专人客服，有问题随时问
有海外公司的，注册 https://waffo.com
信息截至 2026 年 10 月，各平台政策常变，以官方为准

本指南介绍如何在 GPT Image 2 中配置与使用 Waffo Pancake 处理一次性点数购买与循环订阅支付。

Waffo Pancake 是一家 Merchant of Record（MoR，记录商） 平台，以法定卖家身份处理全球税务计算、代收、合规与跨境结算。

GPT Image 2 采用官方 @waffo/pancake-ts SDK，集成 Waffo 托管结账收银台与消费者门户，卡片敏感信息完全不经过您的服务器。

GPT Image 2 将所有 Waffo 配置统一收敛至管理后台（Admin Settings）在线可视化管理，无需在 .env 中维护繁琐的环境变量，并支持测试与生产环境即时切换。

订阅为什么没有人民币币种：

提现：顾客付款后,这笔钱进入店铺余额,等待约 10 个工作日,期间用于覆盖可能发生的退款或拒付。工作日按香港公众假期计算,遇长假实际日历天数会超过两周

！！！注意：提现手续费 1%，最低收费 $10（minimum payout fee），不是最低提现金额 $10

一、前置准备与账号设置

GPT Image 2 默认内置一次性积分包 credits-package 与订阅计划（按月 starter-monthly、按年 premium-yearly），按照以下步骤完成开通与配置：

1. 创建 Waffo 账户

在 Waffo Pancake 控制台 注册商户账户，并在引导流程中创建一个商店。参考 Waffo 快速入门。

2. 获取 API 密钥

从 Waffo 控制台获取 Merchant ID 与私钥：

1. 进入 Waffo 控制台 > API & Development，点击 Create API Key 生成密钥对。
2. 复制 Merchant ID（以 MER_ 开头）和完整的 PEM 格式私钥。
3. 妥善保存私钥。API 密钥在创建时即绑定至测试（Test）或生产（Production）环境，请为不同环境分别创建对应密钥。
   

注意：

• Merchant ID 为商户 ID（以 MER_ 开头），不是 storeId，也不是 URL 中的商店标识。
• 私钥必须包含完整头部与尾部（支持多行完整粘贴）：

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...
-----END PRIVATE KEY-----

3. 设置 Webhook

设置 Webhook 以接收异步履约通知：

1. 进入 Waffo 控制台 > Settings > Webhooks，点击 Add Webhook。
2. Payload 格式：选择 Raw（只有 Raw 格式会携带用于验签的 X-Waffo-Signature 请求头）。
3. Webhook URL 严格填写：

   https://YOUR-DOMAIN.com/api/payment/notify/waffo
   

4. 订阅事件：建议勾选以下核心事件：
   • order.completed（一次性点数购买完成）
   • subscription.activated（订阅首次激活）
   • subscription.payment_succeeded（订阅续费扣款成功）
   • subscription.renewed（订阅续订成功）
   • subscription.updated（订阅信息更新）
   • subscription.canceling（客户发起取消申请）
   • subscription.canceled（订阅正式终止）
   • refund.succeeded（退款完成）

说明：
与 Stripe 不同，Waffo 无需在后台单独配置 Webhook 密钥。@waffo/pancake-ts SDK 内置了官方公钥并根据当前环境自动识别，GPT Image 2 服务端通过 verifyWebhook() 验证签名与防范重放攻击。

4. 创建产品与价格计划

在 Waffo 中创建产品并获取 Product ID（以 PROD_ 开头）：

1. 进入 Waffo 控制台 > Products，点击 Create Product。
2. 对应 GPT Image 2 的方案创建以下产品：
   • 一次性点数包（credits-package）：
     • 产品类型：One-time
     • 名称：例如 500 Credits Package
     • 设置币种与金额（如 USD 10.99，或根据需要添加 CNY 69.99 币种支持）
     • 保存并复制产品 ID（PROD_...）
   • 入门版方案月付（starter-monthly）：
     • 产品类型：Subscription
     • 计费周期：Monthly
     • 设置币种与金额（如 USD 9.99 / 月）
     • 保存并复制产品 ID（PROD_...）
   • 高级版方案年付（premium-yearly）：
     • 产品类型：Subscription
     • 计费周期：Yearly
     • 设置币种与金额（如 USD 99.99 / 年）
     • 保存并复制产品 ID（PROD_...）

提示：如需支持中文收银台或不同非美金币种，可编辑产品并在 Pricing 设置中配置对应货币与本地化信息。

二、在管理后台完成配置

以管理员身份登录 GPT Image 2 后台，访问 系统设置 > 支付设置（/admin/settings，Payment 标签页）：

在 Waffo Pancake 分组下配置以下参数：

配置产品映射表（Product IDs Mapping）

GPT Image 2 的商品 ID 定义在 src/config/locale/messages/{zh,en}/pages/pricing.json 中（credits-package、starter-monthly、premium-yearly）。

在管理后台的 Waffo 产品 ID 映射 中填入合法的 JSON 映射：

{
  "credits-package": "PROD_xxx",
  "starter-monthly": "PROD_xxx",
  "premium-yearly": "PROD_xxx"
}

支持按币种差异化映射（可选）

如果同一商品在不同币种下对应不同 Waffo 产品，映射表支持 ${product_id}_${currency} 优先级匹配：

{
  "credits-package": "PROD_USD_xxx",
  "credits-package_CNY": "PROD_CNY_xxx",
  "starter-monthly": "PROD_MONTHLY_xxx",
  "premium-yearly": "PROD_YEARLY_xxx"
}

结账 API 会优先检索匹配当前币种的 key，找不到时自动回退到基础 product_id。

设为默认支付方式（可选）

如需将 Waffo 作为定价页面的首选支付通道，可在 Default Payment Provider 下拉框中选择 Waffo Pancake。

三、支付实现与运行机制

1. 认证收银台与语言自适应

• 买家身份绑定（Authenticated Checkout）：服务端发起结账时，自动将当前登录用户的 user.id 注入 buyerIdentity，并将 orderNo 作为商户外部订单号（orderMerchantExternalId）传递给 Waffo。
• 收银台语言自适应：系统根据用户当前站点的 locale 自动转换收银台语言（中文转为 zh-Hans，英文保持 en），保证支付体验无缝贴合。
• 页面回跳定向：一次性点数购买跳回 /settings/credits（积分明细页），循环订阅计划跳回 /settings/billing（账单与订阅页）。

2. 同步回跳轮询（保证即时到账与无公网调试）

当用户在 Waffo 收银台完成付款跳回 /api/payment/callback?order_no=... 时：

1. 服务端将商户订单号 orderNo 作为查询标识，直接调用 Waffo GraphQL API 检索交易状态：

   query ($ref: String!) {
     payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
       id
       status
       orderId
       snapshotAmountDetails { currency total }
       subscriptionOrder { ... }
     }
   }
   

2. 平滑轮询机制：Waffo 在跳转后可能需要短暂瞬间同步支付状态。若状态为 processing，服务端会自动以 1 秒间隔重试轮询至多 5 次。状态确认为成功后，立即完成订单标记并下发积分。
3. 这意味着即使本地没有公网 Webhook 隧道，测试支付也能在浏览器跳回瞬间完成权益发放！

3. Webhook 权威异步履约

线上运行依靠 /api/payment/notify/waffo 端点进行双重保障与订阅生命周期维护：

安全环境校验：
Webhook 负载携带 mode（test 或 prod），服务端会自动与管理后台当前配置的 waffo_environment 进行比对，环境不一致的请求将被自动拦截，防止测试事件污染生产数据库。

四、本地联调与生产上线

本地联调

1. 在管理后台将 waffo_environment 设为 test，填入测试环境的 Merchant ID 与 Private Key。
2. 配置好测试产品的 waffo_product_ids_mapping。
3. 访问 http://localhost:3000/pricing 发起购买。由于具备同步回跳轮询机制，可以直接完成结账跳回与点数充值测试。
4. 若需验证异步续订等长周期 Webhook，可通过隧道工具暴露本地端口：

   # 使用 cloudflared
   cloudflared tunnel --url http://localhost:3000
   

   并在 Waffo 控制台添加对应的 Webhook 地址（格式为 Raw）。

生产上线检查清单

1. 商户审核：完成 Waffo 商店审核 / KYB 认证，以启用真实资金清结算。
2. 发布产品：在 Waffo 控制台将产品从测试环境发布（Publish）至生产环境，获取生产环境下的 PROD_... ID。
3. 获取生产密钥：在 Waffo 控制台生成生产环境专用的 API 密钥。
4. 配置生产 Webhook：在 Waffo 控制台添加正式 Webhook：https://YOUR-DOMAIN.com/api/payment/notify/waffo，格式选择 Raw。
5. 更新管理后台配置：
   • 将 waffo_environment 切换为 production。
   • 填入生产环境的 Merchant ID 与 Private Key。
   • 更新 waffo_product_ids_mapping 为生产环境的产品 ID。

五、消费者客户门户

Waffo 提供官方托管的消费者门户：

https://pancake.waffo.ai/consumer/portal/login

用户使用结账时填写的邮箱，通过一次性邮箱验证码（Magic Link）直接免密登录。用户可在门户中：

• 查看活跃订阅、下次扣费时间与历史发票
• 自主取消或恢复订阅
• 下载官方税务发票与收据 PDF
• 更新绑定的信用卡信息

六、测试卡信息

在 Waffo 测试模式（Test）下，可以使用以下测试卡进行模拟支付：

在 Waffo 托管结账页面中，也可以直接点击 Quick Fill 下的 Success 按钮一键自动填充测试卡。