支付失败后如何将Stripe月付订阅转为单次支付？求最佳实践

核心问题原因 #

Stripe 的 incomplete 订阅状态属于临时状态，仅用于等待初始支付完成。处于该状态的订阅仅允许修改 metadata、default_payment_method 这类不触发新发票/计费项的属性，无法通过修改 line item 生成新的计费请求——这就是你遇到报错的根本原因。

分场景解决方案 #

1. 订阅处于 incomplete（首次支付失败）

• 优先引导完成初始发票支付：通过 Stripe Dashboard 或 API 获取该订阅关联的未付发票，生成支付链接/页面让客户完成支付。支付成功后订阅会自动转为 active 状态，之后再处理一次性支付剩余费用的需求。
• 若客户直接要求全额支付：
  1. 先取消原 incomplete 订阅：

     Stripe::Subscription.cancel('sub_XXXXXX')
     

  2. 直接创建一次性收费（无需新订阅）：用 PaymentIntent 收取全额 120 美元，或创建对应一次性价格的新订阅完成支付即可。

2. 订阅处于 active 但后续支付失败（如第 2/12 次）

此时订阅通常处于 past_due 状态，可通过以下方式处理：

• 生成一次性发票收取剩余费用：创建针对该客户的发票，添加对应剩余未付周期的自定义费用（比如剩余 10 个月则添加 100 美元），发送给客户支付。支付完成后，可将原订阅设置为 cancel_at_period_end 避免后续扣费，或直接取消订阅。
  示例代码：

  # 创建一次性发票
  invoice = Stripe::Invoice.create({
    customer: 'cus_XXXXXX',
    collection_method: 'send_invoice',
    days_until_due: 0,
    lines: [
      {
        price_data: {
          currency: 'usd',
          unit_amount: 10000, # 100 美元（10*10）
          product: 'prod_XXXXXX', # 关联原订阅产品
          type: 'one_time'
        }
      }
    ]
  })
  # 发送发票给客户
  Stripe::Invoice.send_invoice(invoice.id)
  

• 创建支付链接简化支付流程：生成对应剩余金额的一次性价格，创建支付链接分享给客户，支付完成后手动调整原订阅状态即可。

最佳实践 #

• 监听支付失败事件：通过 Webhook 监听 invoice.payment_failed，第一时间通知客户并提供重新支付未付发票的选项，尽量让订阅回到 active 状态后再操作。
• 避免在 incomplete 状态下修改计费：该状态是临时状态，核心目标是完成初始支付，不要尝试修改计费项。
• 优先使用发票/一次性收费而非修改订阅：这种方式更灵活，不会破坏原订阅的计费逻辑，也能满足客户一次性支付的需求。

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