> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Creem

> 中国大陆的支付 Provider —— 支付宝和微信支付，API 风格类 Stripe。

如果你卖给中国大陆用户，Creem 是首选。Stripe 没法正经接支付宝和微信支付，Creem 可以。它的 API 设计上有意贴近 Stripe，所以
Vibestrap 里的 Creem Provider 跟 Stripe Provider 几乎一行行对应 —— 换个 SDK
和 env 就行。

如果你的买家在中国（或者要把海外产品扩展到中国市场又不想搞两套代码），就用
Creem。

## 前置条件

* 一个 Creem 账号（[creem.io](https://creem.io)）。生产模式需要中国公司主体
  （营业执照）和 KYC。Sandbox / test 模式不要求。
* 绑定的支付宝和/或微信支付商户号。Creem 注册流程会带你走绑定步骤。
* Postgres 跑起来，schema 已 push。

## 1. 选定当前 Provider

`src/config/site.ts`：

```ts theme={null}
payment: {
  provider: 'creem' as 'stripe' | 'creem' | 'nowpayments',
  currency: 'usd', // 或 'cny' —— 见下面常见坑
},
```

接支付宝 / 微信支付的话基本一定要 `currency: 'cny'`，因为这两条通道天然是
人民币。混其他币种就得加一层换汇。

## 2. 在 Creem 建商品

Creem dashboard，**Products → New product**。每个商品有个 ID，下单时作为
`priceId` 传入。Creem 不像 Stripe 把 product 和 price 拆开 —— 一个 product
就是一个价格。

Vibestrap 本体需要建一个 `promo` 商品和一个 `standard` 商品。

## 3. 配环境变量

`.env.local`（变量名严格对齐 `src/env.ts`）：

```bash theme={null}
CREEM_API_KEY=creem_sk_...
CREEM_WEBHOOK_SECRET=自己想的签名密钥

# Vibestrap 本体的商品 ID
CREEM_PRICE_VIBESTRAP_PROMO=prod_...
CREEM_PRICE_VIBESTRAP_STANDARD=prod_...
```

`CREEM_PRICE_*` 命名上跟其他 Provider 对齐叫 `PRICE`，但底层装的是 Creem 的
product ID。

## 4. 配 webhook

Creem dashboard，**Developers → Webhooks → New endpoint**：

* **URL**：`https://your-domain.com/api/webhooks/creem`
* **Events**（至少订阅）：`checkout.completed`、`payment.succeeded`、
  `subscription.created`、`subscription.updated`、`subscription.canceled`。
* **签名密钥**：自己挑一个长随机串，同时贴到这里和环境变量
  `CREEM_WEBHOOK_SECRET`。Creem 用 HMAC-SHA256 签原始 body。

本地联调用 cloudflared 或 frpc 把 `localhost:3000` 暴露出去（在国内 cloudflared
通常比 ngrok 快）。

## 验证

1. 在 dashboard 里切到 test 模式。
2. `pnpm dev`，打开 `/pricing`，点结账 —— Creem 托管页打开。
3. 用 Creem 给的测试方式（sandbox 支付宝或微信）支付。
4. 看终端 webhook 日志。
5. 查数据库：
   ```sql theme={null}
   select id, provider, scene, status, amount, currency from payment
   where provider = 'creem'
   order by created_at desc limit 1;
   ```

## 常见坑

* **生产必须 KYC** —— Creem 上线生产商户号需要中国公司主体和 ICP 备案。
  Sandbox 不需要，但正式上线得先过 KYC，留几周时间。
* **支付宝 / 微信必须 CNY** —— 支付宝和微信支付是人民币原生通道。如果你设
  `currency: 'usd'` 又走这两条，Creem 要么直接拒，要么换汇并加价。把
  `siteConfig.payment.currency` 设成 `'cny'`，价格按分计（1 元 = 100 分），
  跟 cents 一样的逻辑。
* **Customer portal 不接受 returnUrl** —— `creem.customers.generateBillingLinks`
  不收 `returnUrl`，用户得通过你 app 的导航条回去。
* **Webhook 密钥是你自己填的** —— Creem 不替你生成
  签名密钥，自己 `openssl rand -hex 32`。
* **海外基建对国内出口** —— 如果你部署在 Vercel / Cloudflare 但客户在国内，
  支付跳转没问题，但服务端那条调 `creem.checkouts.create` 的路径从西方边缘
  节点出去会比较慢。考虑把这几条路由部署到亚洲节点。

## 官方文档

* Creem 文档：[creem.io/docs](https://creem.io/docs)
* API 参考：[creem.io/docs/api](https://creem.io/docs/api)
* Webhooks 指南：[creem.io/docs/webhooks](https://creem.io/docs/webhooks)
* 支付宝（上游）：[docs.open.alipay.com](https://docs.open.alipay.com)
* 微信支付（上游）：[pay.weixin.qq.com/docs](https://pay.weixin.qq.com/docs/)