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.
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ückgegebenecheckout_url weiter.
Checkout-Session erstellen
- Node.js SDK
- Python SDK
- cURL
Zum Checkout weiterleiten
Leiten Sie den Kunden nach dem Erstellen einer Session an diecheckout_url weiter:
Fehler behandeln
Wenn eine Anfrage fehlschlägt, gibt die API einen HTTP status code und einen JSON-Body mit einemcode 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.
Payment Links
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 einensession-Parameter, sodass sie bei einer Seitenaktualisierung erhalten bleiben.
Statische Payment Links
Ein statischer Payment Link ist eine URL, die Sie einmal erstellen und mehrfach teilen. Die Basis-URL lautet: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.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 entsprechendedisable...-Flag auf true setzen:
Beispiel für einen statischen Payment Link
Dynamische Payment Links (veraltet)
Bei bestehenden Integrationen, die dynamische Payment Links verwenden, übergeben Siepayment_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.
- Node.js SDK
- Python SDK
- Go SDK
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 UmgebungsvariableDODO_PAYMENTS_WEBHOOK_KEY.
Hier ist ein Beispiel mit Next.js:
app/api/webhooks/dodo/route.ts
Ereignisse, auf die Sie hören sollten
Hören Sie in einem Ablauf für einmalige Zahlungen mindestens auf diese Ereignisse:
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-Sessionbilling_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 derenpayment_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.