首次集成Stripe Checkout一次性支付的技术问询

你的方案概述 #

你作为前端开发者首次集成Stripe支付实现应用内钱包余额充值，采用Stripe Checkout一次性支付，搭配Firebase Cloud Functions和Realtime Database，目标控制成本至零或最低，方案细节如下：

交易状态记录 #

支付历史页面需记录6种交易状态：

• Pending
• Success
• Failed
• Cancelled
• Expired
• Refunded

计划实现的Webhook（Firebase Cloud Functions） #

• checkout.sessions.completed：用户提交支付详情完成时，在实时数据库创建状态为pending的交易记录
• payment_intent.succeeded：更新交易状态为success，并调整钱包余额
• payment_intent.payment_failed：更新交易状态为failed
• payment_intent.canceled：更新交易状态为cancelled
• checkout.session.expired：更新交易状态为expired
• 退款相关Webhook：更新交易状态为refunded，并调整钱包余额

疑问解答 #

1. 是否需要阻止pending状态交易的用户发起新交易？ #

不需要强制阻止，但建议做友好提示而非硬限制：

• Stripe本身允许用户同时发起多个支付会话，但短时间内重复发起大概率是误操作，提示用户“已有待处理的充值请求，请稍后再试”能避免重复扣款风险
• 如果你的钱包逻辑允许多笔待处理交易（比如用户分批充值），完全可以不限制；但要避免余额计算混乱的话，可在前端校验用户状态，检测到pending交易时禁用充值按钮并给出提示

2. Cancelled与Expired的区别，以及支付意向7天后过期变为Cancelled的问题？ #

• Expired：特指Stripe Checkout会话在你设置的超时时间内（默认24小时）未被用户完成支付，触发checkout.session.expired事件，会话直接失效
• Cancelled：包含两种场景：
  1. 用户主动在Checkout页面点击取消按钮，放弃支付
  2. 支付意向（Payment Intent）超过7天未完成，Stripe会自动将其标记为canceled（这是Stripe的规则：所有Payment Intent默认7天后过期并转为取消状态）
     简单总结：Expired是Checkout会话层面的短时间超时，Cancelled是用户主动取消或Payment Intent层面的7天超期

3. 当前Webhook配置是否足够？有没有遗漏？ #

你的配置覆盖了核心场景，但有几个细节需要补充：

• 明确退款事件：要监听charge.refunded事件，而非泛称的“退款Webhook”，这个事件会在退款完成时触发，你可以通过关联的Payment Intent找到对应交易记录，调整余额
• 处理重复触发：Stripe会在网络异常时重复发送Webhook事件，你需要在Firebase Cloud Functions中做幂等性处理——比如记录已处理的事件ID，避免重复更新交易状态和余额
• 异步支付场景：如果用户使用银行转账这类异步支付方式，会触发checkout.session.async_payment_succeeded和checkout.session.async_payment_failed事件，需要补充处理来更新对应交易状态
• 关联关键ID：创建交易记录时，务必把Stripe的session_id、payment_intent_id存入数据库，后续Webhook事件可以通过这些ID关联到对应交易，避免状态更新错误

内容的提问来源于stack exchange，提问作者Moo33