opsx-licence/docs/waffo-integration.md

Waffo 支付与授权服务器打通

依据官方文档：AI Integration

正确闭环

客户端 Checkout
  → opsx-licence 创建本地订单 ORD-…
  → API Key / Store Slug → POST https://api.waffo.ai/v1/actions/checkout/create-session
       orderMerchantExternalId=ORD-…, metadata, successUrl
  → 用户付款
  → Webhook POST /api/v1/webhooks/waffo（order.completed）
  → 按 orderMerchantExternalId 标记 paid 并发 License
  → successUrl / deep link 回客户端

不要只拼 pancake.waffo.ai/store/.../product/... 托管页：无法可靠写入 orderMerchantExternalId，会导致本地订单一直 pending。

管理端配置（推荐）

打开 支付 页（/payments），填写：

项	说明
商户 ID	MER_…（不是 Store ID）
Store ID / Store Slug	商店标识
环境	test / live
API 私钥	只写不回显；保存后点「测试连接」调用 POST /api/payment/waffo/debug
Product ID 映射表	plan_type（或自定义 key）→ Waffo product_id，可增删多行

配置优先读 DB，.env 仅兜底。Webhook 只读提示一般为：

https://你的域名/api/v1/webhooks/waffo（Raw JSON，事件至少 order.completed，尽量 HTTPS）。

.env 兜底变量

见仓库根目录 .env.example：WAFFO_MERCHANT_ID、WAFFO_PRIVATE_KEY / _BASE64、WAFFO_STORE_SLUG、WAFFO_PRODUCT_ID_*、SUCCESS_URL 等。

验收

1. 支付页「测试连接」成功（私钥已配置且签名可用）
2. Checkout 返回的 checkoutUrl 来自 session（含 /checkout/cs_…）
3. 付完后本地订单 paid 并自动有 License
4. Webhook 载荷含 data.orderMerchantExternalId = 本地 ORD-…