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 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
pubspec.yaml hinzu:pubspec.yaml
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.- iOS
- Android
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
RufeDodoCheckout.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 erstelltCheckoutResult aus den Query-Parametern der Rückgabe-URL.
CheckoutStatus
erforderlich
Einer von fünf Werten:
succeeded: Die Rückgabe-URL enthältstatus=succeeded(einmalige Zahlung) oderstatus=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=processingoder ein beliebigerrequires_*-Wert), oder der Parameterstatusfehlte oder war unbekannt. Gleiche sie wiecancelledab.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.result.status.
Darstellung anpassen
Um die Symbolleiste, Schaltflächen und das Farbschema des Checkout-Browsers zu ändern, übergib einBrowserCustomization 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.
Android — Custom Tab
Android — Custom Tab
Color?
Hintergrundfarbe der Symbolleiste.
Farbe der Navigationsleiste.
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.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.iOS — SFSafariViewController
iOS — SFSafariViewController
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.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):checkoutUrlist keinehttps-Checkout-Sitzungs-URL (Pfad beginnend mit/session/) aufcheckout.dodopayments.comodertest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlist 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.