Stripe CLI 触发 invoice.payment_failed 事件的正确方式

在使用 Stripe CLI 触发 invoice.payment_failed 事件时，开发者可能会遇到一个常见问题：当尝试通过 --override 参数指定 subscription 时，命令会失败并返回错误信息 "You may only specify one of these parameters: pending_invoice_items_behavior, subscription"。

问题背景

Stripe CLI 是一个强大的命令行工具，允许开发者在测试环境中模拟各种支付事件。invoice.payment_failed 是一个重要的事件，表示发票支付失败，通常用于测试订阅服务的支付失败处理逻辑。

错误原因分析

这个错误的核心在于 Stripe API 的参数互斥性。默认情况下，Stripe CLI 会设置 pending_invoice_items_behavior 参数为 include，而当开发者尝试通过 --override 指定 subscription 参数时，就违反了 API 的规则：这两个参数不能同时存在。

解决方案

正确的做法是在命令中添加 --remove 开关来移除默认的 pending_invoice_items_behavior 参数。完整的命令示例如下：

stripe trigger \
invoice.payment_failed \
--override \
invoice:customer=cus_123 \
--override \
invoice:subscription=sub_123 \
--override \
payment_method:customer=cus_123 \
--override \
invoiceitem:customer=cus_123 \
--remove \
invoice:pending_invoice_items_behavior

完整实现示例

以下是一个完整的 Node.js 实现示例，展示了如何创建必要的测试数据并生成正确的 CLI 命令：

const stripe = require('stripe')('sk_test_XXX');

async function setupTestEnvironment() {
  // 创建测试客户
  const customer = await stripe.customers.create({
    name: "测试用户",
    email: "[e-mail]"
  });

  // 创建支付方式并附加到客户
  const paymentMethod = await stripe.paymentMethods.create({
    type: "card",
    card: { token: "tok_visa" }
  });
  
  await stripe.paymentMethods.attach(paymentMethod.id, {
    customer: customer.id
  });

  // 设置默认支付方式
  await stripe.customers.update(customer.id, {
    invoice_settings: {
      default_payment_method: paymentMethod.id
    }
  });

  // 创建测试价格
  const price = await stripe.prices.create({
    currency: "usd",
    unit_amount: 1000,
    product_data: { name: "测试产品" },
    recurring: { interval: "month" }
  });

  // 创建测试订阅
  const subscription = await stripe.subscriptions.create({
    customer: customer.id,
    items: [{ price: price.id }]
  });

  // 生成正确的CLI命令
  const cliCommand = [
    "stripe trigger invoice.payment_failed",
    "--override invoice:customer=" + customer.id,
    "--override invoice:subscription=" + subscription.id,
    "--override payment_method:customer=" + customer.id,
    "--override invoiceitem:customer=" + customer.id,
    "--remove invoice:pending_invoice_items_behavior"
  ].join(" ");

  console.log("可执行的CLI命令:");
  console.log(cliCommand);
}

setupTestEnvironment();

最佳实践建议

1. 测试数据隔离：为每个测试场景创建独立的测试数据，避免测试间的相互影响。

2. 参数验证：在使用 Stripe CLI 时，仔细检查参数的互斥性，特别是当使用 --override 和 --remove 时。

3. 事件顺序：理解 Stripe 事件的生命周期，确保触发的事件顺序符合实际业务场景。

4. 错误处理：在自动化测试脚本中加入对 CLI 命令执行结果的检查，确保事件触发成功。

通过遵循这些指导原则，开发者可以更有效地使用 Stripe CLI 来测试支付失败场景，确保应用程序能够正确处理这类事件。