Guía de Integración de Suscripciones

​

Requisitos Previos

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

​

Integración de API

​

Sesiones de Pago

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);

​

Respuesta de API

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

​

Webhooks

​

Tipos de Eventos de Suscripción

1. subscription.active - La suscripción se activa correctamente.
2. subscription.updated - El objeto de suscripción se actualizó (se dispara con cualquier cambio de campo).
3. subscription.on_hold - La suscripción se suspende debido a una renovación fallida.
4. subscription.failed - La creación de la suscripción falló durante la creación del mandato.
5. subscription.renewed - La suscripción se renueva para el siguiente período de facturación.

​

Escenarios de Pago

1. subscription.active - Indica la activación de la suscripción
2. payment.succeeded - Confirma el pago inicial:
   • Para facturación inmediata (0 días de prueba): espera entre 2 y 10 minutos
   • Para días de prueba: cuando este finalice
3. subscription.renewed - Indica que se ha deducido el pago y la renovación para el siguiente ciclo. (Básicamente, siempre que se deduzca el pago de productos de suscripción, recibirás el webhook subscription.renewed junto con payment.succeeded)

1. Fallo de suscripción

• subscription.failed - La creación de la suscripción falló debido a que no se pudo crear un mandato.
• payment.failed - Indica un pago fallido.

2. 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 entra en espera, no se renovará automáticamente hasta que se actualice el método de pago.

​

Manejo de Suscripciones en Espera

​

Cuándo las Suscripciones se Ponen en Espera

• 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

​

Reactivando Suscripciones desde Espera

1. Crea un cargo por los adeudos restantes
2. Genera una factura por el cargo
3. Procesa el pago con el nuevo método de pago
4. Reactiva la suscripción al estado active tras el pago exitoso

// 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 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
}

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

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

​

Cambio de Planes de Suscripción

​

Opciones de Prorrata

​

1. prorated_immediately

• Calcula el importe prorrateado según 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 cambia inmediatamente al usuario al nuevo plan, cobrando al cliente de inmediato

​

2. full_immediately

• Cobra al cliente el importe total de la suscripción del nuevo plan
• Ignora cualquier tiempo restante o crédito del plan anterior
• Útil cuando quieres reiniciar el ciclo de facturación o cobrar el importe completo sin importar el prorrateo

​

3. difference_immediately

• Al actualizar, se cobra inmediatamente al cliente la diferencia entre las dos cantidades del plan.
• Por ejemplo, si el plan actual cuesta 30 dólares y el cliente actualiza a uno de 80 dólares, se le cobra $50 instantáneamente.
• Al degradar, el importe no usado del plan actual se añade como crédito interno y se aplica automáticamente a futuras renovaciones de la suscripción.
• Por ejemplo, si el plan actual cuesta 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 la opción de prorrateo seleccionada
• Si el cambio de plan es una degradación y usas prorated_immediately, los créditos se calculan automáticamente y se añaden al saldo de crédito de la suscripción. Estos créditos son específicos de esa suscripción y solo se utilizarán para compensar futuros pagos recurrentes de la misma suscripción
• La opción full_immediately evita los cálculos de crédito y cobra el importe completo del nuevo plan

​

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