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

​

API-Antwort

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

​

Webhooks

​

Abonnement-Ereignistypen

1. subscription.active - Abonnement wurde erfolgreich aktiviert.
2. subscription.updated - Abonnementobjekt wurde aktualisiert (wird bei jeder Feldänderung ausgelöst).
3. subscription.on_hold - Abonnement wurde aufgrund fehlgeschlagener Erneuerung pausiert.
4. subscription.failed - Erstellung des Abonnements ist während der Mandatserstellung fehlgeschlagen.
5. subscription.renewed - Abonnement wird für den nächsten Abrechnungszeitraum erneuert.

​

Zahlungsszenarien

1. subscription.active - Zeigt die Aktivierung des Abonnements an
2. payment.succeeded - Bestätigt die erste Zahlung:
   • Bei sofortiger Abrechnung (0 Testtage): Erwarten Sie innerhalb von 2-10 Minuten
   • Bei Testtagen: wann immer diese enden
3. subscription.renewed - Zeigt die Abzug der Zahlung und die Erneuerung für den nächsten Zyklus an. (Im Grunde, wann immer eine Zahlung für Abonnementprodukte abgezogen wird, erhalten Sie den subscription.renewed Webhook zusammen mit payment.succeeded)

1. Abonnementfehler

• subscription.failed - Erstellung des Abonnements ist aufgrund eines Fehlers bei der Erstellung eines Mandats fehlgeschlagen.
• payment.failed - Zeigt fehlgeschlagene Zahlung an.

2. Abonnement auf Hold

• subscription.on_hold - Abonnement wurde aufgrund einer fehlgeschlagenen Erneuerungszahlung oder einer fehlgeschlagenen Planänderungsgebühr pausiert.
• Wenn ein Abonnement pausiert wird, wird es nicht automatisch erneuert, bis die Zahlungsmethode aktualisiert wird.

​

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 Gebühr für ausstehende Beträge
2. Generiert eine Rechnung für die Gebühr
3. Verarbeitet die Zahlung mit der neuen Zahlungsmethode
4. Reaktiviert das Abonnement in den active Zustand nach 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 proratisierten Betrag basierend auf der verbleibenden Zeit im aktuellen Abrechnungszyklus
• Berechnet dem Kunden nur die Differenz zwischen dem alten und dem neuen Plan
• Während einer Testphase wird der Benutzer sofort auf den neuen Plan umgeschaltet, wobei der Kunde sofort belastet wird

​

2. full_immediately

• Belastet den Kunden mit dem vollen Abonnementbetrag für den neuen Plan
• Ignoriert die verbleibende Zeit oder Gutschriften des vorherigen Plans
• Nützlich, wenn Sie den Abrechnungszyklus zurücksetzen oder den vollen Betrag unabhängig von der Proratisierung berechnen möchten

​

3. difference_immediately

• Bei einem Upgrade wird der Kunde sofort mit der Differenz zwischen den beiden Planbeträgen belastet.
• Wenn der aktuelle Plan 30 Dollar beträgt und der Kunde auf 80 Dollar aufsteigt, wird ihm sofort 50 Dollar berechnet.
• Bei einem Downgrade wird der nicht genutzte Betrag des aktuellen Plans als interne Gutschrift hinzugefügt und automatisch auf zukünftige Abonnementerneuerungen angewendet.
• Wenn der aktuelle Plan 50 Dollar beträgt und der Kunde auf einen Plan von 20 Dollar wechselt, werden die verbleibenden 30 Dollar gutgeschrieben und für den nächsten Abrechnungszyklus verwendet.

​

Verhalten

• Wenn Sie diese API aufrufen, initiiert Dodo Payments sofort eine Gebühr basierend auf Ihrer ausgewählten Proratisierungsoption
• Wenn die Planänderung ein Downgrade ist und Sie prorated_immediately verwenden, werden Gutschriften automatisch berechnet und dem Guthaben des Abonnements hinzugefügt. Diese Gutschriften sind spezifisch für dieses Abonnement und werden nur verwendet, um zukünftige wiederkehrende Zahlungen des gleichen Abonnements auszugleichen
• Die full_immediately Option umgeht die Berechnung von Gutschriften und belastet den vollständigen Betrag des neuen Plans

​

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