Integrationshandbuch für Abonnements

​

Voraussetzungen

• Ein Dodo Payments Händlerkonto
• API-Anmeldeinformationen (API-Schlüssel und Webhook-Geheimschlüssel) aus dem Dashboard

​

API-Integration

​

Checkout-Sitzungen

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

​

API-Antwort

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

​

Webhooks

​

Abonnement-Ereignistypen

1. subscription.active - Das Abonnement wird erfolgreich aktiviert.
2. subscription.updated - Das Abonnementobjekt wurde aktualisiert (tritt bei jeder Feldänderung auf).
3. subscription.on_hold - Das Abonnement wird aufgrund eines fehlgeschlagenen Verlängerungsversuchs pausiert.
4. subscription.failed - Die Erstellung des Abonnements schlug während der Mandatserstellung fehl.
5. subscription.renewed - Das Abonnement wird für den nächsten Abrechnungszeitraum verlängert.

​

Zahlungsszenarien

1. subscription.active - Zeigt die Aktivierung des Abonnements an
2. payment.succeeded - Bestätigt die Erstzahlung:
   • Bei sofortiger Abrechnung (0 Tage Testzeitraum): Erwartet innerhalb von 2–10 Minuten
   • Bei Testzeitraum: Sobald dieser endet
3. subscription.renewed - Zeigt die Abbuchung und Verlängerung für den nächsten Zyklus an. (Grundsätzlich erhältst du jedes Mal, wenn eine Zahlung für Abonnementprodukte abgebucht wird, subscription.renewed Webhook zusammen mit payment.succeeded)

1. Abonnementfehler

• subscription.failed - Die Erstellung des Abonnements schlug fehl, weil das Mandat nicht erstellt werden konnte.
• payment.failed - Zeigt eine fehlgeschlagene Zahlung an.

2. Abonnement pausiert

• subscription.on_hold - Das Abonnement wird aufgrund einer fehlgeschlagenen Verlängerungszahlung oder einer fehlgeschlagenen Planänderungsabbuchung pausiert.
• Wenn ein Abonnement pausiert ist, erneuert es sich nicht automatisch, bis die Zahlungsmethode aktualisiert wurde.

​

Umgang mit Abonnements auf Hold

​

Wann Abonnements auf Hold gehen

• Erneuerungszahlung schlägt fehl: Die automatische Erneuerungsgebühr schlägt aufgrund unzureichender Mittel, abgelaufener Karte oder Bankablehnung fehl
• Planänderungsgebühr schlägt fehl: Eine sofortige Gebühr während des Upgrades/Downgrades des Plans schlägt fehl
• Zahlungsmethodenautorisierung schlägt fehl: Die Zahlungsmethode kann für wiederkehrende Gebühren nicht autorisiert werden

​

Reaktivierung von Abonnements aus dem Hold-Zustand

1. Erstellt eine Belastung für ausstehende Beträge
2. Generiert eine Rechnung für die Belastung
3. Verarbeitet die Zahlung mit der neuen Zahlungsmethode
4. Reaktiviert das Abonnement in den Zustand active bei erfolgreicher Zahlung

// 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.'
  });
}

​

Beispiel für das Abonnementereignis-Payload

​

Ändern von Abonnementplänen

​

Proratisierungsoptionen

​

1. prorated_immediately

• Berechnet den anteiligen Betrag basierend auf der verbleibenden Zeit im aktuellen Abrechnungszeitraum
• Belastet den Kunden nur für die Differenz zwischen dem alten und neuen Plan
• Während einer Testphase wird der Nutzer sofort auf den neuen Plan umgestellt, und der Kunde wird sofort belastet

​

2. full_immediately

• Belastet den Kunden mit dem vollen Abonnementbetrag für den neuen Plan
• Ignoriert verbleibende Zeit oder Guthaben aus dem vorherigen Plan
• Nützlich, wenn du den Abrechnungszeitraum zurücksetzen oder den vollen Betrag unabhängig von der Pro-Rata-Berechnung berechnen möchtest

​

3. difference_immediately

• Beim Upgrade wird der Kunde sofort mit der Differenz zwischen den beiden Planbeträgen belastet.
• Wenn der aktuelle Plan beispielsweise 30 Dollar kostet und der Kunde auf einen 80-Dollar-Plan upgradet, werden ihm sofort 50 Dollar belastet.
• Beim Downgrade wird der ungenutzte Betrag aus dem aktuellen Plan als internes Guthaben hinzugefügt und automatisch bei zukünftigen Abonnementverlängerungen angerechnet.
• Wenn der aktuelle Plan zum Beispiel 50 Dollar kostet und der Kunde auf einen 20-Dollar-Plan wechselt, werden die verbleibenden 30 Dollar gutgeschrieben und für den nächsten Abrechnungszeitraum verwendet.

​

Verhalten

• Wenn du diese API aufrufst, initiiert Dodo Payments sofort eine Belastung basierend auf deiner ausgewählten Pro-rata-Option
• Wenn die Planänderung ein Downgrade ist und du prorated_immediately verwendest, werden die Guthaben automatisch berechnet und dem Guthabenkonto des Abonnements hinzugefügt. Diese Guthaben sind spezifisch für dieses Abonnement und werden nur zur Verrechnung zukünftiger wiederkehrender Zahlungen desselben Abonnements verwendet
• Die Option full_immediately umgeht die Guthabenberechnung und belastet den gesamten neuen Planbetrag

​

Gebührenverarbeitung

• Die sofortige Gebühr, die bei der Planänderung initiiert wird, wird normalerweise in weniger als 2 Minuten verarbeitet
• Wenn diese sofortige Gebühr aus irgendeinem Grund fehlschlägt, wird das Abonnement automatisch auf Hold gesetzt, bis das Problem behoben ist

​

On-Demand-Abonnements