Skip to main content

Quick Start

Create your first checkout session in under 5 minutes

API Reference

Full API documentation and interactive testing

Preview Endpoint

Calculate pricing and taxes before creating a session
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when confirm: true.
Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

Prerequisites

You need:
  • An active Dodo Payments merchant account
  • API credentials from Developer → API Keys in the dashboard
  • At least one product created in Products

Creating Your First Checkout Session

API Response

All methods return:
Only session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead. When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.

Redirect Your Customer

1

Extract the checkout URL

Get checkout_url from the API response.
2

Redirect to checkout

Send your customer to the URL:
Alternatively, open in a new window:
3

Handle the return

After payment, customers are redirected to your return_url with query parameters:Example redirect:
Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

Sitzungsstatus prüfen

Um den Status einer Sitzung zu prüfen, rufen Sie Get Checkout Session (GET /checkouts/{id}) auf. Die Antwort enthält id, created_at, customer_email und customer_name der Sitzung sowie payment_id und payment_status. Beide Zahlungsfelder sind null, solange der Kunde noch seine Daten eingibt. Nachdem der Kunde die Zahlung übermittelt hat, enthält payment_status den Zahlungsstatus, z. B. succeeded, failed oder processing. Verwenden Sie Webhooks als maßgebliche Quelle für die Erfüllung.

Anfragetext

Erforderliche Felder

array
erforderlich
Array von Produkten, die in die Checkout-Sitzung aufgenommen werden sollen. Jedes Produkt muss eine gültige product_id aus Ihrem Dashboard haben.Sie können Produkte mit einmaliger Zahlung mit einem Abonnementprodukt in derselben Sitzung kombinieren. Ein Warenkorb kann auch zwei oder mehr Abonnementprodukte enthalten, darf dann aber keine Produkte mit einmaliger Zahlung enthalten. Siehe Warenkorb mit mehreren Abonnements. Ein Warenkorb enthält höchstens 20 Produkte.
Ihre Produkt-IDs finden: Produkt-IDs finden Sie in Ihrem Dodo Payments-Dashboard unter Products → View Details oder über die List Products API.

Optionale Felder

object
Kundeninformationen. Sie können entweder einen bestehenden Kunden anhand seiner ID anhängen oder während des Checkouts einen neuen Kundendatensatz erstellen.
object
Rechnungsadressinformationen für eine genaue Steuerberechnung, Betrugsprävention und die Einhaltung gesetzlicher Vorschriften.Wenn confirm: true, werden alle Felder der Rechnungsadresse erforderlich, es sei denn, minimal_address ist true.
array
Steuern Sie, welche Zahlungsmethoden Kunden während des Checkouts verwenden können. Dies hilft bei der Optimierung für bestimmte Märkte oder geschäftliche Anforderungen.Häufige Optionen: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalDie vollständige Liste finden Sie in der Create Checkout Session API reference.
Fügen Sie credit und debit immer als Fallback-Optionen hinzu, um Checkout-Fehler zu vermeiden, wenn bevorzugte Zahlungsmethoden nicht verfügbar sind.
Beispiel:
string
Überschreiben Sie die standardmäßige Währungsauswahl mit einer festen Abrechnungswährung. Verwendet ISO-4217-Währungscodes.Unterstützte Währungen: USD, EUR, GBP, CAD, AUD, INR und weitereBeispiel: "USD" für US-Dollar, "EUR" für EuroDieses Feld ist nur wirksam, wenn adaptive pricing aktiviert ist. Wenn adaptive pricing deaktiviert ist, verwirft die API dieses Feld und die Währung wird aus dem Produktpreis oder dem Rechnungsland übernommen.
boolean
Standard:"false"
Zeigen Sie zuvor gespeicherte Zahlungsmethoden für wiederkehrende Kunden an, um Checkout-Geschwindigkeit und Benutzererfahrung zu verbessern.
string
URL, an die Kunden nach Abschluss der Zahlung weitergeleitet werden. Dodo Payments fügt Ihrer URL bei der Weiterleitung Query-Parameter hinzu (siehe die obige Weiterleitungstabelle).Beispiele für Weiterleitungs-URLs:
Verwenden Sie die Query-Parameter license_key und email, um Lizenzschlüssel anzuzeigen oder direkt auf Ihrer Rückkehrseite eine Bestätigung zu senden, ohne einen zusätzlichen API-Aufruf zu benötigen.
string
URL, an die Kunden weitergeleitet werden, wenn sie auf die Zurück-Schaltfläche klicken oder die Checkout-Sitzung abbrechen. Wenn sie nicht angegeben ist, wird die Zurück-Schaltfläche nicht angezeigt.Legen Sie eine cancel_url fest, um Kunden eine klare Möglichkeit zu geben, zu Ihrer Website zurückzukehren, ohne den Kauf abzuschließen.
boolean
Standard:"false"
Wenn true, werden alle Sitzungsdetails sofort finalisiert. Die API gibt einen Fehler aus, wenn erforderliche Daten fehlen.Wenn confirm: true:
  • Alle Felder der Rechnungsadresse werden erforderlich (nur country und zipcode, wenn minimal_address true ist)
  • payment_method_id kann angegeben werden, um die Belastung sofort zu verarbeiten
  • Die Sitzung läuft nach 15 Minuten statt nach 24 Stunden ab
  • Ein vorhandener customer_id ist erforderlich, wenn payment_method_id angegeben wird
