# Actualiza tu integración Actualiza tu integración a la última versión de la API. Consulta el [Registro de cambios para desarrolladores](https://docs.stripe.com/changelog.md) a fin de ver el historial completo de cambios en la API de Stripe. Para actualizar tu integración, completa los siguientes pasos. Busca en el [Registro de cambios](https://docs.stripe.com/changelog.md?api_usage=true) la información específica de tu integración. ## Define la versión de destino para tu actualización Asegúrate de especificar en tu código la versión de la API con la que estás realizando la integración en lugar de depender de la versión predeterminada de la API de tu cuenta. Para probar una versión más reciente en las llamadas API, configura el encabezado `Stripe-Version` (en entornos activos o de prueba). Descubre cómo [configurar una versión de la API en nuestros SDK del lado del servidor](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Consulta qué versiones de la API utiliza tu integración en la pestaña [Resumen](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). Revisa el [Registro de cambios](https://docs.stripe.com/changelog.md) para encontrar la versión de destino de tu actualización. ## Especifica la versión de la API en tu SDK Tu cuenta tiene una *versión de la API predeterminada* (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 cómo llamas a la API, a qué funcionalidades tienes acceso y la estructura de las respuestas de la API. Cuando usas un [SDK del lado del servidor](https://docs.stripe.com/sdks.md#server-side-libraries), tus llamadas API a Stripe usan la versión de la API que estaba vigente cuando se lanzó el SDK. No puedes orientar una versión de la API diferente cuando usas un lenguaje con establecimiento inflexible de tipos, como Java, Go o .NET. #### Ruby La biblioteca [stripe-ruby](https://github.com/stripe/stripe-ruby) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-ruby usan la versión de la API que era más reciente en el momento en que se lanzó tu versión de stripe-ruby. Las versiones de stripe-ruby anteriores a [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) usan la versión de la API predeterminada de tu cuenta. Para configurar la versión de la API **de forma global** con el SDK, asigna la versión a la propiedad `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') ``` O bien, configura la versión por solicitud: ```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 ``` > Si sustituyes la versión de forma global o por solicitud, los objetos de respuesta de la API también se devuelven en esa versión. #### Python La biblioteca [stripe-python](https://github.com/stripe/stripe-python) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-python usan la versión de la API que era más reciente en el momento en que se lanzó tu versión de stripe-python. Las versiones de stripe-python anteriores a [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) usan la versión de la API predeterminada de tu cuenta. Para configurar la versión de la API **de forma global** con el SDK, asigna la versión a la propiedad `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' ``` O bien, configura la versión por solicitud: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Si sustituyes la versión de forma global o por solicitud, los objetos de respuesta de la API también se devuelven en esa versión. #### PHP La biblioteca [stripe-php](https://github.com/stripe/stripe-php) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-php usan la versión de la API que era más reciente en el momento en que se lanzó tu versión de stripe-php. Las versiones de stripe-php anteriores a [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) usan la versión de la API predeterminada de tu cuenta. Para configurar la versión de la API **de forma global** con el SDK, pasa la versión al 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" ]); ``` O bien, configura la versión por solicitud: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Si sustituyes la versión de forma global o por solicitud, los objetos de respuesta de la API también se devuelven en esa versión. #### Java Como Java es un lenguaje de programación con establecimiento inflexible de tipos, la versión de la API utilizada en el SDK es *fija* y es la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación con establecimiento inflexible de tipos porque los objetos de respuesta podrían no coincidir con los tipos inflexibles del SDK y provocar errores en la solicitud. Por ejemplo, si la versión de la API a la que apuntas requiere parámetros que no están presentes en los tipos del SDK, la solicitud fallará. #### Node La biblioteca [stripe-node](https://github.com/stripe/stripe-node) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-node usarán la versión de la API que era más reciente en el momento en que se lanzó tu versión de stripe-node. Las versiones de stripe-node anteriores a [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) usan la versión de la API predeterminada de tu cuenta. Para configurar la versión de la API **de forma global** con el SDK, proporciona la opción `apiVersion`: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` O bien, configura la versión por solicitud: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Uso de TypeScript Los tipos de TypeScript reflejan la última versión de la API en el momento del lanzamiento. Esta versión está codificada en el [archivo API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Importa Stripe como importación predeterminada y crea una instancia como `new Stripe()` con la última versión de la API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Go Como Go es un lenguaje de programación con establecimiento inflexible de tipos, la versión de la API utilizada en el SDK es *fija* y es la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación con establecimiento inflexible de tipos porque los objetos de respuesta podrían no coincidir con los tipos inflexibles del SDK y provocar errores en la solicitud. Por ejemplo, si la versión de la API a la que apuntas requiere parámetros que no están presentes en los tipos del SDK, la solicitud fallará. #### .NET Como C# es un lenguaje de programación con establecimiento inflexible de tipos, la versión de la API utilizada en el SDK .NET es *fija* y es la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación con establecimiento inflexible de tipos porque los objetos de respuesta podrían no coincidir con los tipos inflexibles del SDK y provocar errores en la solicitud. Por ejemplo, si la versión de la API a la que apuntas requiere parámetros que no están presentes en los tipos del SDK, la solicitud fallará. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### CLI de Stripe ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Actualiza tu código para manejar los cambios de la API Revisa tus solicitudes más importantes y actualiza tu código con el objetivo de manejar los cambios en la respuesta. En cada solicitud, revisa los [cambios rotundos importantes en el registro de cambios](https://docs.stripe.com/changelog.md?api_usage=true) a fin de comprender las modificaciones que se deben implementar para adoptar tu versión de destino. Consulta tus solicitudes de la API en la pestaña [Resumen](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). ## Actualiza tus destinos de eventos > Los [eventos breves](https://docs.stripe.com/event-destinations.md#thin-events) para los recursos de la API v1 están disponibles en su versión preliminar privada. Puedes usarlos para agilizar las actualizaciones de la integración sin cambiar la configuración de tu webhook. Anteriormente, los eventos breves solo admitían recursos de la API v2. [Obtén más información y solicita acceso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Revisa cada destino de eventos que recibe eventos con instantánea, incluidos los puntos de conexión de webhook y los destinos en la nube de Amazon EventBridge y Azure Event Grid. Para los eventos con instantánea, la propiedad [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) del destino controla la versión de la API que se usa para generar la carga del evento. Esta configuración es independiente de la versión de la API que usa el SDK del servidor. Las cargas de los eventos breves no tienen una versión asociada. Solo puedes configurar la `snapshot_api_version` cuando creas un destino de eventos. Para usar una versión diferente de la API, crea y prueba un destino configurado con esa versión antes de eliminar el destino existente. Si ambos destinos están activos durante la migración, tu controlador de eventos debe ser idempotente porque Stripe entrega los eventos a los que estás suscrito a ambos destinos. ## Actualiza tus puntos de conexión de webhook Para actualizar los puntos de conexión de tu webhook, debes [verificar las firmas de los webhooks entrantes](https://docs.stripe.com/webhooks.md#verify-events) y permitir el tráfico desde las [direcciones IP públicas](https://docs.stripe.com/ips.md) de Stripe. También debes crear nuevos puntos de conexión, redirigir el tráfico hacia ellos y, luego, desactivar los antiguos. #### Crea nuevos puntos de conexión de webhook deshabilitados Crea un nuevo punto de conexión de webhook con los siguientes parámetros: - `url`: la misma URL que tu punto de conexión de webhook original, pero agrega un parámetro de consulta para distinguir entre los eventos enviados a los dos puntos de conexión diferentes. Por ejemplo, `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: los mismos eventos que tu punto de conexión de webhook original. - `api_version`: la versión de la API a la que quieres realizar la actualización. Si vas a actualizar a la última versión de la API, puedes usar el Dashboard o la API para crear el punto de conexión. Para otras versiones, usa la API a fin de establecer una versión específica. Después de crear el nuevo punto de conexión de webhook, deshabilítalo. Lo volverás a habilitar en el próximo paso. ![Dos puntos de conexión, pero solo el antiguo está enviando eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Actualiza el código de tu webhook para ignorar los eventos que se envían al nuevo punto de conexión Actualiza tu código de procesamiento de eventos: - Si el parámetro de consulta es para la versión anterior de la API, procésalo como de costumbre. - Si el parámetro de consulta es para la versión más nueva de la API, ignora el evento y devuelve una respuesta de 200 para evitar los reintentos de entrega. A continuación, habilita el nuevo punto de conexión de webhook que creaste en el paso anterior. En este punto, cada evento se envía dos veces: una con la versión anterior de la API y otra con la nueva. ![Dos puntos de conexión que envían eventos, pero solo se procesa el antiguo](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Actualiza el código de tu webhook para procesar los eventos de los nuevos puntos de conexión Actualiza tu código de proceso de eventos: - Si el parámetro de consulta es para la versión anterior, ignora el evento. Te recomendamos que devuelvas un estado 400 para que Stripe vuelva a procesar automáticamente el evento. Esto garantiza que, si tienes que deshacer los cambios, los eventos se vuelvan a enviar al webhook del punto de conexión anterior. - Si el parámetro de consulta es para la nueva versión, procésalo. ![Dos puntos de conexión envían eventos, pero solo se procesa el nuevo](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Monitorea tus puntos de conexión de webhook Monitorea el tráfico de los nuevos puntos de conexión de webhook para confirmar que procesan los eventos correctamente. Si los eventos no se manejan correctamente con tu nuevo código, prueba lo siguiente: 1. Vuelve a la versión anterior de tu código. 2. Deshabilita temporalmente el nuevo punto de conexión de webhook. 3. Procesa los eventos con error (si devolviste un estado 400 como se describe en el paso anterior, Stripe vuelve a enviar automáticamente todos los eventos). 4. Investiga y soluciona el problema. 5. Activa el nuevo punto de conexión de webhook y reanuda el monitoreo. #### Deshabilita el punto de conexión antiguo de webhook Una vez que la actualización se realice correctamente, deshabilita el punto de conexión antiguo de webhook para evitar que tu servidor devuelva un estado `400`. Si no lo deshabilitas, esto puede causar problemas con las integraciones que dependen de una respuesta de `200`. Después de deshabilitar el punto de conexión antiguo de webhook, Stripe no volverá a entregar los eventos que devolvieron un estado `400`. ![Dos puntos de conexión, pero solo el nuevo está enviando eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Prueba y supervisa tu integración [Prueba tu integración](https://docs.stripe.com/testing.md) en un [entorno de prueba](https://docs.stripe.com/sandboxes.md) para confirmar que maneja la nueva versión según lo previsto. Además de la guía general sobre pruebas, sigue estas pautas para los productos y recursos que utiliza tu integración: - [Billing](https://docs.stripe.com/billing/testing.md): usa [clocks de prueba](https://docs.stripe.com/billing/testing/test-clocks.md) para [simular suscripciones](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): prueba notificaciones de webhooks, errores en los pagos y otros escenarios. - [Connect](https://docs.stripe.com/connect/testing.md): crea [cuentas de prueba](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) y utilízalas para [pruebas de verificación](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): prueba [actualizaciones de lector simulado](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): crea PaymentIntents y utiliza números de tarjeta de prueba para simular pagos.