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.
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 alcheckout_url devuelto.
Crear una sesión de Checkout
- Node.js SDK
- Python SDK
- cURL
Redirigir a Checkout
Después de crear una sesión, redirige al cliente alcheckout_url:
Gestionar errores
Cuando una solicitud falla, la API devuelve un código de estado HTTP y un cuerpo JSON con uncode 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.
Payment Links
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ámetrosession, de modo que se conservan aunque se recargue la página.
Payment Links estáticos
Un payment link estático es una URL que creas una vez y compartes varias veces. La URL base es: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.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 flagdisable... correspondiente en true:
Ejemplo de payment link estático
Payment Links dinámicos (obsoletos)
Para las integraciones existentes que utilizan payment links dinámicos, pasapayment_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.
- Node.js SDK
- Python SDK
- Go SDK
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 entornoDODO_PAYMENTS_WEBHOOK_KEY.
Este es un ejemplo con Next.js:
app/api/webhooks/dodo/route.ts
Eventos que debes escuchar
Como mínimo, escucha estos eventos en un flujo de pago único:
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, pasabilling_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 supayment_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.