Skip to main content
Diese Seite behandelt das offizielle Flutter-Paket von Dodo Payments, dodopayments_checkout auf pub.dev. Es gibt außerdem ein separates, von der Community entwickeltes Paket. Siehe Community-Projekte.

Checkout Sessions API

Erstelle das checkout_url, das dieses SDK öffnet, in deinem Backend.

Mobile Integration Guide

Erfahre, wie dieses SDK in den vollständigen mobilen Zahlungsablauf passt.
dodopayments_checkout öffnet den von Dodo Payments gehosteten Checkout in SFSafariViewController unter iOS und in einem Custom Tab unter Android und gibt ein typisiertes CheckoutResult zurück. Es verwendet denselben nativen Code wie die eigenständigen iOS- und Android-SDKs; die gesamte Checkout-Logik befindet sich in diesem nativen Code. Die Dart-Schicht leitet jeden Aufruf über einen typisierten Pigeon-Kanal weiter. Das Paket enthält keinen API-Schlüssel und ruft niemals die Dodo Payments API auf. Voraussetzungen: Flutter 3.44 oder höher mit Dart 3.12 oder höher, iOS 16 oder höher sowie Android minSdk 23.

Installation

1

Add the Dependency

Füge das Paket zu pubspec.yaml hinzu:
pubspec.yaml
Darstellung anpassen erfordert Version 1.1.0 oder höher.Das Android-Plugin wird standardmäßig gegen Android SDK 35 kompiliert. Wenn ein anderes Plugin eine höhere compileSdk benötigt, setze dodoCompileSdk in der gradle.properties deiner App.
2

Register a Callback URL Scheme

Registriere ein URL-Schema, damit das Betriebssystem die Rückgabe-URL des Checkouts wieder an deine App weiterleitet. Verwende dieses Schema in der returnUrl, die du an das SDK übergibst, und setze dieselbe URL als return_url der Checkout-Sitzung, wenn dein Backend die Sitzung erstellt. Die URL muss keine echte Seite laden.
Füge in ios/Runner/Info.plist einen URL-Typ für dein Schema hinzu:
ios/Runner/Info.plist
SFSafariViewController kann seine eigene Rückgabe-URL nicht abfangen, daher öffnet iOS die URL stattdessen in deiner App. Leite jede eingehende URL an das SDK weiter, zum Beispiel über app_links:
Du kannst jede URL weiterleiten. handleOpenURL wird nur bei einer URL aktiv, die mit der returnUrl des laufenden Checkouts übereinstimmt, und löst dafür true auf. Für jede andere URL wird false aufgelöst. Unter Android wird immer false aufgelöst.

Verwendung

Rufe DodoCheckout.instance.start mit dem checkout_url aus deinem Backend auf:
onEvent empfängt Events, deren type CheckoutEventType.opened, returnReceived oder closed ist. Verwende sie nur für das Logging, niemals zur Bestimmung des Ergebnisses.

Bedeutung des Ergebnisses

Das SDK erstellt CheckoutResult aus den Query-Parametern der Rückgabe-URL.
result.status ist ein UI-Hinweis und kein Zahlungsnachweis. Bestätige jede Zahlung über dein Backend mit dem payment.succeeded- oder subscription.active-Webhook.
CheckoutStatus
erforderlich
Einer von fünf Werten:
  • succeeded: Die Rückgabe-URL enthält status=succeeded (einmalige Zahlung) oder status=active (Abonnement).
  • failed: Die Zahlung wurde abgelehnt (status=failed).
  • cancelled: Der Kunde hat die Browseransicht geschlossen, bevor die Rückgabe-URL eingegangen ist. Das SDK kennt das Ergebnis nicht, und die Zahlung kann erfolgreich gewesen sein; zeige daher keinen Fehlerbildschirm an. Gleiche stattdessen die abgebrochene Sitzung ab.
  • pending: Die Zahlung wird später abgeschlossen (status=processing oder ein beliebiger requires_*-Wert), oder der Parameter status fehlte oder war unbekannt. Gleiche sie wie cancelled ab.
  • expired: Die Checkout-Sitzung ist abgelaufen (status=expired).
String?
Der Query-Parameter payment_id, sofern die Rückgabe-URL ihn enthält. Zeige ihn in deiner Benutzeroberfläche an, verwende ihn jedoch nicht, um Zugriff zu gewähren. Siehe Zahlung überprüfen.
String?
Der Query-Parameter subscription_id. Wird für Abonnement-Checkouts gesetzt.
List<String>?
Der Query-Parameter license_key. Wird gesetzt, wenn der Checkout Produkte mit Lizenzschlüsseln enthält.
String?
Der Query-Parameter email. Wird gesetzt, wenn der Checkout eine E-Mail-Adresse erfasst.
Map<String, String>
Jeder Query-Parameter der Rückgabe-URL, unverändert.

Zahlung überprüfen

Webhooks

Dodo Payments ruft dein Backend auf, wenn eine Zahlung erfolgreich ist oder ein Abonnement aktiviert wird.

