Guía para la migración de precios en Checkout

La API Prices agrega nuevas funcionalidades y te da flexibilidad para cobrar a tus clientes. Esta nueva integración ofrece lo siguiente:

• Modelado más unificado de los elementos de Checkout (en lugar de planes, SKU e ítems alineados, ahora cada elemento es un precio).
• Capacidad de renderizar imágenes de productos para ítems recurrentes.
• Crear un catálogo de productos y precios reutilizable en lugar de partidas únicas.
• Crea precios en línea para las suscripciones.
• Aplica tasas impositivas dinámicas a las suscripciones y los pagos únicos.

¿No quieres migrar? Puedes seguir usando tu integración actual, pero no se admiten nuevas funcionalidades. Puedes utilizar cualquier plan o precio recurrente nuevo que crees en el parámetro plan de tus actuales llamadas a la API.

Resumen de productos y precios

Los precios son una nueva entidad básica dentro de Stripe que funciona con suscripciones, facturas y en Checkout. Cada precio está vinculado a un solo producto, y cada producto puede tener varios precios. Los diferentes bienes físicos o niveles de servicio deben representarse mediante productos. El valor de cada producto debe representarse mediante precios.

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/mes, USD 100/año, EUR 9/mes y EUR 90/año. O puedes tener una camiseta azul a USD 20 y a EUR 15.

Pagos puntuales

Las integraciones para pagos únicos tienen los siguientes cambios:

• Instead of ad-hoc line items (that is, setting the name, amount, and currency), creating a Checkout Session requires creating a product and, usually, a price.
• Ahora, es necesario el modo.

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 con la API o en el Dashboard.

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 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 o definir los datos del producto dinámicamente usando price_data.product_data. En el siguiente ejemplo se muestra el flujo para crear un ítem único.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -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" \
  -d cancel_url="https://example.com/cancel"

Código del lado del servidor para precios puntuales

Con esta nueva integración, puedes crear un producto y un catálogo de precios 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 Prices o a través del Dashboard. Necesitarás el ID del precio para crear la sesión de Checkout. En el siguiente ejemplo se muestra cómo crear un producto y un precio a través de la API:

curl https://api.stripe.com/v1/products \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Suscripciones

Las integraciones para pagos recurrentes tienen los siguientes cambios:

• Todos los ítems se especifican en un solo campo line_items en lugar de subscription_data.items.
• Ahora, es necesario el modo. 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 https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

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 el costo único antes de crear la sesión de Checkout. Consulta la tabla de asignaciones para ver cómo se asignan los campos line_items anteriores a la nueva integración. Puedes crear un producto y un precio a través de la API Prices o a través del Dashboard de Stripe. También puedes crear el ítem único alineado. En el siguiente ejemplo se utiliza un ID de precio existente:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

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 al crear una sesión de Checkout:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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 "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Cambios en los webhooks

Debido a que se puede incluir line_items, la respuesta de webhook checkout.session.completed ya no menciona los ítems en forma predeterminada. El objeto Response más pequeño te permite recibir los webhooks de Checkout más rápido. Puedes recuperar ítems con el nuevo punto de conexión de line_items:

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Para obtener más detalles, consulta cómo completar pedidos con Checkout.