Referencia de API - Dodo Payments Documentation

SDKs & Libraries

SDK oficiales de backend para TypeScript, Python, Go, PHP, Java, Kotlin, C#, Ruby y Rust. Estas bibliotecas gestionan la autenticación, la serialización y el manejo de errores para que puedas concentrarte en tu integración.

Mobile Checkout SDKs

Abre el checkout alojado de Dodo desde aplicaciones de Android, iOS, React Native y Flutter, y recibe un resultado tipado en una sola llamada. Estos SDK no contienen ninguna API key.

URL de entorno

Modo de prueba: https://test.dodopayments.com
Modo activo: https://live.dodopayments.com

Obtén más información sobre el modo de prueba y el modo activo.

Autenticación

Las solicitudes a la API requieren una clave de API, excepto algunos endpoints públicos, como Activar licencia, Validar licencia y Desactivar licencia. Genera una en tu dashboard e inclúyela en el encabezado Authorization de cada solicitud.

Generate an API Key

Ve a Desarrollador → API Keys en tu dashboard y selecciona Añadir API Key. Crea la clave en el modo que quieras utilizar: una clave del modo de prueba solo funciona con https://test.dodopayments.com, y una clave del modo activo solo funciona con https://live.dodopayments.com. Asigna a la clave un nombre descriptivo y elige tu nivel de acceso:

Habilitar acceso de escritura activado (predeterminado): permisos completos de lectura y escritura para todas las operaciones de la API.
Habilitar acceso de escritura desactivado: acceso de solo lectura. Puedes obtener datos (pagos, suscripciones, clientes y productos), pero no puedes crear ni modificar recursos.

Desactiva Habilitar acceso de escritura para las integraciones que solo necesiten consultar datos, como las herramientas de análisis o las integraciones con dashboards.

Store Your Key Securely

Copia la clave inmediatamente. No volverás a verla. Guárdala en una variable de entorno como DODO_PAYMENTS_API_KEY.

Authenticate Requests

Incluye tu API key en el encabezado Authorization de cada solicitud:

Authorization: Bearer YOUR_API_KEY

Nunca expongas tu API key en código del lado del cliente, repositorios públicos ni sistemas de control de versiones.

Formato de respuesta

Las solicitudes correctas devuelven 200 o 201 con un cuerpo JSON, o 204 sin cuerpo. Los errores devuelven un estado 4xx o 5xx con un cuerpo JSON que contiene un code y un message.

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "code": "INVALID_REQUEST_BODY",
  "message": "Your request body is invalid. Please check your request headers and object."
}

Límites de solicitudes

La API aplica dos límites simultáneamente: un límite de ráfaga por segundo y un límite sostenido por minuto. Los límites se aplican a todo tu negocio, a través de todas sus API keys, y dependen del nivel de límites de solicitudes de tu negocio.

Nivel predeterminado

Ventana	Límite
Por segundo (ráfaga)	40 solicitudes
Por minuto (sostenido)	240 solicitudes

Niveles superiores

Los negocios con mayores necesidades de API pueden pasar a niveles superiores de límites de solicitudes:

Nivel	Ráfaga (por segundo)	Sostenido (por minuto)
Predeterminado	40	240
Nivel 1	100	1.000
Nivel 2	500	5.000

Para mejorar tu nivel de límites de solicitudes, envía un correo a support@dodopayments.com.

Solicitudes no autenticadas

Las solicitudes sin una API key válida tienen límites por dirección IP:

Ventana	Límite
Por segundo (ráfaga)	20 solicitudes
Por minuto (sostenido)	100 solicitudes

Encabezados de límites de solicitudes

Las respuestas incluyen encabezados que muestran tu uso actual:

X-RateLimit-Limit — Número máximo de solicitudes permitidas en la ventana actual.
X-RateLimit-Remaining — Solicitudes restantes antes de alcanzar el límite.
X-RateLimit-Reset — Segundos hasta que se reinicie la ventana actual.

Cuando superas el límite, la API devuelve 429 Too Many Requests. Implementa un backoff exponencial en la lógica de reintentos.

Manejo de errores

Para saber qué significa un error y cómo resolverlo, consulta las páginas de códigos de error y fallos de transacciones.

Error Codes

Lista completa de códigos de error y sus significados.

Transaction Failures

Problemas habituales de las transacciones y cómo gestionarlos.

Webhooks

Recibe notificaciones en tiempo real cuando se produzcan pagos, suscripciones y otros eventos. Configura webhooks en tu dashboard y gestiona los eventos que necesite tu integración.

Webhook Guide

Configura webhooks, gestiona eventos y verifica firmas.

Guías de integración

Comienza con una de estas guías para crear tu primera integración:

One-time Payments

Crea sesiones de checkout y enlaces de pago, y gestiona pagos.

Subscriptions

Configura la facturación recurrente, gestiona planes y gestiona eventos del ciclo de vida.

Usage-Based Billing

Mide el uso y cobra a los clientes según el consumo.

Checkout Sessions

Crea experiencias de checkout alojadas y seguras.

SDKs & Libraries

Mobile Checkout SDKs

​URL de entorno

​Autenticación

​Formato de respuesta

​Límites de solicitudes

​Nivel predeterminado

​Niveles superiores

​Solicitudes no autenticadas

​Encabezados de límites de solicitudes

​Manejo de errores

Error Codes

Transaction Failures

​Webhooks

Webhook Guide

​Guías de integración

One-time Payments

Subscriptions

Usage-Based Billing

Checkout Sessions

URL de entorno

Autenticación

Formato de respuesta

Límites de solicitudes

Nivel predeterminado

Niveles superiores

Solicitudes no autenticadas

Encabezados de límites de solicitudes

Manejo de errores

Webhooks

Guías de integración