# Checkout 迁移指南
了解如何迁移到 Stripe 的最新集成。
旧版 Checkout 会向客户弹出模态对话框，用于收集银行卡信息，然后向您的网站返回一个令牌或支付源。相比之下，[Payment Links](https://docs.stripe.com/payment-links.md) 和当前版本的 [Checkout](https://docs.stripe.com/payments/checkout.md) 均为由 Stripe 托管的智能支付页面，用于创建支付或 *订阅* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)。这两种集成方式都支持 Apple Pay、Google Pay、动态 *3DS 验证* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)、*Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients)、存量客户复用以及许多其他功能。如果支付链接或 Checkout 不符合您的应用场景，您还可以[对比其他支付集成方案](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability)。
## Before you begin
如果您使用的是 Stripe 的 [SDK](https://docs.stripe.com/sdks.md)，请升级到最新版本。
## 选择您的业务模式
要从旧版 Checkout 迁移，请按照最能代表您的业务模式的指南进行。每个指南都会推荐一个集成路径，并附有示例代码。
- [动态产品目录和定价](https://docs.stripe.com/payments/checkout/migration.md#api-products)
如果您有一个很大的产品目录，或需要支持动态生成行项目（例如捐款或税）。
- [动态订阅](https://docs.stripe.com/payments/checkout/migration.md#api-subscriptions)
如果您是一家 SaaS 提供商，需要给客户计费，且需要高级功能支持。
- [Connect 平台和交易市场](https://docs.stripe.com/payments/checkout/migration.md#connect)
如果您运营的是一个交易市场，连接服务提供者与客户。
- [保存支付方式供以后使用](https://docs.stripe.com/payments/checkout/migration.md#setup-mode)
如果您运营的业务仅在服务完成后才向客户收款。
- [固定定价简单产品目录](https://docs.stripe.com/payments/checkout/migration.md#simple-products)
如果您销售价格事先确定了的若干种产品。
- [简单订阅](https://docs.stripe.com/payments/checkout/migration.md#simple-subscriptions)
如果您是一家 SaaS 提供商，执行月度订阅计划。
在参考相关指南的同时，您还可以参考[转换表](https://docs.stripe.com/payments/checkout/migration.md#parameter-conversion)，了解特定参数和配置选项之间的映射关系。
## 动态产品目录和定价
如果您销售的产品需要动态确定金额或行项目（例如，大的产品目录或捐款），则请查看[接受一次性付款](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout)。
使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器来创建收款。当前版本的 Checkout 的服务器集成逆转了此流程 — 在您的服务器上创建一个 Session，将客户重定向到 Checkout，在支付完成后客户再被重定向回您的应用。
### 升级前
使用旧版 Checkout 时，您需要显示动态金额和订阅并向客户收集银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，然后收款。
#### curl
```bash
curl https://api.stripe.com/v1/customers \
-u <>: \
-d "email"="customer@example.com" \
-d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}" \
-d "description"="Custom t-shirt" \
-d "amount"="{{ORDER_AMOUNT}}" \
-d "currency"="usd"
```
### 升级后
在您的网站上添加一个结账按钮，调用一个服务器端点来创建 [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md)。
```html
Buy cool new product
```
Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：
- 要扣款的[行项目](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items)
- 要使用的货币
包含一个 `success_url` 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url)。如果您需要在付款后为所购买的商品履单，请参阅[履行 Checkout 和支付链接付款](https://docs.stripe.com/checkout/fulfillment.md)。
## 动态订阅
如果您提供的订阅服务需要动态确定，或需要其他高级功能支持，则请查看[设置订阅](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md)。
使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器来创建客户和订阅。当前版本的 Checkout 逆转了此流程 — 先在您的服务器上创建一个 Session，将客户重定向到 Checkout，成功后，客户再被重定向回您的应用。
### 升级前
使用旧版 Checkout 时，您需要显示订阅信息并收集客户的银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，创建客户和订阅。
#### curl
```bash
curl https://api.stripe.com/v1/customers \
-u <>: \
-d "email"="customer@example.com" \
-d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}" \
-d "items[0][price]"="{PRICE_ID}" \
-d "trial_period_days"=30
```
### 升级后
在您的网站上添加一个结账按钮，调用一个服务器端点来创建 [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md)。
```html
Subscribe to cool new service
```
Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：
- 要扣款的[行项目](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items)
- 要使用的货币
包含一个 `success_url` 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url)。创建客户和订阅后，客户被重定向到 `success_url`。如果您需要在付款后为所购买的服务履单，请参阅[履行 Checkout 和支付链接付款](https://docs.stripe.com/checkout/fulfillment.md)。
## Connect 平台和交易市场
如果您运营的是 Connect 平台或交易市场，并且需要创建涉及 Connect 子账户的付款，则考虑使用当前版本的 Checkout。
以下示例演示用 Checkout Sessions API 处理直接收款。也可以结合使用 Checkout 和 Connect 以及[定向收款](https://docs.stripe.com/connect/destination-charges.md?platform=web&ui=stripe-hosted) 和 [独立收款和转账](https://docs.stripe.com/connect/separate-charges-and-transfers.md?platform=web&ui=stripe-hosted)。
### 升级前
使用旧版 Checkout 时，您需要在客户端向客户收集银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，并代 Connect 子账户收款。
#### curl
```bash
curl https://api.stripe.com/v1/charges \
-u <>: \
-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](https://docs.stripe.com/api/checkout/sessions/create.md)。
```html
Roger's Farm
```
Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：
- 要扣款的[行项目](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items)
- 要使用的货币
包含一个 `success_url` 并提供您网站上的某个页面的 URL，客户在完成付款后被重定向到此页面。
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url)。如果您需要在付款后为所购买的商品或服务履单，请参阅[履行 Checkout 和支付链接付款](https://docs.stripe.com/checkout/fulfillment.md)。
## 保存支付方式供以后使用
如果您提供的服务不立即向客户收款，则请查看[设置未来付款](https://docs.stripe.com/payments/save-and-reuse.md?platform=checkout)。
使用旧版 Checkout 时，您需要在客户端创建令牌或来源，然后传递到您的服务器进行保存以供将来使用。当前版本的 Checkout 逆转了此流程 — 先在您的服务器上创建一个 Session，将客户重定向到 Checkout，成功后，客户再被重定向回您的应用。
### 升级前
使用旧版 Checkout 时，您需要显示收款信息并向客户收集银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，最终创建收款。
#### curl
```bash
curl https://api.stripe.com/v1/customers \
-u <>: \
-d "email"="customer@example.com" \
-d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}" \
-d "description"="Cleaning service" \
-d "amount"="{{ORDER_AMOUNT}}" \
-d "currency"="usd"
```
### 升级后
在您的网站上添加一个结账按钮，调用一个服务器端点来创建 [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md)。
```html
Cleaning service
```
Checkout Session 是客户被重定向到支付表单时所看到的内容的程序化展示。可通过多种选项对它进行配置，例如：
- 要扣款的[行项目](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items)
- 要使用的货币
包含一个 `success_url` 并提供您网站上的某个页面的 URL，客户在完成付款设置后被重定向到此页面。
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d mode=setup \
-d currency=usd \
--data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```
创建 Checkout Session 后，将您的客户重定向到响应中返回的 [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) 以获取支付方式的详细信息。客户完成流程后将被重定向到 `success_url`。当您准备好收款时，从 Checkout Session 中[检索 SetupIntent](https://docs.stripe.com/payments/checkout/save-and-reuse.md?payment-ui=stripe-hosted#retrieve-checkout-session)，并使用它来准备交易。
## 固定价格的简单产品目录
如果您以固定定价销售产品（如 T 恤或电子书），请查看[支付链接](https://docs.stripe.com/payment-links/create.md) 指南。您可能已经使用旧版 Checkout 在客户端创建令牌或来源，然后将其传递到您的服务器来创建收款。
### 升级前
使用旧版 Checkout 时，您需要显示金额和订阅并向客户收集银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，创建客户和收款。
#### Curl
```bash
curl https://api.stripe.com/v1/customers \
-u <>: \
-d "email"="{{STRIPE_EMAIL}}" \
-d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/charges \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}" \
-d "description"="T-shirt" \
-d "amount"=500 \
-d "currency"="usd"
```
### 升级后
创建一个表示项目的[产品](https://docs.stripe.com/api/products.md) 和[价格](https://docs.stripe.com/api/prices.md)。下例创建了产品内联。您也可以在[管理平台](https://dashboard.stripe.com/test/products) 中创建这些对象。
```curl
curl https://api.stripe.com/v1/prices \
-u "<>:" \
-d currency=usd \
-d unit_amount=500 \
-d "product_data[name]=T-shirt"
```
用产品和价格在管理平台中创建一个[支付联接](https://dashboard.stripe.com/payment-links/create)。创建链接后，点击**购买按钮**以配置设计并生成代码，您可将其复制粘贴到您的网站。
#### HTML
```html
Purchase your new kit
```
## 简单订阅
如果您提供的是简单的订阅服务（例如软件的每月访问权限），请参阅第 2 版的[支付链接](https://docs.stripe.com/payment-links/create.md) 指南。您可能已经在使用旧版 Checkout 时在客户端创建令牌或来源，然后传递到您的服务器来创建客户和订阅。
### 升级前
使用旧版 Checkout 时，您需要显示订阅信息并收集客户的银行卡信息。
```html
```
接下来，将生成的令牌或来源发送到您的服务器，创建客户和订阅。
#### Curl
```bash
curl https://api.stripe.com/v1/customers \
-u <>: \
-d "email"="{{STRIPE_EMAIL}}" \
-d "source"="{{STRIPE_TOKEN}}"
curl https://api.stripe.com/v1/subscriptions \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}" \
-d "items[][price]"="{PRICE_ID}" \
-d "items[][quantity]"=1
```
### 升级后
创建一个表示订阅的[产品](https://docs.stripe.com/api/products.md) 和[价格](https://docs.stripe.com/api/prices.md)。下例中创建了产品内联。您也可以在[管理平台](https://dashboard.stripe.com/test/products) 中创建这些对象。
```curl
curl https://api.stripe.com/v1/prices \
-u "<>:" \
-d currency=usd \
-d unit_amount=2000 \
-d "recurring[interval]=month" \
-d "product_data[name]=Gold Tier"
```
用产品和价格在管理平台中创建一个[支付联接](https://dashboard.stripe.com/payment-links/create)。创建链接后，点击**购买按钮**以配置设计并生成代码，您可将其复制粘贴到您的网站。
#### HTML
```html
Purchase your new kit
```
## 参数转换
当前版本的 Checkout 支持旧版 Checkout 的大部分功能。但是，它们使用的 API 不同。下表是旧版和当前版本之间的参数和配置选项映射。有关配置选项的完整列表，请查看 [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md)。
| 旧版本 | 当前版本 | 集成提示 |
| ------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowRememberMe` | 不支持 | 创建 [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md) 时，指定 `customer_account` 或 `customer` 参数，即可复用存量客户信息。您也可以开启 [Link](https://docs.stripe.com/payments/link/checkout-link.md)，让客户安全保存并重复使用其支付信息。 |
| `amount` | 已自动计算所有 `line_items` 的总和 | 总金额是您传递到 Checkout 的行项目的和。 |
| `billingAddress` | `Session.billing_address_collection` | Checkout 在需要时自动收集账单地址，达到预防欺诈或合规的目的。将该参数设置为 `required`，则会始终收集账单地址。 |
| `closed` | 当客户想要关闭 Checkout 时，他们会关闭浏览器标签页。 | |
| `currency` | `Session.currency` | |
| `description` | `Session.line_items.description` 或 `product.description` | 如果指定价格，则 Checkout 会自动计算并生成付款频率的描述。如果指定 `Session.line_items`，则 Checkout 会显示每个行项目的 `name`。 |
| `email` | `Session.customer_email` | 如果您已经知道客户的邮件地址，则在创建 Checkout Session 时可以预先填充 [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email)。 |
| `image` | **公司品牌**：在管理平台中上传您的徽标或图标。
**产品图片**：用 `product.images` 指定每个行项目的图片。 | Checkout 会针对贵商家的[品牌](https://docs.stripe.com/payments/checkout/customization/appearance.md#branding)和销售的产品使用特定的图片。Checkout 会默认显示您的徽标，并退回到您的商家名称旁的商家图标。 |
| `key` | 不再是向 Checkout 传递的参数 | |
| `locale` | `Session.locale` | 创建 Checkout Session 时，您可以指定一个受支持的[语言环境](https://docs.stripe.com/payments/checkout/custom-components.md#localization)。 |
| `name` | `Session.line_items` 中指定的价格的 `product.name` | 如果指定一个价格，则 Checkout 显示属于该价格的产品的名称。如果指定 `Session.line_items`，则 Checkout 会显示每个行项目的 `name`。 |
| `panelLabel` | `submit_type` | Checkout 会根据您销售的项目自动定制按钮文本。对于一次性付款，请使用 [submit_type](https://docs.stripe.com/payments/checkout/custom-components.md#submit-button) 自定义按钮文本。 |
| `shippingAddress` | `session.shipping_address_collection` | 通过传递要配送到的 `allowed_countries` 的一个数组[收集收货地址信息](https://docs.stripe.com/payments/collect-addresses.md?payment-ui=checkout)。 |
| `token` 或 `source` | `success_url` | 完成付款时，JavaScript 已不再有回调。由于您的客户是在另一个页面付款的，请设置 `success_url` 以在他们完成付款后将其重定向。 |
| `zipCode` | Checkout 自动收集 | Checkout 在需要时自动收集邮编，达到预防欺诈或合规的目的。 |
## See also
- [添加更多支付方式](https://docs.stripe.com/payments/payment-methods/overview.md)
- [收集地址和电话号码](https://docs.stripe.com/payments/collect-addresses.md)