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 — Un renouvellement ou une facturation liée à un changement de forfait 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 facturation 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 son accès jusqu’à past_due_ends_at
7. subscription.plan_changed — Le forfait a été augmenté, réduit ou modifié
8. subscription.cancelled — L’abonnement a été annulé
9. subscription.expired — L’abonnement a atteint la fin de sa période

​

Scénarios de paiement

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

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

• subscription.renewed : est déclenché à chaque cycle de facturation lorsque le paiement du renouvellement est débité, 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 d’un renouvellement ou d’une facturation liée à un changement de forfait. Si votre entreprise prévoit 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 États des abonnements.
• Lorsqu’un abonnement est suspendu, il ne se renouvelle pas automatiquement tant que le moyen de paiement n’a pas été mis à jour.

​

subscription.failed par rapport à subscription.on_hold

​

Gérer un abonnement suspendu

​

Quand les abonnements sont suspendus

• Le paiement du renouvellement échoue : la facturation automatique du renouvellement échoue en raison de fonds insuffisants, d’une carte expirée ou d’un refus bancaire
• La facturation liée à un changement de forfait échoue : une facturation immédiate lors d’une augmentation ou d’une réduction de forfait échoue
• L’autorisation du moyen de paiement échoue : le moyen de paiement ne peut pas être autorisé pour les facturations récurrentes

​

Réactiver les abonnements suspendus

1. Crée une facturation pour les sommes restantes dues
2. Génère une facture pour cette facturation
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

​

Modifier les forfaits d’abonnement

​

Options de proratisation

​

1. prorated_immediately

• Crédite la portion inutilisée du cycle de facturation actuel, proratisée selon le temps restant. Le crédit couvre le forfait de base, la quantité et les éventuels modules complémentaires
• Facture ensuite un cycle complet selon le nouveau forfait, la nouvelle quantité et les nouveaux modules complémentaires. La facturation elle-même n’est jamais proratisée
• Facturation 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 bascule immédiatement l’utilisateur vers le nouveau forfait et facture le client immédiatement

​

2. full_immediately

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

​

3. difference_immediately

• Le client paie uniquement la différence entre le prix de l’ancien forfait et celui du nouveau
• Le montant ne dépend pas du moment du cycle où la modification est effectuée. La même augmentation coûte le même prix au jour 1 et au jour 29
• En cas d’augmentation, la différence est immédiatement facturée au client. Par exemple, $30/mois → $80/mois = $50 facturés immédiatement
• En cas de réduction, la différence de prix est conservée comme crédit associé à l’abonnement et appliquée automatiquement aux renouvellements futurs. Par exemple, $50/mois → $20/mois = $30 conservés comme crédit

​

4. do_not_bill

• Applique immédiatement la modification du forfait, mais ne facture rien au moment de la modification. Le nouveau forfait, la nouvelle quantité et les nouveaux modules complémentaires sont utilisables immédiatement
• Comme aucune facturation n’est effectuée immédiatement, une augmentation permet au client de bénéficier gratuitement du forfait supérieur pendant le reste du cycle actuel. Une réduction 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 forfait, car ils n’ont jamais été facturés. Une modification ultérieure facture intégralement la nouvelle quantité de modules complémentaires
• Le forfait mis à jour (ainsi que la quantité et les modules complémentaires) est facturé au prochain renouvellement prévu, et la date de facturation d’origine est conservée

​

Comportement

• Lorsque vous appelez cette API, Dodo Payments lance immédiatement une facturation 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 augmentation ou d’une réduction. Si ce crédit dépasse la facturation du nouveau cycle, le solde est ajouté au crédit de l’abonnement. Ces crédits sont spécifiques à 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éductions, l’excédent est conservé comme crédit associé à l’abonnement, comme avec prorated_immediately
• L’option full_immediately ignore les calculs de crédit et facture le montant total du nouveau forfait
• 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 facturation

• La facturation immédiate lancée lors de la modification du forfait est généralement traitée en moins de 2 minutes
• Si cette facturation 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 essentiels à connaître sur la facturation des abonnements

​

Référence API associée