本技能聚焦游戏侧支付逻辑,即“卖什么、何时发放、何时收回”,客户端初始化、Checkout Sessions 与 Stripe API 本身则指向 stripe-docs 技能或官方文档。
主要决策
- 全部支付逻辑在服务端运行,客户端永不发送价格、数量或权益。
- 先销售高级货币,再由玩家用其购买道具,这样调价无需新建 Stripe 产品。
- 只从 Webhook 发放,玩家可能永远不会加载成功页。
- 发放与记录 Stripe 事件 ID 在同一数据库事务内完成,崩溃时两者都不留,由 Stripe 重试。
- 订阅周期按发票只发放一次;因为 checkout.session.completed 与 invoice.paid 都可能指向首张发票,所以发放以发票 ID 唯一。
- 全额退款或争议会撤销一次性购买所发放的内容,最多扣至零余额;已花费货币的玩家转人工处理差额。部分退款,或订阅支付上的退款与争议,也转人工,因为订阅周期发放以发票而非支付意图为键。
使用步骤
- 执行 bun add stripe,不要传 apiVersion。
- 在 templates/product-catalog.ts 定义商品目录,产品 ID 由 Checkout metadata 携带。
- 服务端创建 Checkout Session:一次性购买设置 metadata: { playerId, productId },订阅设置 subscription_data: { metadata: { playerId } };创建调用带幂等键,避免重试产生第二个会话。
- 按 postgres-game-schema 技能添加 processed_events 表(event id 主键、kind、created_at),作为与 bullmq-game-queues 共享的幂等表;购买与订阅周期表需各自唯一键:一次性发放用 checkout session id,订阅周期用 invoice id。
- 用 boilerplate/webhooks.ts 接入 Webhook 端点,针对上述表实现 PaymentStore 与 PaymentTx,在路由中调用 handleStripeWebhook(rawBody, signatureHeader, { stripe, webhookSecret, store }) 并返回其结果。
- grantCurrency 保持简短:写购买行并用 bullmq-game-queues 技能入队发放奖励,Stripe 需要先收到 2xx。
- 参照 templates/webhook-events.ts 设计支付审计日志,记录每个已处理事件的玩家、产品、金额与状态。
- 订阅 HANDLED_EVENT_TYPES 中的事件:checkout.session.completed、checkout.session.async_payment_succeeded、checkout.session.async_payment_failed、invoice.paid、customer.subscription.updated、customer.subscription.deleted、charge.refunded、charge.dispute.created。
各事件处理要点
- checkout.session.completed:payment 模式下,除非 payment_status 为 unpaid 否则发放;subscription 模式下取订阅、存状态,active 时按 session.invoice 发放周期。
- checkout.session.async_payment_succeeded:处理方式同 completed,银行扣款等延迟方式会落到这里。
- checkout.session.async_payment_failed:标记待审核以便通知玩家。
- invoice.paid:先确认 invoice.parent?.type === 'subscription_details',再从 parent.subscription_details.subscription 取订阅 ID,仅在订阅 active 时按该发票发放。
- customer.subscription.updated / deleted:重新拉取订阅并存储当前状态,而非事件中的状态。
- charge.refunded:仅全额退款时按支付意图撤销;部分退款或无匹配发放则标记审核。
- charge.dispute.created:按 dispute.payment_intent 撤销并标记账户,此时资金已从余额划走。
常见坑点
- Bun 上需用 await stripe.webhooks.constructEventAsync(...),因为 Bun 加载 SDK 的 Web 构建、其 crypto 仅异步,constructEvent 会抛错。
- 必须对收到的原始请求体验签,先解析 JSON 会破坏签名。
- 仅按事件 ID 去重不够:同一对象可能有不同事件,同一会话可能先 completed 后 async_payment_succeeded,需靠购买行唯一键阻止二次发放。
- 内存 Set 重启即失且不跨实例共享,应使用数据库表。
- 事件会乱序到达,不要用 created 排序;webhooks.ts 拉取订阅并存储 Stripe 当前返回的状态,且 setSubscription 不会把行移出终态(canceled、incomplete_expired)。
- 当前 API 版本已无 invoice.subscription,需用上述 parent 路径。
- 撤销必须幂等,重复事件与同一支付的不同事件都可能多次触发。
- 玩家已花掉货币时,由游戏规则决定撤销行为:扣剩余并记账、移除道具或锁定账户;不能出现负余额,postgres-game-schema 对货币有 CHECK (amount >= 0);撤销不可抛错,否则 Stripe 会重试最长三天。
- 缺少 playerId metadata 属创建会话的 bug,应标记而非抛错。
- 按玩家限制购买频率,并开启 Radar 防欺诈。
相关文件:templates/product-catalog.ts、boilerplate/webhooks.ts、templates/webhook-events.ts、references/sources.md。相关技能:postgres-game-schema、betterauth-integration、bullmq-game-queues、game-economy-design。