TinyShip Payment Integration 是 TinyShip 的支付服务商配置指南。
用途
该技能用于在 TinyShip 项目中设置支付服务商，并配置定价计划、Webhook 和可选的积分系统，适用于需要为应用接入支付能力的开发场景。
服务商选择
技能建议先询问用户的目标市场以推荐服务商。按资料中的对照关系：中国大陆市场推荐微信支付、支付宝，仅支持一次性支付加积分；全球市场推荐 Stripe，支持一次性、订阅和积分完整功能；全球市场且希望简化接入可选用 Creem；全球市场备选为 PayPal；Dodo Payments 和 Waffo Pancake 为 Merchant of Record 模式。Waffo Pancake 在订阅场景下不支持人民币。
按服务商的设置
技能引用了各服务商对应的参考文件：Stripe 对应 references/stripe-setup.md，微信支付对应 references/wechat-pay-setup.md，支付宝对应 references/alipay-setup.md，PayPal 对应 references/paypal-setup.md。Creem、Dodo Payments 和 Waffo Pancake 需从 TinyShip 仓库读取 docs/user-guide/payment/creem.md、dodo.md 和 waffo.md。Waffo 的特殊点包括：API 密钥在创建时即绑定 Test 或 Production，没有 TEST_MODE 开关；Webhook 验证使用 RSA 公钥（SDK 内置 Test/Prod 密钥）；每个计划需要 waffoProductId（PROD_xxx）。
配置定价计划
设置服务商后可通过两种方式配置计划。方式 A 为静态计划（默认），在 config/payment.ts 中直接定义，包含 provider、id、amount、currency、duration、provider 专属 ID（如 Stripe 必需 stripePriceId）以及多语言 i18n 信息（名称、描述、时长、功能列表）。计划会自动出现在 /pricing 页面。方式 B 为动态定价（管理员管理），在 .env 中设置 PRICING_MODE="dynamic" 启用，计划存储于数据库并通过 /admin/pricing 管理，价格可随时调整而无需改代码或重新部署。新项目 schema 已包含 pricing_plan 表，从旧版本升级的项目需先执行 pnpm db:push（PostgreSQL）或 pnpm db:push:sqlite（SQLite/D1）。动态定价新增能力包括：在管理界面创建/编辑/排序计划、Markdown 格式功能列表、划线原价、基于语言环境的计划可见性、一键导入现有静态计划。迁移静态计划的方式为：启用动态模式，打开 /admin/pricing，点击 "Import from Config"，核对各计划的 provider ID，然后进行测试支付；可随时设回 PRICING_MODE="static" 并重启切回，动态计划数据会保留。
计划类型
按 duration.type 区分：一次性（one_time）适用于所有服务商；订阅（recurring）适用于 Stripe、Creem、PayPal、Dodo、Waffo；积分包（credits）适用于所有服务商，需设置 duration.credits: 100。
Webhook 设置（本地开发）
支付服务商需要向应用发送 Webhook。本地开发可安装隧道工具：ngrok 使用 ngrok http 7001，或 Cloudflare Tunnel 使用 cloudflared tunnel --url http://localhost:7001。使用隧道 URL 作为 Webhook 端点，并在服务商控制台配置 Webhook URL。Webhook 端点地址为 {BASE_URL}/api/payment/webhook/{provider}，例如 /api/payment/webhook/stripe。
积分系统（可选）
如需启用 AI 积分消耗，配置 config/credits.ts，包含 consumptionMode（'fixed' 或 'dynamic'）、fixedChatCost、dynamicChatCostPerKiloToken 以及 modelMultipliers（按模型设置倍率）。可同时添加积分购买计划，使用 duration: { type: 'credits', credits: 100 } 并配置 provider 专属 ID。
验证
验证流程为：启动开发服务器；访问 /pricing 确认计划显示；点击计划并使用沙箱/测试模式完成测试支付；检查 /dashboard 确认订单出现；订阅场景下验证 /api/subscription/status 返回 active 状态。
TinyShip 仓库中的参考文件
包括 config/payment.ts（支付服务商与计划配置）、config/credits.ts（积分系统配置）、libs/payment/AGENTS.md（支付库架构）、libs/credits/AGENTS.md（积分系统架构）、docs/user-guide/payment/overview.md（支付文档索引）、waffo.md（Waffo Pancake 设置）、dynamic-pricing.md（动态定价管理指南）、payment-testing.md（测试与 Webhook 调试指南）。