React-Stripe.js 中 Express Checkout 元素确认支付的最佳实践

在 Stripe 支付集成中，Express Checkout 元素提供了一种简化的支付流程。然而，开发者在实现过程中可能会遇到一些集成问题，特别是在处理支付确认环节时。本文将深入分析一个常见的集成错误，并提供解决方案。

问题现象

当开发者按照官方文档实现 Express Checkout 元素时，可能会遇到以下错误提示： "Element confirming payment is 'expressCheckout', but stripe.confirmPayment() was not called within the 'confirm' event"。

这个错误通常发生在以下情况：

1. 使用了 React 的 useCallback 钩子包装确认函数
2. 在 confirmPayment 方法中同时传入了 elements 参数和 confirmation_token 参数

根本原因分析

经过深入测试和验证，发现问题的核心在于：

1. 参数互斥性：confirmPayment 方法中的 elements 参数和 confirmation_token 参数实际上是互斥的。当使用 Express Checkout 元素时，应该只使用其中之一。

2. React 钩子影响：useCallback 钩子在某些情况下可能会影响事件处理函数的执行时机，导致 Stripe 无法正确识别确认事件。

解决方案

正确的实现方式

以下是经过验证的正确实现方案：

const handleConfirm = async (event) => {
  if (!stripe) return;

  // 创建确认令牌
  const { confirmationToken } = await stripe.createConfirmationToken({
    elements,
    params: {
      payment_method_data: {
        allow_redisplay: 'always',
      },
    },
  });

  // 获取支付意向客户端密钥
  const { clientSecret } = await createPaymentIntent({
    confirmationTokenId: confirmationToken.id,
    returnUrl: 'your_return_url',
  });

  // 确认支付（注意不传入elements参数）
  await stripe.confirmPayment({
    clientSecret,
    confirmParams: {
      confirmation_token: confirmationToken.id,
      return_url: 'your_return_url',
    },
  });
};

关键注意事项

1. 参数选择：

   • 当使用 Express Checkout 元素时，优先使用 confirmation_token
   • 避免同时传入 elements 和 confirmation_token 参数

2. React 集成：

   • 谨慎使用 useCallback 包装事件处理函数
   • 确保事件处理函数能够及时响应

3. 支付流程：

   • 不需要预先检查支付意向状态
   • 确认支付后，Stripe 会自动处理后续流程

技术深度解析

confirmPayment 与 handleNextAction 的区别

虽然这两个方法都用于支付流程，但它们有不同的用途：

1. confirmPayment：

   • 用于初始支付确认
   • 可以处理3D Secure等验证流程
   • 适用于大多数支付场景

2. handleNextAction：

   • 用于处理支付意向状态为"requires_action"的情况
   • 通常在支付流程中断后恢复时使用
   • 需要先检查支付意向状态

TypeScript 类型安全建议

为了在开发阶段就避免参数冲突问题，可以创建类型安全的包装函数：

type ConfirmPaymentParams = 
  | { elements: StripeElements; confirmation_token?: never }
  | { elements?: never; confirmation_token: string };

const safeConfirmPayment = (
  stripe: Stripe,
  params: ConfirmPaymentParams & { clientSecret: string }
) => {
  return stripe.confirmPayment(params);
};

这种方法可以在编译时就捕获参数冲突错误，提高代码健壮性。

总结