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

​

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 d’abonnement a été mis à jour (se déclenche sur tout changement de champ).
3. subscription.on_hold - L’abonnement est mis en attente en raison d’un renouvellement échoué.
4. subscription.failed - La création de l’abonnement a échoué lors de 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 jours d’essai) : Attendez-vous à recevoir dans les 2 à 10 minutes
   • Pour les jours d’essai : dès que cela se termine
3. subscription.renewed - Indique la déduction de paiement et le renouvellement pour le prochain cycle. (En gros, chaque fois qu’un paiement est déduit pour des produits d’abonnement, vous recevrez le webhook subscription.renewed avec payment.succeeded)

1. Échec d’abonnement

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

2. Abonnement en attente

• subscription.on_hold - L’abonnement est mis en attente en raison d’un échec de paiement de renouvellement ou d’un échec de frais de changement de plan.
• Lorsqu’un abonnement est mis en attente, il ne se renouvellera pas automatiquement tant que le mode 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ée un prélèvement pour les montants dus restants
2. Génère une facture pour le prélèvement
3. Traite le paiement en utilisant le nouveau mode de paiement
4. Réactive l’abonnement à l’é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 proratisé en fonction du temps restant dans le cycle de facturation actuel
• Prélève uniquement la différence entre l’ancien et le nouveau plan
• Pendant une période d’essai, cela passera immédiatement l’utilisateur au nouveau plan, prélevant le client immédiatement

​

2. full_immediately

• Prélève le montant total de l’abonnement pour le nouveau plan
• Ignore tout temps restant ou crédits de l’ancien plan
• Utile lorsque vous souhaitez réinitialiser le cycle de facturation ou prélever le montant total indépendamment de la proratisation

​

3. difference_immediately

• Lors de la mise à niveau, le client est immédiatement prélevé de la différence entre les deux montants de plan.
• Par exemple, si le plan actuel est de 30 Dollars et que le client passe à un plan de 80 Dollars, il est prélevé de 50 Dollars instantanément.
• Lors de la rétrogradation, le montant non utilisé du plan actuel est ajouté en tant que crédit interne et appliqué automatiquement aux renouvellements d’abonnement futurs.
• Par exemple, si le plan actuel est de 50 Dollars et que le client passe à un plan de 20 Dollars, les 30 Dollars restants sont crédités et utilisés pour le prochain cycle de facturation.

​

Comportement

• Lorsque vous invoquez cette API, Dodo Payments initie immédiatement un prélèvement basé sur votre option de proratisation sélectionnée
• Si le changement de plan est une rétrogradation et que vous utilisez prorated_immediately, les crédits seront 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 paiements récurrents futurs du même abonnement
• L’option full_immediately contourne les calculs de crédit et prélève le montant total du nouveau plan

​

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