# Guía para la migración de precios en Checkout Descubre cómo actualizar tu integración para usar precios con Stripe Checkout. La integración de la [API Prices](https://docs.stripe.com/api/prices.md) incluye lo siguiente: - Modelado unificado de los elementos de Checkout, en lugar de planes, *SKU* (SKUs (Stock Keeping Units) represent a specific Product variation, taking into account any combination of attributes and cost (for instance, size, color, currency, cost)) y partidas alineadas, ahora cada elemento es un *precio*. - Capacidad de renderizar imágenes de productos para ítems recurrentes. - La capacidad de crear un catálogo de productos y precios reutilizable, en lugar de partidas únicas. - La capacidad de crear precios alineados para las *suscripciones* (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). - Tasas impositivas dinámicas para [suscripciones](https://docs.stripe.com/billing/taxes/collect-taxes.md?tax-calculation=tax-rates#adding-tax-rates-to-checkout) y [pagos únicos](https://docs.stripe.com/payments/checkout/taxes.md). Si no quieres migrar, puedes seguir usando tu integración actual, pero no agregaremos nuevas funcionalidades. Puedes usar cualquier precio recurrente o plan nuevo que crees en el parámetro `plan` de tus llamadas API existentes. ## Resumen de productos y precios Los *precios* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) son una entidad básica dentro de Stripe que funciona con suscripciones, *facturas* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) y en Checkout. Cada precio está vinculado a un solo *producto* (Products represent what your business sells—whether that's a good or a service), y cada producto puede tener varios precios. Los diferentes bienes físicos o niveles de servicio se representan mediante productos. Los precios definen el precio de base, la moneda y el ciclo de facturación, en caso de productos recurrentes. Esto te permite cambiar y agregar precios sin necesidad de cambiar los datos de lo que ofreces. Por ejemplo, puedes tener un solo producto «estrella» a un precio de USD 10 por mes, USD 100 por año, EUR 9 por mes y EUR 90 por año. O bien, puedes tener una camiseta azul a USD 20 y a EUR 15. ## Pagos puntuales Las integraciones para pagos únicos tienen los siguientes cambios: - En lugar de ítems específicos (que definan, por ejemplo, el nombre, el importe y la moneda), la creación de una sesión de Checkout requiere un *producto* (Products represent what your business sells—whether that's a good or a service) y, por lo general, un *precio* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions). - Ahora, es necesario el [modo](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode). El código del lado del cliente sigue siendo el mismo. ### Tabla de asignaciones En lugar de definir cada campo en `line_items`, Checkout utiliza los objetos Product y Price subyacentes para determinar el nombre, la descripción, el importe, la moneda y las imágenes. Puedes [crear productos y precios](https://docs.stripe.com/payments/accept-a-payment.md) con la API o en el Dashboard. | Sin precios | Con precios | | --- | --- | | `line_items.name` | `product.name` | | `line_items.description` | `product.description` | | `line_items.amount` | - `price.unit_amount` - `price_data.unit_amount` (si se define al crear la sesión de Checkout) | | `line_items.currency` | - `price.currency` - `price_data.currency` (si se define al crear la sesión de Checkout) | | `line_items.images` | `product.images` (muestra la primera imagen suministrada) | ### Código del lado del servidor para ítems alineados Antes, solo podías crear ítems únicos alineados. Con precios, puedes seguir configurando ítems alineados, pero también puedes definir precios de forma dinámica con [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) al crear la sesión de Checkout. Cuando creas la sesión de Checkout con `price_data`, debes hacer referencia al ID de un producto existente con [price_data.product](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product) o definir los datos del producto dinámicamente usando [price_data.product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data). En el siguiente ejemplo se muestra el flujo para crear un ítem único. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price_data][unit_amount]"=2000 \ -d "line_items[0][price_data][product_data][name]"=T-shirt \ -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \ -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \ -d "line_items[0][price_data][currency]"=usd \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ### Código del lado del servidor para precios puntuales Con esta integración, puedes [crear un producto y un catálogo de precios](https://docs.stripe.com/payments/accept-a-payment.md) de antemano, en lugar de tener que definir el importe, la moneda y el nombre cada vez que crees una sesión de Checkout. Puedes crear un producto y un precio con la [API de precios](https://docs.stripe.com/api/prices.md) o mediante el [Dashboard](https://dashboard.stripe.com/products). Necesitarás el ID del precio para crear la sesión de Checkout. El siguiente ejemplo muestra cómo crear un producto y un precio a través de la API: #### curl ```bash curl https://api.stripe.com/v1/products \ -u<>: \ -d name=T-shirt \ -d description="Comfortable cotton t-shirt" \ -d "images[]"="https://example.com/t-shirt.png" curl https://api.stripe.com/v1/prices \ -u<>: \ -d product="{{PRODUCT_ID}}" \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ## Suscripciones Las integraciones para pagos recurrentes tienen los siguientes cambios: - Todos los ítems se especifican en un solo campo [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) en lugar de `subscription_data.items`. - Ahora, es necesario el [modo](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode). Define `mode=subscription` si la sesión incluye ítems recurrentes. El código del lado del cliente sigue siendo el mismo. Los planes existentes se pueden utilizar toda vez que se acepten precios recurrentes. ### Código del lado del servidor con planes Veamos un ejemplo de lo que se ve antes y después de crear una sesión de Checkout mediante una prueba y usando un plan existente, que también se puede usar con un precio. El plan ahora se especifica en `line_items` en lugar de `subscription_data.items`. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ### Código del lado del servidor para precio recurrente con costo de instalación Si tienes planes recurrentes con un costo de instalación único, crea el producto y el precio que representen la comisión única antes de crear la sesión de Checkout. Consulta la [tabla de asignaciones](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time) para ver cómo se asignan los campos `line_items` a esta integración. Puedes crear un producto y un precio a través de la [API Prices](https://docs.stripe.com/api/prices.md) o en el [Dashboard de Stripe](https://dashboard.stripe.com/products). También puedes [crear la partida única alineada](https://docs.stripe.com/payments/checkout/migrating-prices.md#server-side-code-for-inline-items). En el siguiente ejemplo, se utiliza un ID de precio existente: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \ -d "line_items[1][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ## Cambios en el objeto Response En lugar de enumerar ítems con `display_items`, el objeto Checkout Session utiliza `line_items`. El campo `line_items` no se renderiza en forma predeterminada como lo hacía `display_items`, pero puedes incluirlo utilizando [expandir](https://docs.stripe.com/api/expanding_objects.md) al crear una sesión de proceso de compra: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="card" \ -d "mode"="payment" \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "success_url"="https://example.com/success" \ -d "expand[]"="line_items" ``` ## Cambios en los webhooks Debido a que se puede incluir `line_items`, la respuesta de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) de `checkout.session.completed` ya no enumera las partidas de forma predeterminada. El objeto Response más pequeño te permite recibir los webhooks de Checkout más rápido. Puedes recuperar partidas con el nuevo punto de conexión de `line_items`: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \ -u <>: ``` Para obtener más detalles, consulta [cómo completar pedidos con Checkout](https://docs.stripe.com/checkout/fulfillment.md).