Skip to main content

Checkout Sessions

Erstelle einen sicheren, gehosteten Checkout für einmalige Zahlungen und Abonnements.

Payment Links

Teile eine URL, um Zahlungen ohne Code zu erfassen.

Webhooks

Empfange Zahlungsereignisse und erfülle Bestellungen.

API Reference

Vollständige Endpoint-Dokumentation und Live-Tests.

Voraussetzungen

Bevor du beginnst, benötigst du:
  • Ein Dodo Payments-Konto.
  • Mindestens ein Produkt. Erstellen Sie es unter Products im Dashboard. Ein Abonnementprodukt mit einem Preis ungleich null muss das subscription minimum für die Währung erfüllen, in der der Kunde bezahlt: $1.00 für USD. Andere Währungen als USD, EUR und GBP müssen ebenfalls mindestens $1.00 wert sein. Ein Abonnement für $0 wird ebenfalls unterstützt.
  • Ein API key. Erstellen Sie ihn unter Developer → API Keys und speichern Sie ihn in der Umgebungsvariable DODO_PAYMENTS_API_KEY. Erstellen Sie den Schlüssel während der Entwicklung im Testmodus: Die Beispiele auf dieser Seite verwenden den Testmodus, und ein Schlüssel im Testmodus funktioniert nur mit dem Testmodus. Siehe Authentication.
  • Das SDK für Ihre Sprache. Das Node.js SDK erfordert Node.js 20 oder höher, das Python SDK Python 3.9 oder höher und das Go SDK Go 1.22 oder höher. Für die cURL-Beispiele ist kein SDK erforderlich.
Das webhook example verwendet ebenfalls das Paket standardwebhooks. Installieren Sie es mit npm install standardwebhooks.

Integrationspfad auswählen

Overlay- und Inline-Checkout funktionieren nur auf einer Webseite. Erstellen Sie in einer nativen mobilen App die Checkout-Session auf Ihrem Server und öffnen Sie deren checkout_url mit einem mobilen Checkout SDK. Damit ein Coding-Agent diese Integration für Sie erstellt, installieren Sie das Agent Plugin.

Checkout Sessions

Erstellen Sie ein sicheres, gehostetes Checkout-Erlebnis. Sie erstellen eine Session auf Ihrem Server und leiten den Kunden anschließend an die zurückgegebene checkout_url weiter.
Jede checkout_url kann einmal verwendet werden und läuft nach 24 Stunden ab oder nach 15 Minuten, wenn Sie confirm: true übergeben. Mit confirm: true müssen Sie außerdem jedes erforderliche Feld angeben. Erstellen Sie für jeden Kunden und jeden Zahlungsversuch eine neue Session.

Checkout-Session erstellen

Zum Checkout weiterleiten

Leiten Sie den Kunden nach dem Erstellen einer Session an die checkout_url weiter:
Weitere Anpassungsmöglichkeiten finden Sie in der vollständigen Anleitung zu Checkout Sessions und in der API Reference.

Fehler behandeln

Wenn eine Anfrage fehlschlägt, gibt die API einen HTTP status code und einen JSON-Body mit einem code und einem message zurück. Richten Sie Ihre Fehlerbehandlung nach code und nicht nach message aus. Eine Übersicht über alle Codes, ihre Ursachen und die entsprechenden Lösungen finden Sie unter Error Codes. Eine fehlgeschlagene Zahlung wird separat gemeldet: Der status der Zahlung ist failed, ihr error_code enthält den Grund, und Sie erhalten einen payment.failed webhook. Informationen dazu, ob Sie es erneut versuchen sollten, finden Sie unter Handle Payment Failures. Ein Payment Link ist eine URL, die den Checkout für ein Produkt öffnet, sodass Sie Zahlungen ohne Code einziehen können. Query-Parameter füllen Kundendaten vorab aus und steuern das Checkout-Formular. Wenn ein Kunde den Link öffnet, speichert der Checkout die Parameter in einer Session und kürzt die URL auf einen session-Parameter, sodass sie bei einer Seitenaktualisierung erhalten bleiben. Ein statischer Payment Link ist eine URL, die Sie einmal erstellen und mehrfach teilen. Die Basis-URL lautet:
Fügen Sie Query-Parameter hinzu, um den Checkout anzupassen:
integer
Standard:"1"
Anzahl der zu kaufenden Artikel.
string
erforderlich
Payment Links verwenden redirect_url. Die Checkout Sessions API verwendet für denselben Zweck return_url.URL, an die nach der Zahlung weitergeleitet werden soll. Dodo Payments fügt die Zahlungsdetails als Query-Parameter hinzu, zum Beispiel https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Wenn das Produkt Lizenzschlüssel ausstellt, wird außerdem ein license_key-Parameter hinzugefügt, wobei mehrere Schlüssel durch Kommas getrennt werden.
string
Legt die Zahlungswährung fest. Standardmäßig wird die Währung des Abrechnungslands verwendet.
boolean
Standard:"true"
Währungswähler ein- oder ausblenden.
boolean
Standard:"true"
Rabattbereich ein- oder ausblenden. Setzen Sie den Wert auf false, um zu verhindern, dass Kunden Gutscheincodes eingeben.
number
Legt den berechneten Betrag in größeren Währungseinheiten fest, zum Beispiel 12.5 für $12.50. Funktioniert nur mit Pay What You Want-Produkten und wird ignoriert, wenn der Betrag unter dem Mindestpreis des Produkts liegt.
paymentAmount verwendet größere Währungseinheiten (12.5 entspricht $12.50). Das Feld product_cart[].amount der Checkout Sessions API verwendet die kleinste Währungseinheit (1250 entspricht $12.50). Siehe Dynamic Pricing.
string
Benutzerdefinierte Metadatenfelder, zum Beispiel metadata_orderId=123.