array
Wenden Sie einen oder mehrere gestapelte Rabattcodes auf die Checkout-Sitzung an. Codes werden in Array-Reihenfolge angewendet (der erste Code reduziert den Ausgangspreis, der zweite den bereits reduzierten Preis usw.), bis zu maximal 20 Codes pro Sitzung.Wenn Purchasing Power Parity aktiviert ist, ist der Ausgangspreis der PPP-angepasste Betrag und nicht der Basispreis.
Das einzelne Feld discount_code unten ist veraltet, wird aber weiterhin vollständig unterstützt. Es kann in derselben Anfrage nicht mit discount_codes kombiniert werden.
string
veraltet
Veraltet – Verwenden Sie für neue Integrationen bevorzugt discount_codes. Dieses Feld funktioniert aus Gründen der Abwärtskompatibilität weiterhin, kann aber in derselben Anfrage nicht mit discount_codes kombiniert werden.
object
Benutzerdefinierte Schlüssel-Wert-Paare zum Speichern zusätzlicher Informationen über die Sitzung.
boolean
Überschreiben Sie das standardmäßige 3DS-Verhalten des Händlers für diese Sitzung.
boolean
Standard:"false"
Aktivieren Sie den Modus zur Erfassung einer minimalen Adresse. Wenn aktiviert, erfasst der Checkout nur:
  • Land: Immer für die Steuerbestimmung erforderlich
  • ZIP-/Postleitzahl: Nur in Regionen, in denen sie für die Berechnung von Umsatzsteuer, VAT oder GST erforderlich ist
Dadurch wird der Checkout erheblich vereinfacht, da unnötige Formularfelder entfallen.Mit confirm: true ist nur zipcode (zusätzlich zu country) erforderlich; die übrigen Felder der Rechnungsadresse bleiben optional.
string
Eine gespeicherte Zahlungsmethode des verknüpften Kunden. Erfordert confirm: true und ein vorhandenes customer.customer_id. Die Eignung der Zahlungsmethode wird anhand der Währung der Zahlung validiert. Wenn dieser Wert gesetzt ist, wird die Belastung sofort verarbeitet und checkout_url als null zurückgegeben. Verwenden Sie stattdessen das zurückgegebene payment_id.
Wenn true, wird eine verkürzte Checkout-URL anstelle der vollständigen Sitzungs-URL zurückgegeben.
string
Produktkollektions-ID für den Checkout-Ablauf auf Basis einer Sammlung. Wenn Sie sie festlegen, übergeben Sie ein leeres product_cart-Array. Rabattcodes können bei der Sitzungserstellung nicht vorab angewendet werden. Siehe Produktkollektionen.
string
Steuer-ID des Kunden (z. B. eine Umsatzsteuer-ID). Erfordert billing_address mit einer country.
string
Optionaler geschäftlicher oder rechtlicher Name, der der Steuer-ID zugeordnet ist, mit bis zu 250 Zeichen. Wenn er zusammen mit einem gültigen tax_id angegeben wird, erscheint er auf der Rechnung anstelle des persönlichen Namens des Kunden.
integer
Überschreiben Sie den Mandatsgrenzwert auf Händlerebene (in INR-Paise) für INR-E-Mandate auf indischen Karten.Der an den Prozessor gesendete Mandatsbetrag ist max(this_floor, actual_billing_amount). Dieser Wert stellt daher effektiv die kundenorientierte Autorisierungsobergrenze dar, wenn die Abrechnung niedriger ist. Wenn kein Wert festgelegt ist, gilt die Händlereinstellung. Ist auch diese nicht festgelegt, gilt der Systemstandard von ₹15.000.
object
Passen Sie das Erscheinungsbild und Verhalten der Checkout-Oberfläche an.
object
Konfigurieren Sie bestimmte Funktionen und Verhaltensweisen für die Checkout-Sitzung.
array
Erfassen Sie während des Checkouts mit benutzerdefinierten Formularfeldern zusätzliche Kundeninformationen. Sie können bis zu 5 benutzerdefinierte Felder pro Checkout-Sitzung definieren. Kundenantworten sind in Webhook-Payloads enthalten und über die API verfügbar.
Kundenantworten auf benutzerdefinierte Felder sind enthalten in:
  • Webhooks: payment.succeeded, subscription.active und andere relevante Event-Payloads enthalten das custom_field_responses-Array
  • API-Antworten: Payment- und Subscription-Objekte enthalten custom_field_responses