Get Payment Detail

Rufe paymentId mit deinem geheimen Schlüssel ab, um den Status zu überprüfen.
Gewähre den Zugriff erst, wenn eine dieser Möglichkeiten die Zahlung bestätigt. Verlasse dich nicht allein auf result.status.

Darstellung anpassen

Um die Symbolleiste, Schaltflächen und das Farbschema des Checkout-Browsers zu ändern, übergib ein BrowserCustomization als customization an CheckoutParams. Android Custom Tabs und iOS SFSafariViewController stellen unterschiedliche native Steuerelemente bereit, daher sind die Optionen in AndroidBrowserOptions und IosBrowserOptions aufgeteilt. Jede Plattform ignoriert die Optionen der jeweils anderen. Jedes Feld ist optional und verwendet standardmäßig null. Bei einem null-Feld setzt das SDK diese Option nicht, und die Plattform verwendet ihre eigene Standardeinstellung.
Color?
Hintergrundfarbe der Symbolleiste.
Color?
Farbe der Navigationsleiste.
Color?
Farbe der Trennlinie über der Navigationsleiste.
CloseButtonStyle?
standard zeigt das systemeigene „X“-Symbol. back zeigt einen Zurück-Pfeil, den das SDK zeichnet.
CloseButtonPosition?
Die Seite der Symbolleiste, auf der die Schaltfläche zum Schließen erscheint: start oder end.
bool?
Zeigt das Teilen-Symbol der Symbolleiste an. false blendet es aus.
bool?
Zeigt den Seitentitel unter der URL in der Symbolleiste an.
bool?
Blendet die Symbolleiste beim Scrollen der Seite automatisch aus.
bool?
Zeigt „Diese Seite mit einem Lesezeichen versehen“ im Überlaufmenü an.
bool?
Zeigt „Seite herunterladen“ im Überlaufmenü an.
BrowserColorScheme?
light oder dark erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. system folgt der Systemeinstellung.
DismissButtonStyle?
Stil der Schaltfläche zum Schließen: done, close oder cancel. iOS entscheidet, ob sie als Beschriftung oder Symbol dargestellt wird.
PresentationStyle?
pageSheet (wird verwendet, wenn du dieses null beibehältst) zeigt eine Karte an, die der Kunde zum Schließen nach unten wischen kann. fullScreen nimmt den gesamten Bildschirm ein.
bool?
Ermöglicht das Einklappen der Symbolleiste beim Scrollen der Seite. Dies wirkt sich nur aus, wenn presentationStyle auf fullScreen gesetzt ist. Bei pageSheet bleiben die Leisten unabhängig von dieser Einstellung fixiert.
BrowserColorScheme?
light oder dark erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. system folgt der Systemeinstellung.
iOS bietet keine Option für die Farbe der Symbolleiste, da die zugrunde liegenden Tint-Eigenschaften von SFSafariViewController seit iOS 26 veraltet sind.

Fehler

start löst CheckoutException nur bei falscher Verwendung oder einem Plattformfehler aus. Lies den Grund aus code, einem CheckoutErrorCode. Der native Code-String befindet sich in nativeCode. Ein Kunde, der abbricht, oder eine abgelehnte Zahlung ist immer ein Ergebnis und niemals eine Exception.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl ist keine https-Checkout-Sitzungs-URL (Pfad beginnend mit /session/) auf checkout.dodopayments.com oder test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl ist keine absolute URL mit einem Schema und einem Host.
  • alreadyInProgress (ALREADY_IN_PROGRESS): Ein anderer Checkout läuft bereits. Es kann immer nur ein Checkout gleichzeitig ausgeführt werden.
  • platformError (PLATFORM_ERROR): unerwarteter Plattformfehler. Unbekannte native Fehler werden ebenfalls diesem Code zugeordnet.

Abgebrochene Sitzungen

Das native SDK speichert die Checkout-Sitzung, sobald der Checkout beginnt, und löscht den Eintrag nur, wenn der Checkout mit succeeded, failed oder expired endet. Der Eintrag bleibt bestehen, wenn die App während des Checkouts beendet wird oder nach einem Ergebnis vom Typ cancelled oder pending. Prüfe beim nächsten Start und nach jedem Ergebnis vom Typ cancelled oder pending, ob ein solcher Eintrag vorhanden ist.
abandoned.sessionId ist die ID der Checkout-Sitzung, die mit cks_ beginnt. abandoned.createdAt ist der DateTime, zu dem der Checkout gestartet wurde. Dein Backend kann die Sitzung mit Get Checkout Session abrufen. Dabei werden payment_id und payment_status zurückgegeben. Behandle die Zahlung, bis sie einen endgültigen Status erreicht, als ausstehend und nicht als fehlgeschlagen.

Verwandte Themen

Mobile Integration Guide

Derselbe Vertrag für Android, iOS und React Native.

Community Projects

Es gibt außerdem ein separates, von der Community entwickeltes Flutter-Paket.
Zuletzt geändert am 26. September 2026