迁移到 Payment Intent 和 Payment Methods API
了解如何从 Sources 和 Tokens API 过渡到 Payment Methods API。
Payment Methods API 替换了当前的 Tokens 和 Sources,为多种支付方式创建付款。它可以和 Payment Intents API 一起使用,为多种支付方式创建付款。
我们计划停止 Sources API 对本地支付方式的支持。如果您当前在使用 Sources API 处理任何本地支付方式,则必须将其迁移到 Payment Methods API。我们将发送电子邮件,提供有关终止 Sources 和 Tokens API 支持的更多信息。
虽然我们不打算停止支持银行卡支付方式,但仍建议您将其迁移至 Payment Methods 和 Payment Intents API。有关迁移银行卡支付方式的更多信息,请参阅迁移到 Payment Intents API。
将本地支付方式从 Sources API 迁移到 Payment Intents API
要迁移您的本地支付方式集成,更新您的服务器和前端以使用 PaymentIntents API。通常涉及三种典型的集成选项:
- 在您的支付流程中重定向到 Stripe Checkout。
- 在您自己的支付页面使用 Stripe Payment Element。
- 构建自己的表单并使用 Stripe JS SDK 完成付款。
如果您使用 Stripe Checkout 或 Payment Element,则可以从 Stripe 管理平台添加和管理大多数支付方式,不需要更改代码。
有关用 Payment Methods API 集成本地支付方式的具体信息,请查看支付方式文档中该支付方式的说明。下表对不同支付类型进行了更高级别的比较。
旧集成 | Stripe Checkout | Payment Element | 自己的表单 |
---|---|---|---|
低度复杂 | 中度复杂 | 高度复杂 | |
在前端或服务器上创建 Source | 在服务器上创建 Checkout Session | 在服务器上创建 PaymentIntent | 在服务器上创建 PaymentIntent |
通过加载小工具或重定向到第三方来授权付款 | 不需要 | 将客户端私钥传递给前端,并使用 Stripe JS SDK 呈现 Payment Element 以完成付款 | 将客户端私钥传递给前端,用您自己的表单收集客户的详细信息,然后根据支付方式完成付款 |
确认可对扣款来源扣款,并对 Source 扣款 | 不需要 | 不需要 | 不需要 |
使用 charge. Webhook 异步确认 Charge 已成功 | 使用 payment_ Webhook 确认 Checkout Session 已成功 | 使用 payment_ Webhook 确认 PaymentIntent 已成功 | 使用 payment_ Webhook 确认 PaymentIntent 已成功 |
注意
PaymentIntent 对象表示新集成中的付款,当您在前端确认付款时,它会创建 Charge。如果您之前存储了对 Charge 的参考信息,则可以在客户完成付款后通过从 PaymentIntent 获取 Charge ID 来继续这样做。但是,我们也建议您存储 PaymentIntent ID。
检查支付状态
之前,您的集成应该会在每次 API 调用后都检查 Source 的状态和 Charge 的状态。您现在不再需要检查这两个状态——只需要在前端确认后检查 PaymentIntent 或 Checkout Session 的状态即可。
payment_intent.status | 含义 | 特别说明 |
---|---|---|
succeeded | 支付成功。 | 不适用 |
requires_ | 支付失败。 | 不适用 |
requires_ | 客户尚未完成付款授权。 | 如果客户没有在 48 小时内完成付款,则 PaymentIntent 将转化为 requires_ ,然后您可以重试确认。 |
一定要通过在您的服务器上获取 PaymentIntent 或侦听您的服务器上的 Webhook 来确认 PaymentIntent 的状态。不要只依赖您确认 PaymentIntent 时返回到提供的 return_
的用户。
退款
您可以继续通过 PaymentIntent 创建的 Charge 调用 Refunds API。Charge ID 可通过 latest_
参数获取。
或者,您可以向 Refunds API 提供 PaymentIntent ID,而非向 Charge 提供。
错误处理
以前,您必须处理 Source 上的错误。使用 PaymentIntent,您可以在创建 PaymentIntent 时以及客户授权付款后检查 PaymentIntent 上的错误,而非检查 Source 上的错误。PaymentIntent 上的大多数错误属于 invalid_
类型,在无效请求中返回。
迁移您的集成时,请记住 PaymentIntent 错误代码可能与 Source 的相应错误代码存在差异。
Webhook
如果您以前侦听过 Source 事件,则您可能需要更新您的集成来侦听新的事件类型。下表所示为一些示例。
旧的 Webhook | Checkout 上的新 Webhook | PaymentIntent 上的新 Webhook | 特别说明 |
---|---|---|---|
source. | 不适用 | 不适用 | |
source. | 不适用 | 不适用 | |
source. | 不适用 | 不适用 | |
charge. | checkout. | payment_ | 同时还会发送 charge. Webhook,因此您不必更新您的集成即可侦听新的 Webhook。 |
charge. | 不适用——客户可以在同一个 Checkout Session 上重新尝试付款,直至其过期,此时您会收到一个 checkout. 事件。 | payment_ | 同时还会发送 charge. Webhook,因此您不必更新您的集成即可侦听新的 Webhook。 |
charge. | charge. | charge. |
转移到 Payment Methods API
Payment Methods 和 Sources API 之间的主要区别在于 Source 是通过状态属性描述交易状态。这意味着每个 Source
对象在可以用于支付之前必须转换到可扣款状态。与之相反,PaymentMethod
是无状态的,靠 PaymentIntent 对象来表示付款状态。
注意
下表并非完整的支付方式列表。如果您将其他支付方式与 Sources API 进行集成,则也将它们迁移到 Payment Methods API。
流程 | 用 Payment Intents API 集成 Payment Method | Tokens 或 Sources 使用 Charges API |
---|---|---|
银行卡 | 银行卡支付 | Tokens 上支持;Source 上不建议 |
ACH 直接借记 | 美国银行账户直接借记 | Tokens 上支持 Source 上不支持 |
ACH 贷记转账 | 美元银行转账 | 已弃用 |
支付宝 | 支付宝支付 | 已弃用 |
Bancontact | Bancontact 支付 | 已弃用 |
EPS | EPS 支付 | 已弃用 |
giropay | giropay 支付 | 已弃用 |
iDEAL | iDEAL 支付 | 已弃用 |
Klarna | Klarna 支付 | 已弃用 |
Multibanco | Multibanco 支付 | 已弃用 Beta |
Przelewy24 | Przelewy24 支付 | 已弃用 |
SEPA 贷记转账 | 欧元银行转账 | 已弃用 |
SEPA 直接借记 | 单一欧元支付区直接借记 | 已弃用 |
Sofort | Sofort 支付 | 已弃用 |
WeChat Pay | 微信支付 | 已弃用 |
选择了要集成的 API 之后,可使用我们的支付方式指南确定正确的支付方式来支持您的客户。
本指南中包含对各个支付方式的详细描述,并讲述了它们在面向客户的流程中的差异,同时还给出了最相关的地理区域。您可以在管理平台中启用可使用的支付方式。激活通常是即时的,不需要额外的合同。
与旧版可重复使用的支付方式兼容
如果您之前用 Sources 处理过以下任何可重复使用的支付方式,则不会自动迁移当前已保存的支付来源。
- 支付宝
- BACS 直接借记
- SEPA 直接借记
要保留当前客户保存的支付方式,您必须用 Stripe 管理平台内的数据迁移工具将这些来源转化为支付方式。有关转化方式的说明,请参阅支持页面。
与旧版银行卡对象的兼容性
If you previously collected card customer payment details with Stripe using cards or Sources, you can start using the Payment Methods API immediately without migrating any payment information.
已保存到 Customer 的兼容支付方式可以用于接受 PaymentMethod 对象的任意 API。例如,创建 PaymentIntent 时,您可以将保存的银行卡用作一个 PaymentMethod:
切记,在将对象绑定到 PaymentIntent 时,务必要提供您的兼容支付方式所保存到的 Customer ID。
您可以通过 Payment Methods API 检索所有已保存的兼容支付方式。
有了这种兼容性,就不会创建新的对象;Payment Methods API 为同一底层对象提供了一个不同的视图。例如,通过 Payment Methods API 对兼容支付方式进行的更新可以通过 Sources API 看到,反之亦然。