Subscription Integration Guide

​

Prérequis

• Un compte marchand Dodo Payments
• Une clé API disponible dans Developer → API Keys du tableau de bord, stockée dans DODO_PAYMENTS_API_KEY
• Un secret de webhook disponible dans Developer → Webhooks, stocké dans DODO_PAYMENTS_WEBHOOK_KEY
• Au moins un produit d’abonnement créé sous Products

​

Intégration de l’API

​

Sessions de checkout

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: 'pdt_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": "pdt_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: 'pdt_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);

​

Réponse de l’API

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

​

Webhooks

​

Types d’événements d’abonnement

1. subscription.active — L’abonnement est activé
2. subscription.updated — Un champ de l’abonnement a été modifié
3. subscription.on_hold — Une charge de renouvellement ou de changement de plan a échoué
4. subscription.failed — La création de l’abonnement a échoué (définitif ; le client doit se réabonner)
5. subscription.renewed — Une charge récurrente a réussi
6. subscription.past_due — Un renouvellement a échoué et la période de grâce a commencé ; le client conserve l’accès jusqu’à past_due_ends_at
7. subscription.plan_changed — Le plan a été mis à niveau, rétrogradé ou modifié
8. subscription.cancelled — L’abonnement a été annulé
9. subscription.expired — L’abonnement a atteint la fin de sa durée

​

Scénarios de paiement

1. subscription.active : le mandat est autorisé et l’abonnement est activé.
2. payment.succeeded : confirme la première charge. Attendez-vous à cet événement dans les 2 à 10 minutes suivant le paiement.

1. Au début de l’essai (paiement) : subscription.active est déclenché une fois le moyen de paiement autorisé. Aucune charge récurrente n’est encore prélevée. La première charge réelle est différée jusqu’à la fin de l’essai.
2. À la fin de l’essai : le montant récurrent est prélevé et vous recevez payment.succeeded avec subscription.renewed.

• subscription.renewed : est déclenché à chaque cycle de facturation lorsque le paiement du renouvellement est prélevé, toujours avec payment.succeeded. Il contient également le next_billing_date mis à jour.

1. Échec de l’abonnement

• subscription.failed - La création de l’abonnement a échoué, car le mandat n’a pas pu être créé.
• payment.failed - Indique un paiement échoué.

2. Abonnement suspendu

• subscription.on_hold - L’abonnement est suspendu en raison de l’échec du paiement du renouvellement ou de la charge liée à un changement de plan. Si votre entreprise dispose d’une période de grâce, un renouvellement échoué fait d’abord passer l’abonnement à past_due (subscription.past_due), puis à on_hold (ou cancelled, selon la configuration de votre période de grâce) uniquement lorsque celle-ci prend fin. Consultez Subscription States.
• Lorsqu’un abonnement est suspendu, il ne se renouvellera pas automatiquement tant que le moyen de paiement n’aura pas été mis à jour.

​

subscription.failed et subscription.on_hold

​

Gestion d’un abonnement suspendu

​

Quand les abonnements sont suspendus

• Le paiement du renouvellement échoue : la charge de renouvellement automatique échoue en raison de fonds insuffisants, d’une carte expirée ou d’un refus de la banque
• La charge liée à un changement de plan échoue : une charge immédiate lors de la mise à niveau ou de la rétrogradation du plan échoue
• L’autorisation du moyen de paiement échoue : le moyen de paiement ne peut pas être autorisé pour les charges récurrentes

​

Réactivation des abonnements suspendus

1. Crée une charge correspondant aux sommes restant dues
2. Génère une facture pour cette charge
3. Traite le paiement avec le nouveau moyen de paiement
4. Réactive l’abonnement à l’état active une fois le paiement réussi

// 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, {
  payment_method: { 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,
    payment_method={"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

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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.'
  });
}

​

Exemple de payload d’événement d’abonnement

​

Modification des plans d’abonnement

​

Options de proratisation

​

1. prorated_immediately

