# Atualize sua integração Atualize sua integração para a versão mais recente da API. Confira o [Changelog do desenvolvedor](https://docs.stripe.com/changelog.md) para o registro completo de alterações na API da Stripe. Para atualizar sua integração, conclua as etapas a seguir. Consulte o [Changelog](https://docs.stripe.com/changelog.md?api_usage=true) para obter informações específicas sobre sua integração. ## Defina a versão de destino para sua atualização Certifique-se de especificar no seu código a versão da API com a qual você está se integrando, em vez de depender da versão padrão da API da sua conta. Para testar uma versão mais recente para chamadas da API, defina o cabeçalho `Stripe-Version` (em ambientes de produção ou de teste). Saiba como [definir uma versão da API em nossos SDKs do lado do servidor](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Veja quais versões da API sua integração usa na aba [Visão geral](https://dashboard.stripe.com/workbench/overview) do [Workbench](https://docs.stripe.com/workbench/overview.md). Consulte o [Changelog](https://docs.stripe.com/changelog.md) para encontrar a versão de destino da sua atualização. ## Especifique a versão da API no seu SDK Sua conta tem uma *versão padrão da 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) que define como você chama a API, quais funções você pode acessar e a estrutura das respostas da API. Ao usar um [SDK do lado do servidor](https://docs.stripe.com/sdks.md#server-side-libraries), suas chamadas da API para a Stripe usam a versão da API que estava vigente quando o SDK foi lançado. Você não pode direcionar uma versão diferente da API ao usar uma linguagem fortemente tipada, como Java, Go ou .NET. #### Ruby A biblioteca [stripe-ruby](https://github.com/stripe/stripe-ruby) permite que você defina a versão da API globalmente ou por solicitação. Se você não definir uma versão da API, as versões recentes do stripe-ruby usarão a versão da API que era a mais recente no momento em que a sua versão do stripe-ruby foi lançada. As versões do stripe-ruby anteriores à [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) usam a versão padrão da API da sua conta. Para definir a versão da API **globalmente** com o SDK, atribua a versão à propriedade: `Stripe.api_version` ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>', stripe_version: '2026-08-26.dahlia') ``` Ou defina a versão por solicitação: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>') intent = client.v1.payment_intents.retrieve( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', { stripe_version: '2026-08-26.dahlia', }, ) intent.capture ``` > Quando você substitui a versão globalmente ou por solicitação, os objetos de resposta da API também são retornados nessa versão. #### Python A biblioteca [stripe-python](https://github.com/stripe/stripe-python) permite definir a versão da API globalmente ou por solicitação. Se você não definir uma versão da API, as versões recentes do stripe-python usarão a versão da API que era a mais recente no momento em que a sua versão do stripe-python foi lançada. As versões do stripe-python anteriores à [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) usam a versão padrão da API da sua conta. Para definir a versão da API **globalmente** com o SDK, atribua a versão à propriedade `stripe.api_version`: ```python import stripe # Don't put any keys in code. See /keys-best-practices. stripe.api_key = <> stripe.api_version = '2026-08-26.dahlia' ``` Ou defina a versão por solicitação: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Quando você substitui a versão globalmente ou por solicitação, os objetos de resposta da API também são retornados nessa versão. #### PHP A biblioteca [stripe-php](https://github.com/stripe/stripe-php) permite que você defina a versão da API globalmente ou por solicitação. Se você não definir uma versão da API, as versões recentes do stripe-php usarão a versão da API que era a mais recente no momento em que a sua versão do stripe-php foi lançada. As versões do stripe-php anteriores à [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) usam a versão padrão da API da sua conta. Para definir a versão da API **globalmente** com o SDK, passe a versão para o método: `\Stripe\Stripe::setApiVersion()` ```php $stripe = new \Stripe\StripeClient([ // Don't put any keys in code. See /keys-best-practices. "api_key" => "<>", "stripe_version" => "2026-08-26.dahlia" ]); ``` Ou defina a versão por solicitação: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Quando você substitui a versão globalmente ou por solicitação, os objetos de resposta da API também são retornados nessa versão. #### Java Como Java é uma linguagem de programação fortemente tipada, a versão da API usada no SDK é *fixa* e corresponde à versão mais recente da API no momento do lançamento do SDK. Não recomendamos definir uma versão diferente da API para linguagens de programação fortemente tipadas, pois os objetos de resposta podem não corresponder aos tipos fortemente tipados no SDK, resultando em falhas nas solicitações. Por exemplo, se a versão da API que você está direcionando exigir parâmetros que não estão presentes nos tipos do SDK, a solicitação falhará. #### Node A biblioteca [stripe-node](https://github.com/stripe/stripe-node) permite definir a versão da API globalmente ou por solicitação. Se você não definir uma versão da API, as versões recentes do stripe-node usarão a versão da API que era a mais recente no momento em que a sua versão do stripe-node foi lançada. As versões do stripe-node anteriores à [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) usam a versão padrão da API da sua conta. Para definir a versão da API **globalmente** com o SDK, forneça a opção `apiVersion`: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` Ou defina a versão por solicitação: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Uso com Typescript Os tipos do TypeScript refletem a versão mais recente da API no momento do lançamento. Essa versão é definida no [arquivo API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Importe a Stripe como uma importação padrão e instancie-a como `new Stripe()` com a versão mais recente da API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Acesse Como Go é uma linguagem de programação fortemente tipada, a versão da API usada no SDK é *fixa* e corresponde à versão mais recente da API no momento do lançamento do SDK. Não recomendamos definir uma versão diferente da API para linguagens de programação fortemente tipadas, pois os objetos de resposta podem não corresponder aos tipos fortemente tipados no SDK, resultando em falhas nas solicitações. Por exemplo, se a versão da API que você está direcionando exigir parâmetros que não estão presentes nos tipos do SDK, a solicitação falhará. #### .NET Como C# é uma linguagem de programação fortemente tipada, a versão da API usada no SDK .NET é *fixa* e corresponde à versão mais recente da API no momento do lançamento do SDK. Não recomendamos definir uma versão diferente da API para linguagens de programação fortemente tipadas, pois os objetos de resposta podem não corresponder aos tipos fortemente tipados no SDK, resultando em falhas nas solicitações. Por exemplo, se a versão da API que você está direcionando exigir parâmetros que não estão presentes nos tipos do SDK, a solicitação falhará. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### Stripe CLI ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Atualize seu código para lidar com alterações na API Revise suas solicitações mais importantes e atualize seu código para lidar com as alterações na resposta. Para cada solicitação, revise as [alterações incompatíveis relevantes no changelog](https://docs.stripe.com/changelog.md?api_usage=true) para entender as mudanças necessárias para adotar sua versão de destino. Visualize suas solicitações de API na aba [Visão geral](https://dashboard.stripe.com/workbench/overview) do [Workbench](https://docs.stripe.com/workbench/overview.md). ## Atualize seus destinos de eventos > Os [eventos thin](https://docs.stripe.com/event-destinations.md#thin-events) para recursos da API v1 estão disponíveis em prévia privada. Você pode usá-los para simplificar as atualizações de integração sem alterar a configuração do seu webhook. Anteriormente, os eventos thin eram compatíveis apenas com recursos da API v2. [Saiba mais e solicite acesso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Revise cada destino de evento que recebe eventos de snapshot, incluindo endpoints de webhook e destinos de nuvem para o Amazon EventBridge e o Azure Event Grid. Para eventos de snapshot, a propriedade [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) do destino controla a versão da API usada para renderizar o payload do evento. Essa configuração é independente da versão da API usada pelo SDK do servidor. Os payloads de eventos thin não são versionados. Você só pode definir `snapshot_api_version` ao criar um destino de evento. Para usar uma versão de API diferente, crie e teste um destino configurado com essa versão antes de excluir o destino existente. Se ambos os destinos estiverem ativos durante a migração, o manipulador de eventos deve ser idempotente, pois a Stripe entrega os eventos assinados para ambos os destinos. ## Atualize seus endpoints de webhook Para atualizar os endpoints do seu webhook, você precisa [verificar as assinaturas de webhook recebidas](https://docs.stripe.com/webhooks.md#verify-events) e permitir o tráfego dos [endereços IP públicos](https://docs.stripe.com/ips.md) da Stripe. Também é preciso criar novos endpoints, redirecionar o tráfego para eles e desabilitar os endpoints antigos. #### Crie novos endpoints de webhook desativados Crie um novo endpoint de webhook com os seguintes parâmetros: - `url`: a mesma URL do seu endpoint de webhook original, mas adicione um parâmetro de consulta para diferenciar os eventos enviados aos dois endpoints. Por exemplo, `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: os mesmos eventos do seu endpoint de webhook original. - `api_version`: a versão da API para a qual você deseja fazer a atualização. Se estiver atualizando para a versão mais recente da API, você pode usar o Dashboard ou a API para criar o endpoint. Para outras versões, use a API para definir uma versão específica. Depois de criar o novo endpoint de webhook, desative-o. Você o reativará na próxima etapa. ![Dois endpoints, mas apenas o antigo está enviando eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Atualize seu código de webhook para ignorar os eventos enviados ao novo endpoint Atualize seu código de processamento de eventos: - Se o parâmetro de consulta for referente à versão mais antiga da API, processe-o normalmente. - Se o parâmetro de consulta for referente à versão mais recente da API, ignore o evento e retorne uma resposta 200 para evitar novas tentativas de entrega. Em seguida, ative o novo endpoint de webhook que você criou na etapa anterior. Nesse momento, cada evento será enviado duas vezes: uma vez com a versão antiga da API e outra com a versão mais recente. ![Dois endpoints enviando eventos, mas apenas o antigo os processando](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Atualize seu código de webhook para processar eventos dos novos endpoints Atualize seu código de processamento de eventos: - Se o parâmetro de consulta for referente à versão mais antiga, ignore o evento. Recomendamos retornar um status 400 para que a Stripe tente reenviar o evento automaticamente. Isso garante que, se você precisar reverter a alteração, os eventos sejam reenviados para o endpoint de webhook mais antigo. - Se o parâmetro de consulta for referente à nova versão, processe o evento. ![Dois endpoints enviando eventos, mas apenas o novo os processando](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Monitore seus endpoints de webhook Monitore o tráfego para os novos endpoints de webhook para confirmar que eles processam os eventos corretamente. Se os eventos não estiverem sendo processados corretamente pelo seu novo código, tente o seguinte: 1. Reverta para a versão anterior do seu código. 2. Desative temporariamente o novo endpoint de webhook. 3. Processe os eventos que falharam (se você retornou um status 400 conforme descrito na etapa anterior, a Stripe reenviará automaticamente todos os eventos). 4. Investigue e corrija o problema. 5. Ative o novo endpoint de webhook e retome o monitoramento. #### Desative o endpoint de webhook antigo Após a atualização ser concluída com sucesso, desative o endpoint de webhook antigo para impedir que seu servidor continue retornando o status `400`. Se você não o desativar, isso poderá causar problemas nas integrações que dependem de uma resposta `200`. Depois que você desativar o endpoint de webhook antigo, a Stripe não reenviará os eventos que retornaram um `400`. ![Dois endpoints, mas apenas o novo está enviando eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Teste e monitore sua integração [Teste sua integração](https://docs.stripe.com/testing.md) em uma [área restrita](https://docs.stripe.com/sandboxes.md) para confirmar que ela consegue llidar com a nova versão conforme o esperado. Além das orientações gerais de teste, siga as orientações para os produtos e recursos que sua integração utiliza: - [Billing](https://docs.stripe.com/billing/testing.md): use [clocks de teste](https://docs.stripe.com/billing/testing/test-clocks.md) para [simular assinaturas](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): teste notificações de webhook, falhas de pagamento e outros cenários. - [Connect](https://docs.stripe.com/connect/testing.md): crie [contas de teste](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) e use-as para [testes de verificação](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): teste [atualizações simuladas de máquinas](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): crie PaymentIntents e use números de cartão de teste para simular pagamentos.