Payment Intents API

了解 Stripe 支付的驱动因素 - Payment Intents API

用 Payment Intent API 构建可处理复杂付款流程的集成，付款流程的状态会随着 PaymentIntent 的生命周期发生变化。从最初创建到整个结账过程，此 API 会一直跟踪付款状态，并在必要时触发额外的验证步骤。

使用 Payment Intent 的好处包括：

自动处理验证
无双重收款
没有幂等性密钥问题
支持强客户认证 (SCA) 及类似法规变化

全套 API

将 Payment Intents API 与 Setup Intents 和 Payment Methods API 结合使用。这些 API 可帮您处理动态付款（例如，3DS 验证之类的额外验证），为您向其他国家/地区扩展做好准备，通知支持新的规范和区域性支付方式。

用 Payment Intents API 构建集成涉及两项操作：创建并确认 PaymentIntent。每个 PaymentIntent 通常都会关联您的应用程序中的一个购物车或客户会话。PaymentIntent 中承载着交易详情，例如支持的支付方式、收款金额以及期望的币种。

创建 PaymentIntent

要开始使用，请查看接受付款指南。其中介绍了如何在服务器上创建 PaymentIntent，并将它的客户端私钥传递到客户端，而非传递整个 PaymentIntent 对象。

当您创建 PaymentIntent时，您需要指定金额和货币之类的选项：

最佳实践

建议在知道金额后尽快创建 PaymentIntent，例如客户开始结账流程时，这有助于跟踪您的购买漏斗。如果金额发生变化，则可以更新它的金额。例如，如果客户在结账过程中后退了一步，然后向购物车添加了新的项目，则您可能需要在他们重新开始结账流程时更新金额。
如果结账过程中断然后又恢复，则应尝试重新使用同一个 PaymentIntent，而非创建一个新的。每个 PaymentIntent 都有唯一 ID，再次需要的时候可用它来检索。在应用的数据模型中，您可以将 PaymentIntent 的 ID 存储在客户的购物车或会话中以方便检索。重新使用 PaymentIntent 的好处在于此对象状态可帮助跟踪特定购物车或会话中失败的付款尝试。
请记得提供一个幂等性密钥来防止为同一笔购买创建重复的 PaymentIntent。此密钥通常基于在您的应用中为购物车或客户会话关联的 ID。

将客户端私钥传递到客户端

PaymentIntent 中包含一个客户端私钥，它是每个 PaymentIntent 的唯一密钥。在您的应用的客户端，Stripe.js 在调用函数（例如 stripe.confirmCardPayment 或 stripe.handleCardAction）来完成付款时将客户端私钥用作一个参数。

检索客户端私钥

PaymentIntent 中包含的是一个客户端私钥，用于在客户端安全地完成支付流程。有不同的方法可以将客户端私钥传递到客户端。

使用浏览器的 fetch 功能，从您的服务器上的端点获取客户端私钥。如果您的客户端是单页应用，特别是用现代的前端框架（例如 React）搭建的情况，则该方法最为合适。创建服务于客户端私钥的服务器端点：

然后在客户端用 JavaScript 获取客户端私钥：

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

注意

可以用客户端私钥来完成付款流程，使用 PaymentIntent 上指定的金额。不要记录它，而是把它嵌入到 URL，或显示给除客户以外的所有人。务必在包含客户端私钥的每个页面都启用 TLS。

付款后

客户确认付款后，最好的做法是让您的服务器监测 Webhook，以检测付款何时成功或失败。

如果有多个付款尝试，例如重试，则一个 PaymentIntent 可能不止有一个与它关联的Charge对象。对每笔收款，您都可以检查其结果及所用支付方式的详情。

为未来付款优化支付方式

setup_future_usage 参数负责保存支付方式以供将来再次使用。对于银行卡，它还会根据地方法规及卡组织规则优化授权率，例如 SCA。要确定使用哪个值，可考虑您打算将来如何使用此支付方式。

您打算如何使用支付方式	setup_future_usage 要使用的枚举值
仅会话内付款	`on_session`
仅会话外付款	`off_session`
会话内与会话外这两种付款方式	`off_session`

您仍可用设置用于会话内付款的银行卡进行会话外付款，但银行很有可能拒绝会话外付款，并要求持卡人进行额外的验证。

下例演示了如何创建 PaymentIntent 并指定 setup_future_usage：

注意

会话外付款的设置更有可能带来额外阻力。如果您不打算用保存的卡接受会话外付款，请使用会话内设置。Charges API 是一个较旧的支付 API，不能处理银行的银行卡验证请求，印度的商家不能使用。

动态账单描述符

默认情况下，您的 Stripe 的对账单描述符会在您对客户的银行卡扣款后显示在其对账单上。若想为不同的付款提供不同的描述，可包含 statement_descriptor 参数。

对账单描述符最多为 22 个字符，不能使用 <、>、'、" 或 * 这些特殊字符，且不能只包含数字。使用动态对账单描述符时，动态文字会附到在 Stripe 管理平台内设置的对账单描述符的前缀。在分隔默认的对账单描述符和动态部分时，还加上了一个星号 (*) 和空格。这两个字符也算在 22 个字符限制内。

在元数据内存储信息

Stripe 支持向您的常见请求（例如处理付款）中添加元数据。元数据不会向客户显示，也不会构成我们的欺诈预防系统拒绝或阻止付款的依据。

通过元数据，您可以向 Stripe 活动关联其他信息（对您自身有意义）。

您包含的任何元数据都可以在管理平台内查看（例如，查看单笔付款的页数时），并且可用于常见的报告中。例如，可以将您的店铺的订单 ID 绑定到那个订单的 PaymentIntent。这样做的话，您便能方便地核对 Stripe 内的付款与您系统内的订单。

如果您使用的是 Radar 风控团队版，则考虑以元数据形式传递任何额外的客户信息和订单信息。然后您可以编写使用元数据属性的 Radar 规则，并在管理平台内得到更多信息，进而加速您的审核流程。

当 PaymentIntent 创建收款时，PaymentIntent 将它的元数据复制到 Charge。对 PaymentIntent 进行的后续更新不会修改 PaymentIntent 之前创建的 Charge 的元数据。

注意

不要以元数据形式或在 PaymentIntent 的 description 参数中存储任何敏感信息（个人身份信息、银行卡详情等）。