Guía de Integración de Suscripciones

Requisitos Previos

Para integrar la API de Dodo Payments, necesitarás:

Una cuenta de comerciante de Dodo Payments
Credenciales de API (clave de API y clave secreta de webhook) desde el panel de control

Para una guía más detallada sobre los requisitos previos, consulta esta sección.

Integración de API

Sesiones de Pago

Utiliza las Sesiones de Pago para vender productos de suscripción con un pago seguro y alojado. Pasa tu producto de suscripción en product_cart y redirige a los clientes a la checkout_url devuelta.

No puedes mezclar productos de suscripción con productos de una sola vez en la misma sesión de pago.

SDK de Node.js
SDK de Python
API REST

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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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);

Respuesta de API

El siguiente es un ejemplo de la respuesta:

{
  "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 los 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 cambios en el estado de la suscripción:

subscription.active - La suscripción se activa con éxito.
subscription.updated - El objeto de suscripción fue actualizado (se activa en 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 próximo 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.

Utiliza subscription.updated para recibir notificaciones en tiempo real sobre cualquier cambio en la suscripción, manteniendo el estado de tu aplicación sincronizado sin necesidad de sondear la API.

Escenarios de Pago

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

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

Escenarios de Fallo de Pago

Fallo de 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 pago fallido.

Suscripción en Espera

subscription.on_hold - La suscripción se pone en espera debido a un pago de renovación fallido o un cargo fallido por cambio de plan.
Cuando una suscripción se pone 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 rastrear principalmente los eventos de suscripción para gestionar el ciclo de vida de la suscripción.

Manejo de Suscripciones en Espera

Cuando una suscripción entra en estado de 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 pone en espera cuando:

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

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

Reactivando Suscripciones desde Espera

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

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

Manejar el webhook subscription.on_hold

Cuando recibas 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 });
});

Actualizar método de pago

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
}

También puedes usar un ID de método de pago existente si el cliente tiene métodos de pago guardados:

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

Monitorear eventos de webhook

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

payment.succeeded - El cargo por las deudas restantes 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 carga útil de evento de suscripción

Propiedad	Tipo	Requerido	Descripción
`business_id`	string	Sí	El identificador único para el negocio
`timestamp`	string	Sí	La marca temporal de cuándo ocurrió el evento (no necesariamente la misma que cuando fue entregado)
`type`	string	Sí	El tipo de evento. Consulta Tipos de Eventos
`data`	object	Sí	La carga útil de datos principal. Consulta Objeto de Datos

Cambio de Planes de Suscripción

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

Referencia de API de Cambio de Plan

Para información detallada sobre cómo cambiar planes de suscripción, consulta nuestra documentación de 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 por 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 total de suscripción por el nuevo plan
Ignora cualquier tiempo restante o créditos del plan anterior
Útil cuando deseas reiniciar el ciclo de facturación o cobrar el monto total independientemente de la prorrata

3. `difference_immediately`

Al actualizar, se cobra inmediatamente al cliente la diferencia entre los dos montos del plan.
Por ejemplo, si el plan actual es de 30 Dólares y el cliente actualiza a 80 Dólares, se le cobra $50 de inmediato.
Al degradar, el monto no utilizado del plan actual se agrega como crédito interno y se aplica automáticamente a futuras renovaciones 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 utilizan para el próximo 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 utilizas prorated_immediately, los créditos se calcularán automáticamente y se agregarán al saldo de crédito de la suscripción. Estos créditos son específicos para esa suscripción y solo se utilizará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: Utiliza 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 independientemente del ciclo de facturación actual.

Procesamiento de Cargos

El cargo inmediato iniciado al cambiar de plan generalmente completa el procesamiento en menos de 2 minutos
Si este cargo inmediato falla por cualquier motivo, 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. Contacta al soporte para habilitar esta función.

Para crear una suscripción bajo demanda: Para crear una suscripción bajo demanda, utiliza el endpoint de 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 el monto a cobrar al cliente por esa transacción.

Para una guía completa, paso a paso—incluyendo ejemplos de solicitud/respuesta, políticas de reintento seguras y manejo de webhooks—consulta la Guía de Suscripciones Bajo Demanda.

Integration Guides

Cookbooks

Requisitos Previos

Integración de API

Sesiones de Pago

Respuesta de API

Webhooks

Tipos de Eventos de Suscripción

Escenarios de Pago

Manejo de Suscripciones en Espera

Cuándo las Suscripciones se Ponen en Espera

Reactivando Suscripciones desde Espera

Ejemplo de carga útil de evento de suscripción

Cambio de Planes de Suscripción

Referencia de API de Cambio de Plan

Opciones de Prorrata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamiento

Procesamiento de Cargos

Suscripciones Bajo Demanda

Integration Guides

Cookbooks

​Requisitos Previos

​Integración de API

​Sesiones de Pago

​Respuesta de API

​Webhooks

​Tipos de Eventos de Suscripción

​Escenarios de Pago

​Manejo de Suscripciones en Espera

​Cuándo las Suscripciones se Ponen en Espera

​Reactivando Suscripciones desde Espera

​Ejemplo de carga útil de evento de suscripción

​Cambio de Planes de Suscripción

Referencia de API de Cambio de Plan

​Opciones de Prorrata

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​Comportamiento

​Procesamiento de Cargos

​Suscripciones Bajo Demanda

Requisitos Previos

Integración de API

Sesiones de Pago

Respuesta de API

Webhooks

Tipos de Eventos de Suscripción

Escenarios de Pago

Manejo de Suscripciones en Espera

Cuándo las Suscripciones se Ponen en Espera

Reactivando Suscripciones desde Espera

Ejemplo de carga útil de evento de suscripción

Cambio de Planes de Suscripción

Opciones de Prorrata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamiento

Procesamiento de Cargos

Suscripciones Bajo Demanda