tinyship-payment

TinyShip 支付集成

TinyShip 支付服务商设置指南。

选择服务商

询问用户的目标市场，以便推荐服务商：

市场	推荐服务商	订阅支持
中国	WeChat Pay、Alipay	仅支持一次性付款和积分
全球	Stripe	完整支持（一次性付款、定期付款、积分）
全球（便于入驻）	Creem	完整支持（一次性付款、定期付款、积分）
全球（备选）	PayPal	完整支持（一次性付款、定期付款、积分）
全球（MoR/免税）	Dodo Payments	完整支持（名义商户服务）
全球（MoR/免税）	Waffo Pancake	完整支持（名义商户服务；订阅不支持 CNY）

按服务商设置

请阅读相应的参考文件，了解详细步骤：

• references/stripe-setup.md — Stripe（全球市场推荐）
• references/wechat-pay-setup.md — WeChat Pay
• references/alipay-setup.md — Alipay
• references/paypal-setup.md — PayPal

对于 Creem、Dodo Payments 和 Waffo Pancake，请阅读 TinyShip 仓库中的 docs/user-guide/payment/creem.md、 docs/user-guide/payment/dodo.md 和 docs/user-guide/payment/waffo.md。

请注意 Waffo 的以下事项：API 密钥在创建时会绑定到 Test 或 Production（没有 TEST_MODE 开关）；Webhook 验证使用 RSA 公钥（SDK 内置了 Test/Prod 密钥）；每个方案都需要一个 waffoProductId（PROD_xxx）。

配置定价方案

设置好服务商后，可以通过两种方式配置方案：

选项 A：静态方案（默认）

直接在 config/payment.ts 中定义方案：

plans: {
  monthly: {
    provider: 'stripe',           // must match your configured provider
    id: 'monthly',
    amount: 10,
    currency: 'USD',
    duration: { months: 1, type: 'recurring' },
    stripePriceId: 'price_xxx',   // provider-specific ID (required for Stripe)
    i18n: {
      'en': {
        name: 'Monthly Plan',
        description: 'Full access for one month',
        duration: 'month',
        features: ['All features', 'Priority support']
      },
      'zh-CN': {
        name: '月度订阅',
        description: '一个月完整访问',
        duration: '月',
        features: ['所有功能', '优先支持']
      }
    }
  }
}

方案会自动显示在 /pricing 页面上。

选项 B：动态定价（由管理员管理）

在 .env 中设置 PRICING_MODE="dynamic" 以启用。方案随后会存储在数据库中，并通过 /admin/pricing 管理面板进行管理——无需修改代码或重新部署，即可随时调整价格。

新项目的架构中已包含 pricing_plan 表，因此常规数据库初始化即可创建该表。从旧版本升级的项目必须先添加该表：

pnpm db:push          # PostgreSQL
pnpm db:push:sqlite   # SQLite / D1

动态定价支持：

• 在管理界面中创建、编辑和重新排序方案
• 使用 Markdown 格式的功能列表
• 划线价（原价）
• 按区域设置显示方案
• 一键将现有静态方案导入数据库

迁移现有静态方案：启用动态模式，打开 /admin/pricing，点击“Import from Config”，验证每个方案的服务商 ID，然后进行一次测试付款。随时可以通过设置 PRICING_MODE="static" 并重启来切回静态模式——动态方案数据会保留。

完整详情请参阅 TinyShip 仓库中的 docs/user-guide/payment/dynamic-pricing.md。

方案类型

类型	duration.type	服务商
一次性付款	one_time	全部
订阅	recurring	Stripe、Creem、PayPal、Dodo、Waffo
积分包	credits	全部（设置 duration.credits: 100）

Webhook 设置（本地开发）

支付服务商需要向你的应用发送 Webhook。本地开发时：

1. 安装隧道工具：

# Option A: ngrok
ngrok http 7001

# Option B: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:7001

2. 将隧道 URL 用作 Webhook 端点
3. 在服务商控制面板中配置 Webhook URL

Webhook 端点为：{BASE_URL}/api/payment/webhook/{provider} （例如，/api/payment/webhook/stripe）

积分系统（可选）

如需启用 AI 积分消耗功能，请配置 config/credits.ts：

credits: {
  consumptionMode: 'dynamic',          // 'fixed' or 'dynamic'
  fixedChatCost: 10,                   // credits per chat (fixed mode)
  dynamicChatCostPerKiloToken: 1,      // credits per 1K tokens (dynamic mode)
  modelMultipliers: {
    'qwen3.7-flash': 1.0,
    'gpt-5.6-sol': 2.0,
    'default': 1.0
  }
}

在订阅方案旁添加一个积分购买方案：

credits100: {
  provider: 'stripe',
  id: 'credits100',
  amount: 10,
  currency: 'USD',
  duration: { type: 'credits', credits: 100 },
  stripePriceId: 'price_xxx',
  i18n: { /* ... */ }
}

验证

1. 启动开发服务器
2. 访问 /pricing——应显示各方案
3. 点击一个方案并完成测试付款（使用沙盒/测试模式）
4. 检查 /dashboard——应显示订单
5. 对于订阅，验证 /api/subscription/status 是否返回有效状态

TinyShip 仓库中的参考文件

• config/payment.ts — 支付服务提供商和套餐配置
• config/credits.ts — 积分系统配置
• libs/payment/AGENTS.md — 支付库架构
• libs/credits/AGENTS.md — 积分系统架构
• docs/user-guide/payment/overview.md — 支付文档索引
• docs/user-guide/payment/waffo.md — Waffo Pancake 设置（MoR、托管结账）
• docs/user-guide/payment/dynamic-pricing.md — 动态定价管理指南
• docs/user-guide/payment-testing.md — 测试和 webhook 调试指南