调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录

Checkout 迁移指南

了解如何迁移到 Stripe 的最新集成。

旧版 Checkout 为客户显示一个模态对话框，用以收集银行卡信息，并返回一个令牌或您网站的来源。相比之下，支付链接 和当前版本的 Checkout 是由 Stripe 托管的智能支付页面，可创建支付或订阅。两种集成都支持 Apple Pay、Google Pay、Dynamic 3D Secure、Connect、重用现有客户和许多其他功能。如果支付链接或 Checkout 不适合您的使用情况，您还可以比较其他支付集成。

开始前

如果您使用的是 Stripe 的 SDK，请升级到最新版本。

选择您的业务模式

要从旧版 Checkout 迁移，请按照最能代表您的业务模式的指南进行。每个指南都会推荐一个集成路径，并附有示例代码。

在参考相关指南的同时，您还可以参考转换表，了解特定参数和配置选项之间的映射关系。

动态产品目录和定价

如果您销售的产品需要动态确定金额或行项目（例如，大的产品目录或捐款），则请查看接受一次性付款。

使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器来创建收款。当前版本的 Checkout 的服务器集成逆转了此流程 — 在您的服务器上创建一个 Session，将客户重定向到 Checkout，在支付完成后客户再被重定向回您的应用。

升级前

使用旧版 Checkout 时，您需要显示动态金额和订阅并向客户收集银行卡信息。

client.html
<form action="/purchase" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="Custom t-shirt"
    data-description="Your custom designed t-shirt"
    data-amount="{{ORDER_AMOUNT}}"
    data-currency="usd">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，然后收款。

Command Line
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "description"="Custom t-shirt" \
  -d "amount"="{{ORDER_AMOUNT}}" \
  -d "currency"="usd"

升级后

在您的网站上添加一个结账按钮，调用一个服务器端点来创建 Checkout Session。

checkout.html
<html>
  <head>
    <title>Buy cool new product</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：

包含一个 success_url 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][price_data][product_data][name]"="Custom t-shirt" \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success"

在创建 Checkout Session 后，将客户重定向到在响应中返回的 URL。如果您需要在付款后为所购买的商品履单，请参阅履行 Checkout 和支付链接付款。

动态订阅

如果您提供的订阅服务需要动态确定，或需要其他高级功能支持，则请查看设置订阅。

使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器来创建客户和订阅。当前版本的 Checkout 逆转了此流程 — 先在您的服务器上创建一个 Session，将客户重定向到 Checkout，成功后，客户再被重定向回您的应用。

升级前

使用旧版 Checkout 时，您需要显示订阅信息并收集客户的银行卡信息。

client.html
<form action="/subscribe" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="Gold Tier"
    data-description="Monthly subscription with 30 days trial"
    data-amount="2000"
    data-label="Subscribe">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，创建客户和订阅。

Command Line
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "items[0][price]"="{PRICE_ID}" \
  -d "trial_period_days"=30

升级后

在您的网站上添加一个结账按钮，调用一个服务器端点来创建 Checkout Session。

checkout.html
<html>
  <head>
    <title>Subscribe to cool new service</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Subscribe</button>
    </form>
  </body>
</html>

Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：

包含一个 success_url 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d "subscription_data[trial_period_days]"=30 \
  -d mode=subscription \
  --data-urlencode success_url="https://example.com/success"

在创建 Checkout Session 后，将客户重定向到在响应中返回的 URL。创建客户和订阅后，客户被重定向到 success_url。如果您需要在付款后为所购买的服务履单，请参阅履行 Checkout 和支付链接付款。

Connect 平台和交易市场

如果您运营的是 Connect 平台或交易市场，并且需要创建涉及 Connect 子账户的付款，则考虑使用当前版本的 Checkout。

以下示例演示用 Checkout Sessions API 处理直接收款。也可以结合使用 Checkout 和 Connect 以及定向收款 和 独立收款和转账。

升级前

使用旧版 Checkout 时，您需要在客户端向客户收集银行卡信息。

client.html
<form action="/purchase" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="Food Marketplace"
    data-description="10 cucumbers from Roger's Farm"
    data-amount="2000">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，并代 Connect 子账户收款。

