如何在 Stripe 中实现“先付款后升级”的订阅计划变更-Python教程-PHP中文网

如何在 Stripe 中实现“先付款后升级”的订阅计划变更

本文详解如何绕过 stripe 客户门户，通过服务端控制实现安全、原子化的订阅升级流程：先生成并收取一次性发票，待支付成功后再更新订阅项，确保用户付费完成才生效新计划。

本文详解如何绕过 stripe 客户门户，通过服务端控制实现安全、原子化的订阅升级流程：先生成并收取一次性发票，待支付成功后再更新订阅项，确保用户付费完成才生效新计划。

在 Stripe 中直接调用 Subscription.modify() 并设置 collection_method="send_invoice" 会立即创建待支付发票，但不会阻塞订阅变更——即：订阅状态可能提前切换（如 current_period_end 更新），而用户尚未付款。这违背了“先付款、后升级”的业务要求，存在服务越权提供和财务对账风险。

正确做法是将升级流程拆分为两个幂等、可验证、事件驱动的步骤：

✅ 步骤一：创建并触发一次性发票（One-off Invoice）

不修改订阅本身，而是为差额（或全额新周期费用）创建独立发票，并强制立即结算：

import stripe
from datetime import timedelta

# 假设已获取 customer_id, subscription_id, new_price_id
# 1. 计算升级差额（示例：prorated + new plan首期费）
invoice_items = [
    {
        "customer": customer_id,
        "price": new_price_id,
        "quantity": 1,
        "description": "Upgrade to Premium Plan (prorated)",
    }
]

# 2. 创建草稿发票并立即最终化（自动尝试支付）
invoice = stripe.Invoice.create(
    customer=customer_id,
    collection_method="charge_automatically",  # 关键：自动扣款，非 manual
    days_until_due=None,  # 不设账期，立即处理
    auto_advance=True,
    statement_descriptor="Upgrade Fee",
    # 可选：附加折扣抵扣历史已付金额
    # coupon="promo_abc123"
)

# 3. 尝试支付该发票（同步阻塞，返回 PaymentIntent）
pi = stripe.Invoice.pay(invoice.id, expand=["payment_intent"])

if pi.payment_intent.status == "succeeded":
    print("✅ 一次性发票支付成功，可安全升级订阅")
else:
    raise Exception(f"❌ 发票支付失败: {pi.payment_intent.status}")

⚠️ 注意事项：

必须使用 collection_method="charge_automatically" + Invoice.pay()，而非 send_invoice，才能确保支付完成后再推进流程；

Invoice.pay() 返回的 PaymentIntent 状态需显式校验（如 "succeeded" 或 "requires_action"），前端应处理 3D Secure 流程；

若需支持部分退款或抵扣，建议在创建发票前先查询客户余额（Customer.balance）或发放一次性 coupon。

✅ 步骤二：支付成功后，原子化更新订阅

仅当上一步支付确认成功，才执行订阅变更，且禁用 proration 以避免重复计费（因差额已在发票中结清）：

# 支付确认后，安全升级订阅
updated_sub = stripe.Subscription.modify(
    subscription_id,
    items=[
        {
            "id": existing_item_id,  # 原订阅项 ID（需提前查询）
            "price": new_price_id,
        }
    ],
    proration_behavior="create_prorations",  # 或 "none"，取决于是否需生成调整项
    # 关键：不设置 cancel_at / trial_end，避免时间逻辑冲突
    # 所有周期变更由发票支付结果驱动
    payment_behavior="allow_incomplete",  # 允许后续失败重试
)