Guide d'intégration des abonnements

​

Prérequis

• Un compte marchand Dodo Payments
• Des identifiants API (clé API et clé secrète de webhook) depuis le tableau de bord

​

Intégration API

​

Sessions de paiement

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

​

Réponse 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é avec succès.
2. subscription.updated - L’objet abonnement a été mis à jour (se déclenche à chaque changement de champ).
3. subscription.on_hold - L’abonnement est suspendu en raison d’un renouvellement échoué.
4. subscription.failed - La création de l’abonnement a échoué pendant la création du mandat.
5. subscription.renewed - L’abonnement est renouvelé pour la prochaine période de facturation.

​

Scénarios de paiement

1. subscription.active - Indique l’activation de l’abonnement
2. payment.succeeded - Confirme le paiement initial :
   • Pour une facturation immédiate (0 jour d’essai) : attendez-vous à ce qu’il arrive dans les 2 à 10 minutes
   • Pour des jours d’essai : dès que ceux-ci prennent fin
3. subscription.renewed - Indique que le paiement a été prélevé et que le renouvellement pour le cycle suivant est en cours. (Chaque fois qu’un paiement est prélevé pour des produits d’abonnement, vous recevrez le webhook subscription.renewed ainsi que payment.succeeded)

1. Échec de l’abonnement

• subscription.failed - La création de l’abonnement a échoué en raison d’un échec lors de la création du mandat.
• payment.failed - Indique un paiement échoué.

2. Abonnement en attente

• subscription.on_hold - L’abonnement est mis en attente en raison d’un renouvellement échoué ou d’un échec de facturation lié au changement de forfait.
• Lorsqu’un abonnement est mis en attente, il ne se renouvelle pas automatiquement tant que le moyen de paiement n’est pas mis à jour.

​

Gestion des abonnements en attente

​

Quand les abonnements sont mis en attente

• Le paiement de renouvellement échoue : Le prélèvement automatique échoue en raison de fonds insuffisants, d’une carte expirée ou d’un refus bancaire
• Le frais de changement de plan échoue : Un prélèvement immédiat lors de la mise à niveau/diminution du plan échoue
• L’autorisation du mode de paiement échoue : Le mode de paiement ne peut pas être autorisé pour des prélèvements récurrents

​

Réactivation des abonnements en attente

1. Créer un prélèvement pour les sommes restantes dues
2. Générer une facture pour le prélèvement
3. Traiter le paiement avec le nouveau moyen de paiement
4. Réactiver l’abonnement en état active après un 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, {
  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.'
  });
}

​

Exemple de charge utile d’événement d’abonnement

​

Changer de plans d’abonnement

​

Options de proratisation

​

1. prorated_immediately

• Calcule le montant au prorata en fonction du temps restant dans le cycle de facturation actuel
• Ne facture au client que la différence entre l’ancien et le nouveau forfait
• Pendant une période d’essai, cela 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 pour le nouveau forfait
• Ignore le temps restant ou les crédits du forfait précédent
• Utile lorsque vous souhaitez réinitialiser le cycle de facturation ou facturer le montant complet indépendamment du prorata

​

3. difference_immediately

• Lors d’une montée en gamme, le client est immédiatement facturé de la différence entre les deux montants de forfait.
• Par exemple, si le forfait actuel est de 30 dollars et que le client passe à un forfait à 80 dollars, il est facturé 50 $ instantanément.
• Lors d’une descente en gamme, le montant non utilisé du forfait actuel est ajouté comme crédit interne et appliqué automatiquement aux prochains renouvellements.
• Par exemple, si le forfait actuel est de 50 dollars et que le client passe à un forfait à 20 dollars, les 30 $ restants sont crédités et utilisés pour le prochain cycle de facturation.

​

Comportement

• Lorsque vous appelez cette API, Dodo Payments initie immédiatement un prélèvement en fonction de l’option de prorata sélectionnée
• Si le changement de forfait correspond à une descente en gamme et que vous utilisez prorated_immediately, les crédits sont automatiquement calculés et ajoutés au solde de crédit de l’abonnement. Ces crédits sont spécifiques à cet abonnement et ne seront utilisés que pour compenser les futurs paiements récurrents du même abonnement
• L’option full_immediately évite les calculs de crédit et facture le montant total du nouveau forfait

​

Traitement des prélèvements

• Le prélèvement immédiat initié lors du changement de plan se termine généralement en moins de 2 minutes
• Si ce prélèvement immédiat échoue pour une raison quelconque, l’abonnement est automatiquement mis en attente jusqu’à ce que le problème soit résolu

​

Abonnements à la demande