调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录
概览升级您的集成
线上付款
概览查找您的用例Managed Payments
支付方式
支付接口
支付场景
线下支付
其他 Stripe 产品

Checkout 迁移指南

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

复制页面

旧版 Checkout 会向客户展示了一个模态对话框，用于收集卡片信息，并将生成的令牌或来源返回到您的网站。相比之下，Payment Link 和当前版本的 Checkout 是由 Stripe 托管的智能支付页面，可用来创建付款或订阅。两种集成都支持 Apple Pay、Google Pay、动态 3DS 验证、Connect、重用当前客户，以及很多其他功能。如果 Payment Link 和 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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "email"="customer@example.com" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "email"="{{STRIPE_EMAIL}}" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "email"="{{STRIPE_EMAIL}}" \
  -d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 在需要时自动收集邮编，达到预防欺诈或合规的目的。

另见

此页面的内容有帮助吗？
是否
需要帮助？联系支持。
加入我们的早期使用计划。
查看我们的更改日志。
有问题？联系销售。
LLM? Read llms.txt.
Powered by Markdoc