Skip to main content

Checkout Sessions

Crea un checkout seguro y alojado para pagos únicos y suscripciones.

Payment Links

Comparte una URL para cobrar pagos sin código.

Webhooks

Escucha eventos de pago y completa los pedidos.

API Reference

Documentación completa de endpoints y pruebas en vivo.

Requisitos previos

Antes de comenzar, necesitas:
  • Una cuenta de Dodo Payments.
  • Al menos un producto. Créalo en Products en el dashboard. Un producto de suscripción con un precio distinto de cero debe cumplir el mínimo de suscripción para la moneda en la que paga el cliente: $1.00 para USD. Las monedas distintas de USD, EUR y GBP también deben tener un valor de al menos $1.00. También se admite una suscripción de $0.
  • Una API key. Créala en Developer → API Keys y guárdala en la variable de entorno DODO_PAYMENTS_API_KEY. Crea la key en modo de prueba mientras desarrollas: los ejemplos de esta página usan el modo de prueba, y una key de modo de prueba solo funciona con el modo de prueba. Consulta Authentication.
  • El SDK de tu lenguaje. El SDK de Node.js requiere Node.js 20 o posterior, el SDK de Python requiere Python 3.9 o posterior, y el SDK de Go requiere Go 1.22 o posterior. Los ejemplos de cURL no necesitan ningún SDK.
El ejemplo de webhook también utiliza el paquete standardwebhooks. Instálalo con npm install standardwebhooks.

Elige una ruta de integración

El checkout superpuesto y el checkout integrado solo funcionan en una página web. En una aplicación móvil nativa, crea la sesión de checkout en tu servidor y abre su checkout_url con un SDK de checkout móvil. Para que un agente de programación cree esta integración por ti, instala el Agent Plugin.

Sesiones de Checkout

Crea una experiencia de checkout segura y alojada. Creas una sesión en tu servidor y, después, rediriges al cliente al checkout_url devuelto.
Cada checkout_url funciona una vez y caduca después de 24 horas, o después de 15 minutos cuando pasas confirm: true. Con confirm: true, también debes proporcionar todos los campos obligatorios. Crea una sesión nueva para cada cliente y cada intento de pago.

Crear una sesión de Checkout

Redirigir a Checkout

Después de crear una sesión, redirige al cliente al checkout_url:
Para una personalización avanzada, consulta la guía completa de Sesiones de Checkout y la API Reference.

Gestionar errores

Cuando una solicitud falla, la API devuelve un código de estado HTTP y un cuerpo JSON con un code y un message. Basa la gestión de errores en code, no en message. Para consultar cada código, su causa y cómo resolverlo, visita Códigos de error. Un pago fallido se informa por separado: el status del pago es failed, su error_code indica el motivo y recibes un webhook payment.failed. Para decidir si debes reintentar, consulta Gestionar fallos de pago. Un payment link es una URL que abre checkout para un producto, por lo que puedes cobrar pagos sin escribir código. Los parámetros de consulta rellenan previamente los datos del cliente y controlan el formulario de checkout. Cuando un cliente abre el link, checkout almacena los parámetros en una sesión y acorta la URL a un parámetro session, de modo que se conservan aunque se recargue la página. Un payment link estático es una URL que creas una vez y compartes varias veces. La URL base es:
Añade parámetros de consulta para personalizar el checkout:
integer
predeterminado:"1"
Número de artículos que se comprarán.
string
requerido
Los payment links utilizan redirect_url. La API de Checkout Sessions utiliza return_url para el mismo propósito.URL a la que se redirige después del pago. Dodo Payments añade los detalles del pago como parámetros de consulta, por ejemplo https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Si el producto emite license keys, también se añade un parámetro license_key, con varias keys separadas por comas.
string
Especifica la moneda del pago. De forma predeterminada, usa la moneda del país de facturación.
boolean
predeterminado:"true"
Muestra u oculta el selector de moneda.
boolean
predeterminado:"true"
Muestra u oculta la sección de descuentos. Establécelo en false para impedir que los clientes introduzcan códigos de cupón.
number
Fija el importe cobrado, en unidades monetarias principales; por ejemplo, 12.5 para $12.50. Solo funciona con productos Pay What You Want y se ignora si está por debajo del precio mínimo del producto.
paymentAmount utiliza unidades monetarias principales (12.5 equivale a $12.50). El campo product_cart[].amount de la API de Checkout Sessions utiliza la unidad monetaria más pequeña (1250 equivale a $12.50). Consulta Precios dinámicos.
string
Campos de metadata personalizados, por ejemplo metadata_orderId=123.

