# Waffo 支付与授权服务器打通

依据官方文档：[AI Integration](https://docs.waffo.ai/zh/integrate/ai-integration)

## 正确闭环

```text
客户端 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-…`