object
Zusätzliche Konfiguration für Checkout-Sitzungen mit Abonnementprodukten.

Anwendungsbeispiele

Einfacher Checkout für ein einzelnes Produkt

Warenkorb mit mehreren Produkten

Warenkorb mit mehreren Abonnements

Um mehrere Abonnementprodukte in einem Checkout zu verkaufen, fügen Sie product_cart zwei oder mehr Abonnementprodukte hinzu. Der Kunde bezahlt einmal und Dodo Payments erstellt eine Zahlung, eine Rechnung und ein Abonnement für jedes Produkt. Jedes Abonnement hat einen eigenen Abrechnungszyklus und wird unabhängig verlängert. Daher können sich ein monatliches und ein jährliches Produkt denselben Warenkorb teilen.
Ein Warenkorb mit mehreren Abonnements unterliegt folgenden Einschränkungen:
  • Er kann keine Produkte mit einmaliger Zahlung enthalten. Die API lehnt die Anfrage mit einem 422 ab.
  • Er enthält höchstens 20 Abonnementprodukte.
  • Er kann dasselbe Produkt nicht zweimal enthalten. Um mehr als eine Einheit eines Produkts zu verkaufen, legen Sie stattdessen quantity fest.
  • Er kann keine On-demand-Abrechnung verwenden (subscription_data.on_demand).
  • Ein auf den Warenkorb angewendeter Rabattcode zählt als eine Einlösung.
subscription_data.trial_period_days gilt für jedes Abonnement im Warenkorb. Ohne diesen Wert verwendet jedes Abonnement den für sein eigenes Produkt festgelegten Testzeitraum. Wenn Sie ihn nicht festlegen und Missbrauch von Testzeiträumen verhindern aktiviert ist, startet ein Produkt, das der Kunde bereits getestet hat, ohne Testzeitraum. Die daraus resultierende Zahlung enthält is_multi_subscription: true und listet jedes gestartete Abonnement in subscription_ids auf. Ihr subscription_id ist null, da kein einzelnes Abonnement die Zahlung besitzt. Der Webhook payment.succeeded enthält dieselben Felder. Lesen Sie is_multi_subscription, um den Zahlungstyp zu ermitteln, nicht die Länge von subscription_ids. Nach erfolgreicher Zahlung erhalten Sie ein payment.succeeded-Ereignis für den Warenkorb und ein subscription.active-Ereignis für jedes Abonnement. Danach verlängert, ändert und kündigt sich jedes Abonnement unabhängig mit einer eigenen Rechnung für jede Verlängerung. Alle Abonnements aus einem Warenkorb verwenden dieselbe Zahlungsmethode, die der Kunde beim Checkout genutzt hat. Wenn Sie die Zahlungsmethode eines dieser Abonnements aktualisieren, überträgt Dodo Payments die neue Zahlungsmethode auf jedes Abonnement aus demselben Warenkorb, das dieselbe Abrechnungs- und Abwicklungswährung hat und active, on_hold, past_due oder paused ist. Jedes Abonnement aus einem Warenkorb startet mit derselben Abwicklungs- und Abrechnungswährung, auch wenn die Produkte unterschiedliche Preiswährungen haben. Eine spätere Änderung, etwa ein Planwechsel, kann ein Abonnement in eine andere Abwicklungs- oder Abrechnungswährung verschieben. Dieses Abonnement behält seine alte Zahlungsmethode, sodass Sie sie separat aktualisieren müssen. Bei einem on_hold-Abonnement wiederholt die Aktualisierung nur die unbezahlte Rechnung dieses Abonnements.

Abonnement mit Testzeitraum

Vorbestätigter Checkout

Checkout mit Währungsüberschreibung

Gespeicherte Zahlungsmethoden für wiederkehrende Kunden

B2B-Checkout mit Erfassung der Tax ID

Checkout mit dunklem Theme und gestapelten Rabattcodes

