Checkout 迁移指南
旧版 Checkout 会给客户呈现一个模态对话框来收集银行卡信息,然后向您的网站返回一个令牌或来源。与之相反,当前版本的 Checkout 是一个 Stripe 托管的智能支付页面,可创建付款或订阅。它支持 Apple Pay、动态 3DS 验证以及很多其他功能。
当前版本的 Checkout 提供了更大的灵活性,支持动态行项目、Connect,可重复使用 Customers。如果您想更快开始或产品目录更简单,则还可以使用仅客户端集成。
要从旧版迁移到当前版本,请遵照与您的业务模式最吻合的指南。每个指南都推荐有一个集成路径,同时附有示例代码。
如果您有一个很大的产品目录,或需要支持动态生成行项目(例如捐款或税)。
如果您是一家 SaaS 提供商,需要给客户计费,且需要高级功能支持。
如果您运营的是一个交易市场,连接服务提供者与客户。
如果您运营的业务仅在服务完成后才向客户收款。
如果您销售价格事先确定了的若干种产品。
如果您是一家 SaaS 提供商,执行月度订阅计划。
在参考相关指南的同时,您还可以参考转换表,了解两个版本的 Checkout 的配置选项之间的映射关系。
动态产品目录和定价
如果您销售的产品需要动态确定金额或行项目(例如,大的产品目录或捐款),则请查看接受一次性付款。
使用旧版 Checkout 时,您需要在客户端创建令牌或来源,然后传递到您的服务器来创建收款。当前版本的 Checkout 的服务器集成逆转了这个流程——在您的服务器上创建一个 Session,把它的 ID 传递到您的客户端,将客户重定向到 Checkout,成功后,客户再被重定向回您的应用。
升级前
使用旧版 Checkout 时,您需要显示动态金额和订阅并向客户收集银行卡信息。
<form action="/purchase" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Custom t-shirt" data-description="Your custom designed t-shirt" data-amount="{{ORDER_AMOUNT}}" data-currency="usd"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
接下来,将生成的令牌或来源发送到您的服务器,然后收款。
升级后
使用当前版本的 Checkout 时,先在您的服务器上创建一个 Checkout Session。
备注
如果您使用的是我们的某个客户端库,则请升级到最新版本的库,以使用 Checkout Sessions API。
接下来,将 Session ID 传递到您的客户端,并将客户重定向到 Checkout 来完成付款。
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
客户完成付款后,将被重定向到 success_url
。
如果您需要在付款后交付购买的商品,则请参考 Checkout 的订单履行。
动态订阅
如果您提供的订阅服务需要动态确定,或是需要其他高级功能支持,则请查看设置订阅。
使用旧版 Checkout 时,您需要在客户端创建令牌或来源,然后传递到您的服务器来创建客户和订阅。当前版本的 Checkout 的服务器集成逆转了这个流程——先在您的服务器上创建一个 Session,把它的 ID 传递到您的客户端,将客户重定向到 Checkout,成功后,客户再被重定向回您的应用。
升级前
使用旧版 Checkout 时,您需要显示订阅信息并收集客户的银行卡信息。
<form action="/subscribe" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Gold Tier" data-description="Monthly subscription with 30 days trial" data-amount="2000" data-label="Subscribe"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
接下来,将生成的令牌或来源发送到您的服务器,创建客户和订阅。
升级后
使用当前版本的 Checkout 时,先在您的服务器上创建一个 Checkout Session。
备注
如果您使用的是我们的某个客户端库,则请升级到最新版本的库,以使用 Checkout Sessions API。
接下来,将 Session ID 传递到您的客户端,并将客户重定向到 Checkout 来完成付款。
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
创建完客户和订阅后,客户将被重定向到 success_url
。
如果您需要在付款后交付购买的服务,则请参考 Checkout 的订单履行。
您还可以用 Checkout 更新订阅信息。
Connect 平台和交易市场
如果您运营的是 Connect 平台或交易市场,并且需要创建涉及 Connect 子账户的付款,则考虑使用当前版本的 Checkout 的服务器集成。按照 Connect 指南中的说明迁移您的集成。
下例演示了用 Checkout Sessions API 处理定向收款的方式。按照 Connect 指南创建定向收款。
升级前
使用旧版 Checkout 时,您需要在客户端向客户收集银行卡信息。
<form action="/purchase" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Food Marketplace" data-description="10 cucumbers from Roger's Farm" data-amount="2000"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
接下来,将生成的令牌或来源发送到您的服务器,并代 Connect 子账户收款。
升级后
使用当前版本的 Checkout 时,先代 Connect 子账户在您的服务器上创建一个 Checkout Session。
备注
如果您使用的是我们的某个客户端库,则请升级到最新版本的库,以使用 Checkout Sessions API。
接下来,将 Session ID 传递到您的客户端,并将客户重定向到 Checkout 来完成付款。初始化 Stripe.js 时一定要提供 Connect 子账户的 ID。
// Initialize Stripe.js with the same connected account ID used when creating // the Checkout Session. const stripe = Stripe(
, { stripeAccount:'pk_test_TYooMQauvdEDq54NiTphI7jx'}); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'{{CONNECTED_ACCOUNT_ID}}'
客户完成付款后,将被重定向到 success_url
。
如果您需要在付款后交付购买的商品或服务,则请参考 Checkout 的订单履行。
保存支付方式供以后使用
如果您提供的服务不立即向客户收款,则请查看设置未来付款。
使用旧版 Checkout 时,您需要在客户端创建令牌或来源,然后传递到您的服务器来保存供以后使用。当前版本的 Checkout 的服务器集成逆转了这个流程——先在您的服务器上创建一个 Session,把它的 ID 传递到您的客户端,将客户重定向到 Checkout,成功后,客户再被重定向回您的应用。
升级前
使用旧版 Checkout 时,您需要显示收款信息并向客户收集银行卡信息。
<form action="/subscribe" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Cleaning Service" data-description="Charged after your home is spotless" data-amount="2000"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
接下来,将生成的令牌或来源发送到您的服务器,最终创建收款。
升级后
使用当前版本的 Checkout,先用设置模式在您的服务器上创建一个 Checkout Session。
备注
如果您使用的是我们的某个客户端库,则请升级到最新版本的库,以使用 Checkout Sessions API。
接下来,将 Session ID 传递到您的客户端,并将客户重定向到 Checkout 来收集支付方式详情。
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
客户完成该流程后,将被重定向到 success_url
。
从这里,您可以从 Checkout 流程中检索 Setup Intent,并用它准备您的交易。
固定价格的简单产品目录
如果您是以固定价格销售产品(例如T恤或电子书),则请查看有关一次性付款的指南,了解如何生成代码片段添加到您的网站。
使用旧版 Checkout 时,您需要在客户端创建令牌或来源,然后传递到您的服务器来创建收款。使用当前版本的 Checkout 时,会为您自动创建付款,不再需要服务器集成。
客户端代码
服务器端代码
下面的转换表提供了两个版本的 Checkout 的配置选项的映射关系。有关当前版本配置选项的完整列表,请查看 redirectToCheckout
参考文档。
简单订阅
如果您提供的是简单的订阅服务(例如按月付费使用软件),请查看有关订阅的指南,了解如何在管理平台内创建订阅方案并生成代码片段添加到您的网站。
使用旧版 Checkout 时,您需要在客户端创建令牌或来源,然后传递到您的服务器来创建客户和订阅。而使用当前版本的 Checkout,它会为您自动创建客户和订阅,不再需要服务器集成。
客户端代码
服务器端代码
下面的转换表提供了两个版本的 Checkout 的配置选项的映射关系。有关当前版本配置选项的完整列表,请查看 redirectToCheckout
参考文档。
参数转换
当前版本的 Checkout 支持旧版 Checkout 中的大多数功能。但是,两个版本没有使用相同的 API。下面为当前版本与旧版本之间的参数和配置选项对照表。
有关当前版本 Checkout 接受的配置选项的完整列表,请查看 Stripe.js 参考文档 和 Checkout Sessions 的 API 参考文档。
旧版本 | 当前版本 | 集成提示 |
---|---|---|
allowRememberMe |
| 当前版本的 Checkout 不支持 Remember Me(记住我)功能。要重复使用现有客户,建议在创建 Checkout Session 时指定 customer 参数。 |
amount |
| 总金额是您传递到 Checkout 的行项目的和。 |
billingAddress |
| Checkout 在需要时自动收集账单地址,达到预防欺诈或合规的目的。将该参数设置到 required ,则会始终收集账单地址。 |
billingAddress |
| Checkout 在需要时自动收集账单地址,达到预防欺诈或合规的目的。将该参数设置到 required ,则会始终收集账单地址。 |
closed |
| 客户想要关闭 Checkout 时,可关闭浏览器选项卡或导航到 cancelUrl 。 |
currency |
| |
description |
| 如果指定价格,则 Checkout 会自动计算并生成付款频率的描述。如果指定 Session.line_items ,则 Checkout 会显示每个行项目的 name 。 |
email |
| 如果您已经知道客户的邮件地址,则在这里指定它,客户便不用再行输入。 |
image |
| Checkout 为您公司的品牌及产品使用特定的图片。Checkout 会默认显示您公司的 Logo,并返回到您公司的图标和名称。 |
key |
| |
locale |
| 创建 Checkout Session 时,可以指定一个支持的位置。 |
name |
| 如果指定一个价格,则 Checkout 显示属于该价格的产品的名称。如果指定 Session.line_items ,则 Checkout 会显示每个行项目的 name 。 |
panelLabel |
| Checkout 根据您销售的商品或服务自动自定义按钮文字。对于一次性付款,使用 submit_type 来自定义按钮文字。 |
shippingAddress |
| 通过传递想要配送到的 allowed_countries 的一个数组收集收货地址信息。 |
token 或 source |
| 完成付款时,JavaScript 已不再有回调。由于您的客户是在另一个页面付款的,因此设置 successUrl ,在他们完成付款后将其重定向。 |
zipCode |
| Checkout 在需要时自动收集邮编,达到预防欺诈或合规的目的。 |