Command Line
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{TOKEN_ID}}" \
  -d "description"="10 cucumbers from Roger\"s Farm" \
  -d "amount"=2000 \
  -d "currency"="usd" \
  -d "application_fee_amount"=200 \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"

升级后

在您的网站上添加一个结账按钮，调用一个服务器端点来创建 Checkout Session。

checkout.html
<html>
  <head>
    <title>Roger's Farm</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：

包含一个 success_url 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "line_items[0][price_data][currency]"=usd \
  --data-urlencode "line_items[0][price_data][product_data][name]"="Cucumbers from Roger's Farm" \
  -d "line_items[0][price_data][unit_amount]"=200 \
  -d "line_items[0][quantity]"=10 \
  -d "payment_intent_data[application_fee_amount]"=200 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success"

在创建 Checkout Session 后，将客户重定向到在响应中返回的 URL。如果您需要在付款后为所购买的商品或服务履单，请参阅履行 Checkout 和支付链接付款。

保存支付方式供以后使用

如果您提供的服务不立即向客户收款，则请查看设置未来付款。

使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器进行保存以供将来使用。当前版本的 Checkout 逆转了此流程 — 先在您的服务器上创建一个 Session，将客户重定向到 Checkout，成功后，客户再被重定向回您的应用。

升级前

使用旧版 Checkout 时，您需要显示收款信息并向客户收集银行卡信息。

client.html
<form action="/subscribe" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="Cleaning Service"
    data-description="Charged after your home is spotless"
    data-amount="2000">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，最终创建收款。

Command Line
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "description"="Cleaning service" \
  -d "amount"="{{ORDER_AMOUNT}}" \
  -d "currency"="usd"

升级后

在您的网站上添加一个结账按钮，调用一个服务器端点来创建 Checkout Session。

checkout.html
<html>
  <head>
    <title>Cleaning service</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Subscribe</button>
    </form>
  </body>
</html>

Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：

包含一个 success_url 并提供您网站上的某个页面的 URL，客户在完成付款设置后被重定向到此页面。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d mode=setup \
  --data-urlencode success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}"

在创建 Checkout Session 后，将客户重定向到在响应中返回的 URL 以收集支付方式详情。客户完成该流程后，将被重定向到 success_url。在您准备好收款时，请从 Checkout Session 检索 SetupIntent，并用它准备交易。

固定价格的简单产品目录

如果您以固定定价销售产品（如 T 恤或电子书），请查看支付链接 指南。您可能已经使用旧版 Checkout 在客户端创建令牌或来源，然后将其传递到您的服务器来创建收款。

升级前

使用旧版 Checkout 时，您需要显示金额和订阅并向客户收集银行卡信息。

client.html
<form action="/pay" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="T-shirt"
    data-description="Comfortable cotton t-shirt"
    data-amount="500"
    data-currency="usd">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，创建客户和收款。

Command Line
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="{{STRIPE_EMAIL}}" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "description"="T-shirt" \
  -d "amount"=500 \
  -d "currency"="usd"

升级后

创建一个表示项目的产品 和价格。下例创建了产品内联。您也可以在管理平台 中创建这些对象。

Command Line
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d currency=usd \
  -d unit_amount=500 \
  -d "product_data[name]"=T-shirt

用产品和价格在管理平台中创建一个支付联接。创建链接后，点击购买按钮以配置设计并生成代码，您可将其复制粘贴到您的网站。

index.html
<body>
  <h1>Purchase your new kit</h1>
  <!-- Paste your embed code script here. -->
  <script
    async
    src="https://js.stripe.com/v3/buy-button.js">
  </script>
  <stripe-buy-button
    buy-button-id=
'{{BUY_BUTTON_ID}}'

    publishable-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

  >
  </stripe-buy-button>
</body>

简单订阅

如果您提供的是简单的订阅服务（例如软件的每月访问权限），请参阅第 2 版的支付链接 指南。您可能已经在使用旧版 Checkout 时在客户端创建令牌或来源，然后传递到您的服务器来创建客户和订阅。

升级前

使用旧版 Checkout 时，您需要显示订阅信息并收集客户的银行卡信息。