Regionale Zahlungsmethoden (UPI für Indien)

Ausführliche Informationen zur Konfiguration und zum Testen von UPI finden Sie auf der Seite Zahlungsmethoden in Indien.

BNPL-Checkout (Buy Now, Pay Later)

Ausführliche Informationen zur Konfiguration und zum Testen von BNPL finden Sie auf der Seite Buy Now, Pay Later (BNPL).

Sofortiger Checkout mit vorhandener Zahlungsmethode

Zahlungsbestätigungsseite überspringen und sofort weiterleiten

Sprache erzwingen

Benutzerdefinierte Felder erfassen

Checkout-Sitzungen in der Vorschau anzeigen

Verwenden Sie den Endpunkt Checkout-Sitzung in der Vorschau anzeigen, um Preise, Steuern und Summen vor der Erstellung einer Sitzung zu berechnen. Dies ist nützlich, um auf Ihrer Website genaue Preisinformationen anzuzeigen.
Das in der Vorschau angezeigte current_breakup.subtotal berücksichtigt bereits Purchasing Power Parity und Charm Pricing, sofern diese auf das Produkt zutreffen.
Wenn der Warenkorb ein Abonnementprodukt enthält, gibt die Vorschauantwort außerdem ein next_billing_date zurück – eine Vorschau des bevorstehenden Abrechnungsdatums, damit Sie es vor der Erstellung des Abonnements anzeigen können. Es wird relativ zum aktuellen Zeitpunkt berechnet: now + trial period, wenn ein Testzeitraum gilt, andernfalls now + one payment frequency. Bei Warenkörben, die ausschließlich Produkte mit einmaliger Zahlung enthalten, wird das Feld nicht angegeben. Dies ist eine auf den Zeitpunkt der Vorschau bezogene Schätzung; das maßgebliche next_billing_date wird festgelegt, wenn das Abonnement aktiviert wird.
Die Vorschau gibt außerdem trial_period_days (die effektive Dauer des kostenlosen oder kostenpflichtigen Testzeitraums) und trial_amount (die Gebühr pro Einheit für den Testzeitraum nach Rabatten, in den kleinsten Einheiten der Preiswährung) zurück. trial_amount ist nur bei einem kostenpflichtigen Testzeitraum vorhanden und bei einem kostenlosen Testzeitraum oder keinem Testzeitraum null. Verwenden Sie current_breakup für den tatsächlich heute fälligen, versteuerten Gesamtbetrag.
Bei einem Warenkorb mit mehreren Abonnements gibt die Antwort außerdem ein subscriptions-Array mit einem Eintrag pro Abonnement zurück: product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days und next_billing_date. Das next_billing_date auf oberster Ebene ist das früheste Datum im Warenkorb. trial_period_days und trial_amount auf oberster Ebene sind null. Lesen Sie Beträge aus subscriptions und current_breakup. recurring_breakup summiert die Verlängerungsbeträge aller Abonnements, auch wenn sie an unterschiedlichen Daten verlängert werden. Lesen Sie daher jede Verlängerung aus subscriptions.
Wenn Sie Dynamic Links verwenden, bieten Checkout-Sitzungen mehr Flexibilität. Bei Dynamic Links mussten Sie die vollständige Rechnungsadresse des Kunden angeben. Bei Checkout-Sitzungen können Sie beliebige verfügbare Informationen übergeben, und der Checkout-Ablauf erfasst die übrigen Daten. Zum Beispiel:
  • Geben Sie nur das Rechnungsland des Kunden an, und der Checkout erfasst die übrigen Daten.
  • Oder geben Sie alle Informationen an und setzen Sie confirm: true, um direkt zur Zahlungsseite zu gelangen.
Die Migration ist unkompliziert: Aktualisieren Sie Ihre Integration, um die Checkout-Sessions-API oder die entsprechende SDK-Methode zu verwenden, passen Sie die Request-Payload an das Format der Checkout-Sessions an, und Sie sind fertig. Eine zusätzliche Verarbeitung ist nicht erforderlich.

Verwandte Ressourcen

Overlay Checkout

Checkout als modales Overlay auf Ihrer Seite öffnen

Inline Checkout

Checkout direkt in Ihre Seite einbetten

Mobile Integration

Checkout in nativen mobilen Apps integrieren

Webhooks

Auf Zahlungs- und Abonnementereignisse reagieren

Payment Methods

Unterstützte Zahlungsmethoden nach Region

Subscriptions

Wiederkehrende Abrechnung und Abonnementverwaltung
Zuletzt geändert am 8. Oktober 2026