• Crédite la portion inutilisée du cycle de facturation actuel, au prorata du temps restant. Le crédit couvre le plan de base, la quantité et les éventuels modules complémentaires
• Puis facture un cycle complet selon le nouveau plan, la nouvelle quantité et les nouveaux modules complémentaires. La charge elle-même n’est jamais proratisée
• Charge immédiate nette = (nouveau cycle complet) moins (fraction restante x ancien cycle complet). Si le crédit est supérieur, la différence est conservée comme crédit associé à l’abonnement pour les renouvellements futurs
• Pendant une période d’essai, cette option fait immédiatement passer l’utilisateur au nouveau plan et facture le client sans attendre

​

2. full_immediately

• Facture au client le montant total de l’abonnement du nouveau plan, sans crédit pour le cycle précédent
• Qu’il s’agisse d’une mise à niveau ou d’une rétrogradation, le client paie l’intégralité du prix du nouveau plan à partir de zéro
• Utile lorsque vous souhaitez facturer le montant total, quelle que soit la durée restante de l’ancien plan

​

3. difference_immediately

• Le client paie uniquement la différence entre le prix de l’ancien plan et celui du nouveau plan
• Le montant ne dépend pas du moment du cycle où la modification est effectuée. La même mise à niveau coûte autant au premier qu’au vingt-neuvième jour
• Lors d’une mise à niveau, la différence est immédiatement facturée au client. Par exemple, $30/mois → $80/mois = $50 facturés immédiatement
• Lors d’une rétrogradation, la différence de prix est enregistrée comme crédit associé à l’abonnement et appliquée automatiquement aux futurs renouvellements. Par exemple, $50/mois → $20/mois = $30 enregistrés comme crédit

​

4. do_not_bill

• Applique immédiatement la modification du plan, mais ne facture rien au moment de la modification. Le nouveau plan, la nouvelle quantité et les nouveaux modules complémentaires sont utilisables immédiatement
• Comme rien n’est facturé sur le moment, une mise à niveau offre au client le plan supérieur gratuitement pendant le reste du cycle actuel. Une rétrogradation prend effet immédiatement, sans crédit pour la portion inutilisée du cycle déjà payée
• Les modules complémentaires accordés via do_not_bill ne sont pas crédités lors d’une modification ultérieure du plan, car ils n’ont jamais été facturés. Une modification ultérieure facture intégralement la nouvelle quantité de modules complémentaires
• Le plan mis à jour (ainsi que la quantité et les modules complémentaires) est facturé lors du prochain renouvellement planifié, et la date de facturation d’origine est conservée

​

Comportement

• Lorsque vous appelez cette API, Dodo Payments lance immédiatement une charge selon l’option de proratisation sélectionnée
• Avec prorated_immediately, un crédit correspondant à la portion inutilisée du cycle actuel est calculé à chaque modification, qu’il s’agisse d’une mise à niveau ou d’une rétrogradation. Si ce crédit dépasse la charge du nouveau cycle, le solde est ajouté au crédit de l’abonnement. Ces crédits sont propres à cet abonnement et servent uniquement à compenser les futurs paiements récurrents du même abonnement
• Avec difference_immediately, le montant net correspond toujours exactement à la différence de prix. Pour les rétrogradations, l’excédent est enregistré comme crédit associé à l’abonnement, comme avec prorated_immediately
• L’option full_immediately ignore les calculs de crédit et facture l’intégralité du nouveau plan
• L’option do_not_bill applique immédiatement la modification, mais reporte la facturation à la prochaine date de renouvellement, qui est conservée

​

Traitement de la charge

• La charge immédiate lancée lors de la modification du plan termine généralement son traitement en moins de 2 minutes
• Si cette charge immédiate échoue pour quelque raison que ce soit, l’abonnement est automatiquement suspendu jusqu’à la résolution du problème

​

Abonnements à la demande

​

Points clés à connaître sur la facturation des abonnements

​

Référence API associée