Subscription Integration Guide - Dodo Payments Documentation

Prerequisites

To integrate the Dodo Payments API, you’ll need:

A Dodo Payments merchant account
API credentials (API key and webhook secret key) from the dashboard

For a more detailed guide on the prerequisites, check this section.

API Integration

Checkout Sessions

Use Checkout Sessions to sell subscription products with a secure, hosted checkout. Pass your subscription product in product_cart and redirect customers to the returned checkout_url.

Mixed Checkout: You can combine subscription products with one-time products in the same checkout session. This enables use cases like setup fees with subscriptions, hardware bundles with SaaS, and more. See the Checkout Sessions guide for examples.

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "prod_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

API Response

The following is an example of the response:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Redirige al cliente a checkout_url.

Webhooks

Al integrar suscripciones, recibirás webhooks para rastrear el ciclo de vida de la suscripción. Estos webhooks te ayudan a gestionar los estados de suscripción y escenarios de pago de manera efectiva. Para configurar tu endpoint de webhook, sigue nuestra Guía de Integración Detallada.

Tipos de Eventos de Suscripción

Los siguientes eventos de webhook rastrean los cambios de estado de la suscripción:

subscription.active - La suscripción se activa con éxito.
subscription.updated - El objeto de la suscripción fue actualizado (se dispara con cualquier cambio de campo).
subscription.on_hold - La suscripción se pone en espera debido a una renovación fallida.
subscription.failed - La creación de la suscripción falló durante la creación del mandato.
subscription.renewed - La suscripción se renueva para el siguiente período de facturación.

Para una gestión confiable del ciclo de vida de la suscripción, recomendamos rastrear estos eventos de suscripción.

Usa subscription.updated para obtener notificaciones en tiempo real sobre cualquier cambio de suscripción, manteniendo el estado de tu aplicación sincronizado sin sondeo de la API.

Escenarios de Pago

Flujo de Pago Exitoso Cuando un pago tiene éxito, recibirás los siguientes webhooks:

subscription.active - Indica activación de la suscripción
payment.succeeded - Confirma el pago inicial:
- Para facturación inmediata (0 días de prueba): Espera dentro de 2-10 minutos
- Para días de prueba: cuando eso termine
subscription.renewed - Indica deducción de pago y renovación para el próximo ciclo. (Básicamente, cada vez que se deduce el pago por productos de suscripción, recibirás el webhook subscription.renewed junto con payment.succeeded)

Escenarios de Fallo de Pago

Fallo de la Suscripción

subscription.failed - La creación de la suscripción falló debido a un fallo en la creación de un mandato.
payment.failed - Indica un fallo de pago.

Suscripción en Espera

subscription.on_hold - La suscripción se pone en espera debido a un fallo en el pago de renovación o un fallo al cambiar el plan.
Cuando una suscripción está en espera, no se renovará automáticamente hasta que se actualice el método de pago.

Mejor Práctica: Para simplificar la implementación, recomendamos principalmente rastrear eventos de suscripción para gestionar el ciclo de vida de la suscripción.

Para una guía completa sobre cómo leer error_code/error_message, decidir cuándo reintentar y visibilizar los fallos a los clientes, consulta Manejo de Fallos de Pago.

`subscription.failed` vs. `subscription.on_hold`

Estos dos eventos son fáciles de confundir, pero requieren manejos muy diferentes:

Evento	Cuándo se dispara	Estado	¿Recuperable?	Qué hacer
`subscription.failed`	El mandato inicial no pudo ser creado en la creación de la suscripción	`failed`	No — terminal	No conceder acceso. Pedir al cliente que inicie una nueva suscripción con un método de pago diferente.
`subscription.on_hold`	Un pago de renovación (o un cargo por cambio de plan) falló en una suscripción ya activa	`on_hold`	Sí	Recuperar actualizando el método de pago; ver Manejo de Suscripción en Espera a continuación.

subscription.failed es terminal: la suscripción no puede reactivarse. El cliente debe crear una nueva suscripción. Nunca conceder derechos cuando se dispara este evento.

Manejo de Suscripción en Espera

Cuando una suscripción entra en el estado on_hold, necesitas actualizar el método de pago para reactivarla. Esta sección explica cuándo las suscripciones se ponen en espera y cómo manejarlas.

Cuándo las Suscripciones se Ponen en Espera

Una suscripción se coloca en espera cuando:

Falló el pago de renovación: El cargo automático de renovación falla debido a fondos insuficientes, tarjeta expirada o rechazo del banco
Falla el cargo por cambio de plan: Un cargo inmediato durante la actualización/degradación del plan falla
Falla la autorización del método de pago: El método de pago no puede ser autorizado para cargos recurrentes

Las suscripciones en estado on_hold no se renovarán automáticamente. Debes actualizar el método de pago para reactivar la suscripción.

Reactivación de Suscripciones desde en Espera

Para reactivar una suscripción desde el estado on_hold, usa la API de Actualización de Método de Pago. Esto automáticamente:

Crea un cargo por deudas pendientes
Genera una factura por el cargo
Procesa el pago usando el nuevo método de pago
Reactiva la suscripción al estado active tras el pago exitoso

Handle subscription.on_hold webhook

Cuando recibes un webhook subscription.on_hold, actualiza el estado de tu aplicación y notifica al cliente:

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

Update payment method

Cuando el cliente esté listo para actualizar su método de pago, llama a la API de Actualización de Método de Pago:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    type="new",
    return_url="https://example.com/return"
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

También puedes usar una ID de método de pago existente si el cliente ha guardado métodos de pago:

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

Monitor webhook events

Después de actualizar el método de pago, monitorea estos eventos de webhook:

