# 升级您的集成

将您的集成升级到最新的 API 版本。

查看[开发人员更新日志](https://docs.stripe.com/changelog.md)，获取 Stripe API 变更的完整记录。

要升级您的集成，请完成以下步骤。请搜索[变更日志](https://docs.stripe.com/changelog.md?api_usage=true)，查找与您的集成相关的特定信息。

## 定义升级的目标版本

请务必在代码中指定您集成所使用的 API 版本，而不是依赖账户的默认 API 版本。若要为 API 调用测试较新的版本，请在真实环境或测试环境中设置 `Stripe-Version` 标头。了解如何[在我们的服务器端 SDK 中设置 API 版本](https://docs.stripe.com/upgrades.md#specify-sdk-api-version)。

在 [Workbench](https://docs.stripe.com/workbench/overview.md) 的[概览选项卡](https://dashboard.stripe.com/workbench/overview)中查看您的集成使用的 API 版本。

查看[变更日志](https://docs.stripe.com/changelog.md)，以查找升级的目标版本。

## 在 SDK 中指定 API 版本

您的账户有一个 *默认 API 版本* (If an API request doesn’t specify a version, Stripe uses your account’s default API version, which you can set in the Stripe Dashboard. We recommend specifying the version for each request (either with the Stripe-Version HTTP header or by using a pinned SDK) so your code determines the API version instead of your Dashboard settings)，用于定义您如何调用 API、可以访问哪些功能以及 API 响应的结构。当您使用[服务器端 SDK](https://docs.stripe.com/sdks.md#server-side-libraries) 时，您对 Stripe 的 API 调用使用的是 SDK 发布时的 API 版本。在使用 Java、Go 或 .NET 等强类型语言时，您不能指定不同的 API 版本。

#### Ruby

[stripe-ruby](https://github.com/stripe/stripe-ruby) 库允许您全局设置 API 版本，也可以针对单个请求进行设置。

如果您未设置 API 版本，较新版本的 stripe-ruby 会使用 stripe-ruby 版本发布时的最新 API 版本。而 [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) 之前的 stripe-ruby 版本会使用您账户的默认 API 版本。

要通过 SDK **全局**设置 API 版本，请将版本号赋值给 `Stripe.api_version` 属性：

```ruby
require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>', stripe_version: '2026-08-26.dahlia')
```

或者按请求设置版本：

```ruby
require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
intent = client.v1.payment_intents.retrieve(
  'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
  {
    stripe_version: '2026-08-26.dahlia',
  },
)
intent.capture
```

> 当您在全局或按请求覆盖版本时，API 响应对象也会以该版本返回。

#### Python

[stripe-python](https://github.com/stripe/stripe-python) 库允许您全局设置 API 版本，也可以针对单个请求进行设置。

如果您未设置 API 版本，较新版本的 stripe-python 会使用 stripe-python 版本发布时的最新 API 版本。[v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) 之前的 stripe-python 版本使用您账户的默认 API 版本。

要通过 SDK **全局**设置 API 版本，请将版本号赋值给 `stripe.api_version` 属性：

```python
import stripe
# Don't put any keys in code. See /keys-best-practices.
stripe.api_key = <<YOUR_SECRET_KEY>>
stripe.api_version = '2026-08-26.dahlia'
```

或者按请求设置版本：

```python
import stripe
intent = stripe.PaymentIntent.retrieve(
  "pi_1DlIVK2eZvKYlo2CW4yj5l2C",
  stripe_version="2026-08-26.dahlia",
)
intent.capture()
```

> 当您在全局或按请求覆盖版本时，API 响应对象也会以该版本返回。

#### PHP

[stripe-php](https://github.com/stripe/stripe-php) 库允许您在全局或针对每个请求设置 API 版本。

如果您未设置 API 版本，较新版本的 stripe-php 会使用 stripe-php 版本发布时的最新 API 版本。而 [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) 之前的 stripe-php 版本使用您账户的默认 API 版本。

要通过 SDK **全局**设置 API 版本，请将版本号传递给 `\Stripe\Stripe::setApiVersion()` 方法：

```php
$stripe = new \Stripe\StripeClient([
  // Don't put any keys in code. See /keys-best-practices.
  "api_key" => "<<YOUR_SECRET_KEY>>",
  "stripe_version" => "2026-08-26.dahlia"
]);
```

或者按请求设置版本：

```php
$intent = $stripe->paymentIntents->capture(
  'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
  [],
  ['stripe_version' => '2026-08-26.dahlia']
);
```

> 当您在全局或按请求覆盖版本时，API 响应对象也会以该版本返回。

#### Java

由于 Java 是强类型编程语言，SDK 中使用的 API 版本是_固定的_，且为 SDK 发布时的最新 API 版本。

我们不建议为强类型编程语言设置不同的 API 版本，因为响应对象可能与 SDK 中的强类型不匹配，并导致请求失败。例如，如果您要针对的 API 版本需要 SDK 类型中不存在的参数，则请求会失败。

#### Node

[stripe-node](https://github.com/stripe/stripe-node) 库允许您全局设置 API 版本，也可以针对单个请求进行设置。

如果您未设置 API 版本，较新版本的 stripe-node 会使用 stripe-node 版本发布时的最新 API 版本。[v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) 之前的 stripe-node 版本使用您账户的默认 API 版本。

要通过 SDK **全局**设置 API 版本，请提供 `apiVersion` 选项：

```javascript
// Don't put any keys in code. See /keys-best-practices.
const stripe = require('stripe')('<<YOUR_SECRET_KEY>>', {
  apiVersion: '2026-08-26.dahlia',
});
```

或者按请求设置版本：

```javascript
const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', {
  apiVersion: '2026-08-26.dahlia',
});
```

#### Typescript 用法

TypeScript 类型反映了发布时的最新 API 版本。此版本在 [API_VERSION 文件](https://github.com/stripe/stripe-node/blob/master/API_VERSION)中编码。

请将 Stripe 设置为默认导入，并使用最新的 API 版本将其实例化为 `new Stripe()`。

```javascript
import Stripe from 'stripe';
const stripe = new Stripe('<<YOUR_PUBLISHABLE_KEY>>', {
  apiVersion: '2026-08-26.dahlia'
});
```

#### Go

由于 Go 是强类型编程语言，SDK 中使用的 API 版本是_固定的_，且为 SDK 发布时的最新 API 版本。

我们不建议为强类型编程语言设置不同的 API 版本，因为响应对象可能与 SDK 中的强类型不匹配，并导致请求失败。例如，如果您要针对的 API 版本需要 SDK 类型中不存在的参数，则请求会失败。

#### .NET

由于 C# 是强类型编程语言，.NET SDK 中使用的 API 版本是_固定的_，且为 SDK 发布时的最新 API 版本。

我们不建议为强类型编程语言设置不同的 API 版本，因为响应对象可能与 SDK 中的强类型不匹配，并导致请求失败。例如，如果您要针对的 API 版本需要 SDK 类型中不存在的参数，则请求会失败。

#### cURL

```sh
curl https://api.stripe.com/v1/charges \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-08-26.dahlia"
```

#### Stripe CLI

```sh
stripe charges create --stripe-version 2026-08-26.dahlia
```

## 更新代码以处理 API 变更

查看您最重要的请求并更新您的代码以处理响应中的变更。对于每一个请求，请查看[更新日志中的相关重大变更](https://docs.stripe.com/changelog.md?api_usage=true)，以了解采用您的目标版本所需的变更。

在 [Workbench](https://docs.stripe.com/workbench/overview.md) 的[概览选项卡](https://dashboard.stripe.com/workbench/overview)中查看您的 API 请求。

## 更新您的事件接收端

> API v1 资源的[精简事件](https://docs.stripe.com/event-destinations.md#thin-events)现已提供受邀预览版。您可以使用它们优化集成升级，而无需更改您的 Webhook 配置。此前，精简事件仅支持 API v2 资源。[了解详情并申请开通](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog)。

检查每个接收快照事件的事件接收端，包括 Webhook 端点以及 Amazon EventBridge 和 Azure Event Grid 的云目标。对于快照事件，事件接收端的 [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) 属性决定用于生成事件载荷的 API 版本。此设置独立于服务器端 SDK 使用的 API 版本。精简事件载荷不区分 API 版本。

只能在创建事件接收端时设置 `snapshot_api_version`。如需使用不同的 API 版本，请在删除现有事件接收端之前，创建并测试配置了该版本的事件接收端。如果在迁移过程中两个事件接收端均处于活动状态，则您的事件处理程序必须是幂等的，因为 Stripe 会将已订阅的事件发送到这两个事件接收端。

## 更新 Webhook 端点

要升级您的 Webhook 端点，您需要[验证传入 Webhook 的签名](https://docs.stripe.com/webhooks.md#verify-events)，并允许来自 Stripe [公共 IP 地址](https://docs.stripe.com/ips.md)的流量。您还需要创建新的端点，将流量重定向到这些端点，然后停用旧端点。

#### 创建新的已禁用 Webhook 端点

使用以下参数创建新的 Webhook 端点：

- `url`：与原始 Webhook 端点相同的 URL，但需要添加查询参数，以区分发送到这两个不同端点的事件。例如 `https://example.com/webhooks?version=2024-04-10`.
- `enabled_events`：与原始 Webhook 端点相同的事件。
- `api_version`：您希望升级到的 API 版本。如果要升级到最新的 API 版本，您可以使用管理平台或 API 来创建端点。对于其他版本，请使用 API 设置特定版本。

创建新的 Webhook 端点后，请将其禁用。您需要在下一步中重新启用它。
![有两个端点，但只有旧版端点在发送事件](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png)

#### 更新 Webhook 代码以忽略发送到新端点的事件

更新事件处理代码：

- 如果查询参数对应的是旧版 API，请照常处理。
- 如果查询参数对应的是新版 API，请忽略该事件并返回 200 响应，以防止投递重试。

接下来，启用您在上一步中创建的新 Webhook 端点。此时，每个事件都会被发送两次：一次使用旧版 API，一次使用新版本。
![两个端点都在发送事件，但只处理旧版事件](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png)

#### 更新 Webhook 代码以处理新端点的事件

更新事件处理代码：

- 如果查询参数对应的是旧版本，请忽略该事件。我们建议返回 400 状态码，以便 Stripe 自动重试该事件。这样可以确保当您需要回退时，事件会重新发送到旧的 Webhook 端点。
- 如果查询参数对应的是新版本，请处理该事件。
![两个端点都在发送事件，但只处理新版事件](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png)

#### 监控 Webhook 端点

监控发送到新 Webhook 端点的流量，以确认它们能够正确处理事件。

如果新代码无法正确处理事件，请尝试以下操作：

1. 将代码恢复到早期版本。
2. 暂时禁用新的 Webhook 端点。
3. 处理失败的事件（如果您按照上一步骤中的说明返回了 400 状态码，Stripe 会自动重新发送所有事件）。
4. 调查并修复问题。
5. 启用新的 Webhook 端点并恢复监控。

#### 禁用旧 Webhook 端点

升级成功后，请禁用旧的 Webhook 端点，以阻止您的服务器返回 `400` 状态码。如果不将其禁用，可能会对依赖 `200` 响应的集成造成问题。

禁用旧的 Webhook 端点后，Stripe 将不会重新投递返回 `400` 的事件。
![两个端点，但只有新端点在发送事件](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png)

## 测试并监控您的集成

在[沙盒](https://docs.stripe.com/sandboxes.md)中[测试您的集成](https://docs.stripe.com/testing.md)，以确认其按预期处理新版本。

除了通用测试指南外，请遵循您的集成所使用的产品和资源的指南：

- [Billing](https://docs.stripe.com/billing/testing.md)：使用[测试时钟](https://docs.stripe.com/billing/testing/test-clocks.md)来[模拟订阅](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md)。
- [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md)：测试 Webhook 通知、支付失败以及其他场景。
- [Connect](https://docs.stripe.com/connect/testing.md)：创建[测试账户](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts)并将其用于[验证测试](https://docs.stripe.com/connect/testing-verification.md)。
- [Terminal](https://docs.stripe.com/terminal/references/testing.md)：测试[模拟读卡器更新情况](https://docs.stripe.com/terminal/references/testing.md?terminal-card-present-integration=terminal#simulated-reader-updates)。
- [Payment Intents](https://docs.stripe.com/payments/quickstart-payment-intents.md#test-payment)：创建 PaymentIntents 并使用测试卡号来模拟支付。