Stripe Terminal集成报错：PaymentIntent处于requires_payment_method状态无法捕获

按照Stripe Terminal手动捕获支付的官方流程操作，调用paymentIntents.capture时触发StripeInvalidRequestError，提示PaymentIntent处于requires_payment_method状态，无法执行捕获操作。

具体操作流程及响应： #

步骤1：创建PaymentIntent

stripe.paymentIntents.create({
    currency: 'usd',
    payment_method_types: ['card_present'],
    capture_method: 'manual',
    amount: 1000,
})

响应：创建成功，状态为requires_payment_method

步骤2：调用读卡器处理PaymentIntent

stripe.terminal.readers.processPaymentIntent({
    reader_id: '你的读卡器ID',
    payment_intent: '你的PaymentIntent ID'
})

响应：调用成功，状态为in_progress

步骤3：查询读卡器状态

stripe.terminal.readers.retrieve('你的读卡器ID');

响应：查询成功，状态为in_progress

步骤4：查询PaymentIntent状态

stripe.paymentIntents.retrieve('你的PaymentIntent ID');

响应：查询成功，状态仍为requires_payment_method

步骤5：尝试捕获PaymentIntent

stripe.paymentIntents.capture('你的PaymentIntent ID')

响应：触发错误，状态为requires_payment_method

错误信息：This PaymentIntent could not be captured because it has a status of requires_payment_method. Only a PaymentIntent with one of the following statuses may be captured: requires_capture.

问题原因及解决方案 #

核心原因

调用processPaymentIntent后，读卡器处于in_progress状态说明支付流程未完成——用户尚未在终端完成刷卡/插卡、输入密码等操作，PaymentIntent不会自动进入requires_capture状态，此时调用捕获接口必然触发状态错误。

正确流程修正

1. 等待终端支付流程结束：调用processPaymentIntent后，需通过以下方式确认支付完成：

   • 轮询（测试场景）：持续调用stripe.terminal.readers.retrieve，直到读卡器状态变为idle
   • Webhook（生产环境）：监听terminal.reader.action_succeeded事件，该事件会在终端完成支付操作后触发

2. 确认PaymentIntent状态：只有当PaymentIntent状态变为requires_capture时，才能调用paymentIntents.capture接口。若支付失败，PaymentIntent会回到requires_payment_method状态，需排查终端操作或支付卡问题。

3. 轮询方式代码示例：

async function waitForPaymentCompletion(readerId, paymentIntentId) {
    while (true) {
        const reader = await stripe.terminal.readers.retrieve(readerId);
        if (reader.status === 'idle') {
            const paymentIntent = await stripe.paymentIntents.retrieve(paymentIntentId);
            if (paymentIntent.status === 'requires_capture') {
                const capturedIntent = await stripe.paymentIntents.capture(paymentIntentId);
                console.log('捕获成功：', capturedIntent);
                break;
            } else {
                console.log('支付失败，当前状态：', paymentIntent.status);
                break;
            }
        }
        // 间隔1秒轮询一次
        await new Promise(resolve => setTimeout(resolve, 1000));
    }
}

// 步骤2调用后执行该函数
waitForPaymentCompletion('你的读卡器ID', '你的PaymentIntent ID');

注意事项

• 禁止在终端支付流程未完成时提前调用捕获接口，违反Stripe状态机逻辑
• 生产环境优先使用Webhook，轮询仅适合快速测试
• 确保读卡器已正确连接，且用户完成所有终端支付操作

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