client.html
<form action="/subscribe" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

    data-name="Gold Tier"
    data-description="Monthly subscription"
    data-amount="2000"
    data-currency="usd"
    data-label="Subscribe">
  </script>
</form>

接下来，将生成的令牌或来源发送到您的服务器，创建客户和订阅。

Command Line
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="{{STRIPE_EMAIL}}" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "items[][price]"="{PRICE_ID}" \
  -d "items[][quantity]"=1

升级后

创建一个表示订阅的产品 和价格。下例中创建了产品内联。您也可以在管理平台 中创建这些对象。

Command Line
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d currency=usd \
  -d unit_amount=2000 \
  -d "recurring[interval]"=month \
  -d "product_data[name]"="Gold Tier"

用产品和价格在管理平台中创建一个支付联接。创建链接后，点击购买按钮以配置设计并生成代码，您可将其复制粘贴到您的网站。

index.html
<body>
  <h1>Purchase your new kit</h1>
  <!-- Paste your embed code script here. -->
  <script
    async
    src="https://js.stripe.com/v3/buy-button.js">
  </script>
  <stripe-buy-button
    buy-button-id=
'{{BUY_BUTTON_ID}}'

    publishable-key=
"pk_test_TYooMQauvdEDq54NiTphI7jx"

  >
  </stripe-buy-button>
</body>

参数转换

当前版本的 Checkout 支持旧版 Checkout 的大部分功能。但是，它们使用的 API 不同。下表是旧版和当前版本之间的参数和配置选项映射。有关配置选项的完整列表，请查看 Checkout Sessions。

旧版本当前版本集成提示
allowRememberMe不支持通过在创建 Checkout Session 时指定 customer 参数来重复使用现有客户。您也可以启用 链接，让客户安全地保存并重复使用他们的支付信息。
amount已自动计算所有 line_items 的总和总金额是您传递到 Checkout 的行项目的和。
billingAddressSession.billing_address_collectionCheckout 在需要时自动收集账单地址，达到预防欺诈或合规的目的。将该参数设置为 required，则会始终收集账单地址。
closedcancel_url客户想要关闭 Checkout 时，可关闭浏览器选项卡或导航到 cancel_url。
currencySession.currency
descriptionSession.line_items.description 或 product.description如果指定价格，则 Checkout 会自动计算并生成付款频率的描述。如果指定 Session.line_items，则 Checkout 会显示每个行项目的 name。
emailSession.customer_email如果您已经知道客户的邮件地址，则在创建 Checkout Session 时可以预先填充 customer_email。

image

公司品牌：在管理平台中上传您的徽标或图标。

产品图片：用 product.images 指定每个行项目的图片。

Checkout 会针对贵商家的品牌和销售的产品使用特定的图片。Checkout 会默认显示您的徽标，并退回到您的商家名称旁的商家图标。

key不再是向 Checkout 传递的参数
localeSession.locale创建 Checkout Session 时，可以指定一个支持的区域。
nameSession.line_items 中指定的价格的 product.name如果指定一个价格，则 Checkout 显示属于该价格的产品的名称。如果指定 Session.line_items，则 Checkout 会显示每个行项目的 name。
panelLabelsubmit_typeCheckout 会根据您销售的项目自动自定义按钮文本。对于一次性付款，用 submit_type 自定义按钮文本。
shippingAddresssession.shipping_address_collection通过传递要配送到的 allowed_countries 的一个数组收集收货地址信息。
token 或 sourcesuccess_url完成付款时，JavaScript 已不再有回调。由于您的客户是在另一个页面付款的，请设置 success_url 以在他们完成付款后将其重定向。
zipCodeCheckout 自动收集Checkout 在需要时自动收集邮编，达到预防欺诈或合规的目的。

另见

此页面的内容有帮助吗？
是否
需要帮助？联系支持。
加入我们的早期使用计划。
查看我们的产品更改日志。
有问题？联系销售。
Powered by Markdoc
本页
开始前
选择您的业务模式
动态产品目录和定价
升级前
升级后
动态订阅
升级前
升级后
Connect 平台和交易市场
升级前
升级后
保存支付方式供以后使用
升级前
升级后
固定价格的简单产品目录
升级前
升级后
简单订阅
升级前
升级后
参数转换
另见
使用的产品
Checkout
Payment Links