Rellenar previamente la información del cliente

Añade campos del cliente como parámetros de consulta para agilizar el checkout:
string
Nombre completo del cliente (se ignora si se proporciona firstName o lastName).
string
Nombre del cliente.
string
Apellido del cliente.
string
Dirección de correo electrónico del cliente.
string
País del cliente (código ISO 3166-1 alpha-2).
string
Dirección.
string
Ciudad.
string
Estado o provincia.
string
Código postal o ZIP.

Desactivar campos del formulario

Para impedir que los clientes modifiquen la información rellenada previamente, desactiva un campo proporcionando su valor y estableciendo el flag disable... correspondiente en true:
La desactivación de campos evita cambios accidentales y garantiza la coherencia de los datos.
Los endpoints POST /payments y POST /subscriptions están obsoletos. Para las nuevas integraciones, utiliza Checkout Sessions.
Para las integraciones existentes que utilizan payment links dinámicos, pasa payment_link: true a Crear un pago único o Crear una suscripción para crear un link. Los ejemplos siguientes crean un payment link de un solo uso. Para las suscripciones, consulta la Guía de integración de suscripciones.

Webhooks

Los webhooks indican a tu servidor cuándo un pago se realiza correctamente o falla, para que puedas completar el pedido.

Crear un endpoint de webhook

Ve a Developer → Webhooks en el dashboard y añade la URL de tu endpoint. Copia el signing secret del endpoint en la variable de entorno DODO_PAYMENTS_WEBHOOK_KEY. Este es un ejemplo con Next.js:
app/api/webhooks/dodo/route.ts
Nuestra implementación de webhook sigue la especificación de Standard Webhooks.

Eventos que debes escuchar

Como mínimo, escucha estos eventos en un flujo de pago único:
Completa siempre el pedido cuando recibas payment.succeeded del webhook, no cuando se produzca la redirección del navegador. La redirección puede omitirse si el cliente cierra la pestaña, mientras que el webhook se reintenta hasta que se confirma su recepción.
Si vendes productos con license keys, gestiona también license_key.created. Para consultar la lista completa de eventos, incluidos los eventos de suscripción, entitlement, crédito, recuperación y dunning, visita la Guía de eventos de webhook. Para consultar un ejemplo completo con Next.js y TypeScript, visita el repositorio de demostración y su implementación activa.

Moneda y dirección de facturación

Para cobrar en una moneda específica, pasa billing_currency y billing_address.country al crear la sesión de checkout. Si los omites, Adaptive Currency elige la moneda y el país a partir de la dirección IP del cliente, que puede no corresponderse con la moneda en la que quieres cobrar. Los importes de Pay What You Want se expresan en la moneda base del producto, que debe ser USD, GBP o EUR. Para cobrar un importe fijo en otra moneda, utiliza Adaptive Currency, que convierte el precio base según los tipos de cambio actuales, o Precios localizados, que establece un precio fijo por moneda. Los precios localizados no funcionan con Pay What You Want.

Compra repetida con un clic

Para cobrar a un cliente recurrente con un método de pago guardado, pasa su payment_method_id junto con confirm: true. payment_method_id solo se acepta cuando confirm es true, y también debes pasar el customer_id existente del cliente. Puesto que confirm es true, también debes pasar un billing_address completo, o únicamente country y zipcode cuando minimal_address sea true. La sesión cobra directamente el método de pago guardado, por lo que no devuelve ningún checkout_url. Utiliza webhooks para saber si el pago se realizó correctamente.

Páginas relacionadas

Checkout Sessions

Guía completa con opciones de personalización avanzadas.

Overlay Checkout

Inserta checkout como un overlay modal en tu página.

Inline Checkout

Inserta checkout directamente en el diseño de tu página.

Subscription Integration

Configura la facturación recurrente.

Webhook Event Guide

Lista completa de todos los eventos de webhook.

API Reference

Documentación de la API de Checkout Sessions.
Última modificación el 26 de septiembre de 2026