Stripe支付意图手动捕获详解

为什么选择手动捕获？

在某些业务场景下，立即扣款可能不符合需求。例如：

• 订单预留与库存确认： 用户提交订单后，商家可能需要时间确认库存、检查订单详情，或进行人工审核，在此期间仅需预授权资金，待确认无误后再实际扣款。
• 服务交付延迟： 对于需要一定准备时间或分阶段交付的服务，可以在服务开始前授权，服务完成后再捕获资金。
• 风险管理： 对于高风险交易，可以先授权资金，待人工审核通过后才进行捕获，以减少欺诈损失。
• 酒店/租车预订： 在客户预订时授权一笔费用，待客户入住/取车后或离店/还车时再进行实际扣款。

手动捕获为这些场景提供了解决方案，将支付流程分解为“授权”和“捕获”两个独立步骤，从而提供更大的控制权。

实现 Stripe 手动捕获的步骤

要实现 Stripe 的手动捕获功能，主要涉及以下两个核心步骤：创建 PaymentIntent 时指定手动捕获模式，以及在适当时候执行捕获操作。

1. 创建 PaymentIntent 并指定手动捕获

在创建 PaymentIntent 对象时，需要将 capture_method 参数设置为 'manual'。这将指示 Stripe 在完成支付流程后仅授权资金，而不是立即从客户账户中扣除。

示例代码 (Node.js):

const stripe = require('stripe')('YOUR_STRIPE_SECRET_KEY'); // 替换为您的Stripe密钥

async function createManualPaymentIntent(amountInCents, currencyCode, customerId = null) {
  try {
    const paymentIntent = await stripe.paymentIntents.create({
      amount: amountInCents, // 金额，以最小货币单位表示（例如，美元为美分）
      currency: currencyCode, // 货币代码，例如 'usd'
      customer: customerId, // 可选：关联客户ID
      payment_method_types: ['card'], // 支付方式类型，例如银行卡
      capture_method: 'manual', // 关键：设置为手动捕获
      confirm: true, // 自动确认 PaymentIntent
      description: '订单预授权', // 描述信息
      // 其他可选参数，如 metadata, receipt_email 等
    });

    console.log(`PaymentIntent ID: ${paymentIntent.id} 已创建，状态为: ${paymentIntent.status}`);
    // 当 confirm: true 时，如果支付成功，状态通常会是 'requires_capture'
    return paymentIntent;
  } catch (error) {
    console.error('创建 PaymentIntent 失败:', error.message);
    throw error;
  }
}

// 示例调用 (假设授权 $10.00 美元)
// createManualPaymentIntent(1000, 'usd')
//   .then(pi => console.log('手动捕获 PaymentIntent 创建成功。'))
//   .catch(err => console.error('手动捕获 PaymentIntent 创建失败。'));

当客户完成支付流程（例如，通过 Stripe Elements 输入卡信息并提交）后，如果 PaymentIntent 的 confirm 属性设置为 true，Stripe 会自动尝试授权这笔支付。如果授权成功，PaymentIntent 的状态将变为 requires_capture，表示资金已被预留，等待您的后续捕获指令。

2. 捕获 PaymentIntent

在您决定实际扣款时（例如，在 5 分钟后、订单发货后或人工审核通过后），您需要调用 Stripe API 的捕获端点来完成资金的捕获。

示例代码 (Node.js):

const stripe = require('stripe')('YOUR_STRIPE_SECRET_KEY'); // 替换为您的Stripe密钥

async function captureAuthorizedPayment(paymentIntentId) {
  try {
    const capturedPaymentIntent = await stripe.paymentIntents.capture(
      paymentIntentId
    );

    console.log(`PaymentIntent ID: ${capturedPaymentIntent.id} 已捕获，状态为: ${capturedPaymentIntent.status}`);
    // 成功捕获后，状态将变为 'succeeded'
    return capturedPaymentIntent;
  } catch (error) {
    console.error('捕获 PaymentIntent 失败:', error.message);
    throw error;
  }
}

// 示例调用 (假设在一段时间后捕获之前创建的 PaymentIntent)
// 假设之前创建的 paymentIntentId 为 'pi_xxxxxxxxxxxxxx'
// captureAuthorizedPayment('pi_xxxxxxxxxxxxxx')
//   .then(pi => console.log('支付已成功捕获。'))
//   .catch(err => console.error('支付捕获失败。'));

在实际应用中，您可能会将 captureAuthorizedPayment 函数集成到您的后端逻辑中，例如：

• 通过定时任务（如 CRON job）在预设时间后触发。
• 通过 Webhook 监听订单状态变化，当订单状态变为“已发货”时触发。
• 通过管理后台的手动操作触发。

注意事项

• 授权有效期： Stripe 的支付授权通常在 7 天内有效。如果超过 7 天未进行捕获，授权将自动失效，您将无法再捕获这笔资金。
• 全额捕获： 使用 paymentIntent.capture() 方法通常会捕获 PaymentIntent 中授权的全部金额。如果需要进行部分捕获，Stripe 提供了更高级的 API 功能，但通常不通过简单的 capture() 调用实现。对于大多数延迟扣款场景，全额捕获是常见的做法。
• 幂等性： 对捕获操作进行幂等性处理非常重要，以防止因网络问题等导致重复捕获。Stripe API 通常会处理请求的幂等性，但在您的应用层面也应确保逻辑的健壮性。
• 错误处理： 在创建和捕获 PaymentIntent 的过程中，务必实现完善的错误处理机制，例如处理授权失败、捕获失败等情况，并向用户提供清晰的反馈。
• Webhooks： 强烈建议使用 Stripe Webhooks 来监听 payment_intent.succeeded、payment_intent.payment_failed、payment_intent.canceled 等事件，以便您的系统能够实时响应支付状态的变化，而不仅仅依赖 API 调用的返回值。特别是对于手动捕获，监听 payment_intent.requires_capture 状态变化可以帮助您跟踪哪些支付意图等待捕获。

总结

Stripe 的手动捕获功能为需要延迟支付处理的业务场景提供了强大的灵活性和控制力。通过将支付流程分解为授权和捕获两个阶段，商家可以更好地管理资金流转时机，优化用户体验，并应对复杂的业务需求。理解并正确实施 capture_method: 'manual' 和 paymentIntents.capture() 是构建健壮且灵活的 Stripe 支付解决方案的关键。