payment.succeeded - El cargo por deudas pendientes fue exitoso
subscription.active - La suscripción ha sido reactivada

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

Ejemplo de Payload de Evento de Suscripción

Propiedad	Tipo	Obligatorio	Descripción
`business_id`	string	Sí	El identificador único para el negocio
`timestamp`	string	Sí	La marca de tiempo de cuando ocurrió el evento (no necesariamente igual a cuando se entregó)
`type`	string	Sí	El tipo de evento. Ver Tipos de Evento
`data`	object	Sí	La carga útil principal de datos. Ver Objeto de Datos

Cambiar Planes de Suscripción

Puedes mejorar o degradar un plan de suscripción usando el endpoint API de cambio de plan. Esto te permite modificar el producto de la suscripción, la cantidad y manejar la prorrata.

Change Plan API Reference

Para obtener información detallada sobre el cambio de planes de suscripción, consulta nuestra documentación de la API de Cambio de Plan.

Opciones de Prorrata

Al cambiar planes de suscripción, tienes dos opciones para manejar el cargo inmediato:

1. `prorated_immediately`

Calcula el monto prorrateado basado en el tiempo restante en el ciclo de facturación actual
Cobra al cliente solo la diferencia entre el plan antiguo y el nuevo
Durante un período de prueba, esto cambiará inmediatamente al usuario al nuevo plan, cobrando al cliente de inmediato

2. `full_immediately`

Cobra al cliente el monto completo de la suscripción para el nuevo plan
Ignora cualquier tiempo restante o créditos del plan anterior
Útil cuando deseas restablecer el ciclo de facturación o cobrar el monto completo sin importar la prorrata

3. `difference_immediately`

Al mejorar, el cliente se cobra de inmediato la diferencia entre los dos montos de los planes.
Por ejemplo, si el plan actual es de 30 Dólares y el cliente mejora a uno de 80 Dólares, se le cobran $50 instantáneamente.
Al degradar, la cantidad no utilizada del plan actual se añade como crédito interno y se aplica automáticamente a renovaciones futuras de suscripción.
Por ejemplo, si el plan actual es de 50 Dólares y el cliente cambia a un plan de 20 Dólares, los $30 restantes se acreditan y se usan para el siguiente ciclo de facturación.

Comportamiento

Cuando invocas esta API, Dodo Payments inicia inmediatamente un cargo basado en tu opción de prorrata seleccionada
Si el cambio de plan es una degradación y usas prorated_immediately, se calcularán automáticamente los créditos y se añadirán al saldo de crédito de la suscripción. Estos créditos son específicos de esa suscripción y solo se usarán para compensar futuros pagos recurrentes de la misma suscripción
La opción full_immediately omite los cálculos de crédito y cobra el monto completo del nuevo plan

Elige tu opción de prorrata cuidadosamente: Usa prorated_immediately para una facturación justa que tenga en cuenta el tiempo no utilizado, o full_immediately cuando desees cobrar el monto completo del nuevo plan sin importar el ciclo de facturación actual.

Procesamiento del Cargo

El cargo inmediato iniciado al cambiar el plan usualmente completa el procesamiento en menos de 2 minutos
Si este cargo inmediato falla por alguna razón, la suscripción se coloca automáticamente en espera hasta que se resuelva el problema

Suscripciones Bajo Demanda

Las suscripciones bajo demanda te permiten cobrar a los clientes de manera flexible, no solo en un horario fijo. Esta función está disponible para todas las cuentas.

Para crear una suscripción bajo demanda: Para crear una suscripción bajo demanda, utiliza el endpoint API POST /subscriptions e incluye el campo on_demand en el cuerpo de tu solicitud. Esto te permite autorizar un método de pago sin un cargo inmediato o establecer un precio inicial personalizado. Para cobrar una suscripción bajo demanda: Para cargos posteriores, utiliza el endpoint POST /subscriptions//charge y especifica la cantidad a cobrar al cliente por esa transacción.

Para obtener una guía completa, paso a paso, incluyendo ejemplos de solicitudes/respuestas, políticas de reintento seguro y manejo de webhooks, consulta la Guía de Suscripciones Bajo Demanda.

Referencia de API Relacionada

Create Subscription

Referencia de API para crear productos de suscripción y gestionar el ciclo de vida de la suscripción

Change Subscription Plan

Referencia de API para mejorar, degradar o cambiar planes de suscripción con opciones de prorrata

Update Payment Method

Referencia de API para actualizar métodos de pago y reactivar suscripciones en espera

Patch Subscription

Referencia de API para actualizar los detalles y la configuración de suscripciones

​Prerequisites

​API Integration

​Checkout Sessions

​API Response

​Webhooks

​Tipos de Eventos de Suscripción

​Escenarios de Pago

​subscription.failed vs. subscription.on_hold

​Manejo de Suscripción en Espera

​Cuándo las Suscripciones se Ponen en Espera

​Reactivación de Suscripciones desde en Espera

​Ejemplo de Payload de Evento de Suscripción

​Cambiar Planes de Suscripción

Change Plan API Reference

​Opciones de Prorrata

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​Comportamiento

​Procesamiento del Cargo

​Suscripciones Bajo Demanda

​Referencia de API Relacionada

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

Prerequisites

API Integration

Checkout Sessions

API Response

Webhooks

Tipos de Eventos de Suscripción

Escenarios de Pago

`subscription.failed` vs. `subscription.on_hold`

Manejo de Suscripción en Espera

Cuándo las Suscripciones se Ponen en Espera

Reactivación de Suscripciones desde en Espera

Ejemplo de Payload de Evento de Suscripción

Cambiar Planes de Suscripción

Opciones de Prorrata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamiento

Procesamiento del Cargo

Suscripciones Bajo Demanda

Referencia de API Relacionada