Kundeninformationen vorab ausfüllen

Fügen Sie Kundenfelder als Query-Parameter hinzu, um den Checkout zu optimieren:
string
Vollständiger Name des Kunden (wird ignoriert, wenn firstName oder lastName angegeben ist).
string
Vorname des Kunden.
string
Nachname des Kunden.
string
E-Mail-Adresse des Kunden.
string
Land des Kunden (ISO 3166-1-alpha-2-Code).
string
Straßenadresse.
string
Stadt.
string
Bundesland oder Provinz.
string
Postleitzahl oder ZIP-Code.

Formularfelder deaktivieren

Um zu verhindern, dass Kunden vorausgefüllte Informationen ändern, deaktivieren Sie ein Feld, indem Sie dessen Wert angeben und das entsprechende disable...-Flag auf true setzen:
Das Deaktivieren von Feldern verhindert versehentliche Änderungen und gewährleistet die Datenkonsistenz.
Die Endpunkte POST /payments und POST /subscriptions sind veraltet. Verwenden Sie stattdessen Checkout Sessions für neue Integrationen.
Bei bestehenden Integrationen, die dynamische Payment Links verwenden, übergeben Sie payment_link: true an Create One-Time Payment oder Create Subscription, um einen Link zu erstellen. Die folgenden Beispiele erstellen einen Payment Link für eine einmalige Zahlung. Informationen zu Abonnements finden Sie im Subscription Integration Guide.

Webhooks

Webhooks informieren Ihren Server darüber, ob eine Zahlung erfolgreich war oder fehlgeschlagen ist, damit Sie die Bestellung erfüllen können.

Webhook-Endpunkt erstellen

Gehen Sie im Dashboard zu Developer → Webhooks und fügen Sie Ihre Endpunkt-URL hinzu. Kopieren Sie das Signaturgeheimnis des Endpunkts in die Umgebungsvariable DODO_PAYMENTS_WEBHOOK_KEY. Hier ist ein Beispiel mit Next.js:
app/api/webhooks/dodo/route.ts
Unsere Webhook-Implementierung folgt der Standard Webhooks-Spezifikation.

Ereignisse, auf die Sie hören sollten

Hören Sie in einem Ablauf für einmalige Zahlungen mindestens auf diese Ereignisse:
Erfüllen Sie die Bestellung immer anhand von payment.succeeded aus dem Webhook und nicht anhand der Browserweiterleitung. Die Weiterleitung kann verpasst werden, wenn der Kunde den Tab schließt, während der Webhook bis zur Bestätigung erneut gesendet wird.
Wenn Sie Produkte mit Lizenzschlüsseln verkaufen, behandeln Sie zusätzlich license_key.created. Die vollständige Liste der Ereignisse, einschließlich Abonnement-, Berechtigungs-, Guthaben-, Wiederherstellungs- und Mahn-Ereignissen, finden Sie im Webhook Event Guide. Ein vollständiges Next.js- und TypeScript-Beispiel finden Sie im Demo-Repository und in der Live-Bereitstellung.

Währung und Rechnungsadresse

Um in einer bestimmten Währung abzurechnen, übergeben Sie beim Erstellen der Checkout-Session billing_currency und billing_address.country. Wenn Sie diese Angaben weglassen, wählt Adaptive Currency Währung und Land anhand der IP-Adresse des Kunden aus. Dies muss nicht der Währung entsprechen, in der Sie abrechnen möchten. Pay What You Want-Beträge werden in der Basiswährung des Produkts angegeben, die USD, GBP oder EUR sein muss. Um einen festen Betrag in einer anderen Währung einzuziehen, verwenden Sie Adaptive Currency, das Ihren Basispreis zu aktuellen Wechselkursen umrechnet, oder Localized Pricing, das einen festen Preis pro Währung festlegt. Localized Pricing funktioniert nicht mit Pay What You Want.

Wiederholter Kauf mit einem Klick

Um einem wiederkehrenden Kunden mit einer gespeicherten Zahlungsmethode eine Zahlung zu berechnen, übergeben Sie deren payment_method_id zusammen mit confirm: true. payment_method_id wird nur akzeptiert, wenn confirm den Wert true hat. Außerdem müssen Sie customer_id des bestehenden Kunden übergeben. Da confirm den Wert true hat, müssen Sie außerdem einen vollständigen billing_address übergeben oder nur country und zipcode, wenn minimal_address den Wert true hat. Die Session belastet die gespeicherte Zahlungsmethode direkt und gibt daher keine checkout_url zurück. Verwenden Sie webhooks, um zu erfahren, ob die Zahlung erfolgreich war.

Verwandte Seiten

Checkout Sessions

Vollständige Anleitung mit erweiterten Anpassungsmöglichkeiten.

Overlay Checkout

Checkout als modales Overlay auf Ihrer Seite einbetten.

Inline Checkout

Checkout direkt in das Layout Ihrer Seite einbetten.

Subscription Integration

Wiederkehrende Abrechnung einrichten.

Webhook Event Guide

Vollständige Liste aller Webhook-Ereignisse.

API Reference

Dokumentation der Checkout Sessions API.
Zuletzt geändert am 8. Oktober 2026