Diese Seite behandelt das offizielle Dodo Payments React Native Checkout SDK,
@dodopayments/react-native-checkout. Es öffnet den von Dodo Payments gehosteten Checkout in einer nativen Browseransicht und gibt ein typisiertes Ergebnis zurück. Ein älteres Paket, dodopayments-react-native-sdk (unscoped), verfügt über eine andere API. Auf dieser Seite wird ausschließlich das scoped package dokumentiert.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.
SFSafariViewController unter iOS und einen Custom Tab unter Android. Es enthält keinen API key und keine eigene Checkout-Logik und ruft daher niemals die Dodo Payments API auf. Der Checkout läuft in der Browseransicht. Das SDK zeigt diese Ansicht an, schließt sie und liest das Ergebnis aus der return URL.
Installation
1
Install the Package
- Android
- iOS
- Expo
Das Paket wird automatisch verknüpft und lädt Die native Abhängigkeit wird automatisch aufgelöst, daher ist kein weiterer Installationsschritt erforderlich.
com.dodopayments.api:checkout-android aus Maven Central.2
Register a Callback URL Scheme
Registriere ein URL-Schema, damit das Betriebssystem die return URL des Checkouts zurück zu deiner App leitet.Lege auf jeder Plattform dieselbe URL wie
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
Lege das Schema in Ersetze
android/app/build.gradle als manifest placeholder fest:android/app/build.gradle
"myapp" durch das Schema deiner App.return_url der Checkout-Session fest, wenn dein Backend die Session erstellt. Das SDK vergleicht bei der return URL Schema, Host und Pfad. Die URL muss keine echte Seite laden.Verwendung
RufeDodoCheckout.start mit dem checkout_url aus deinem Backend auf:
onEvent empfängt Ereignisse mit einem type von checkout.opened, checkout.return_received oder checkout.closed. Verwende sie nur für das Logging, niemals zur Bestimmung des Ergebnisses.
Weiterleiten der Return URL
iOS benötigt den ListenerLinking zur Verarbeitung der return URL, da SFSafariViewController seine eigene return URL nicht abfangen kann. Unter Android führt handleOpenURL nichts aus und löst false auf, da das Android SDK seine Weiterleitung nativ abfängt. Du kannst den Listener auf beiden Plattformen registrieren.
handleOpenURL true auf, wenn die URL zum laufenden Checkout gehört, und false für jede andere URL.
Bedeutung des Ergebnisses
Das SDK erstellt das Ergebnis aus den query parameters der return URL.CheckoutStatus
erforderlich
Einer von fünf Werten:
succeeded: Die return URL enthältstatus=succeeded(Einmalzahlung) oderstatus=active(Subscription).failed: Die Zahlung wurde abgelehnt (status=failed).cancelled: Der Kunde hat die Browseransicht geschlossen, bevor die return URL eintraf. Das SDK kennt das Ergebnis nicht, und die Zahlung kann erfolgreich gewesen sein. Zeige daher keinen Fehlerbildschirm an. Gleiche stattdessen die abandoned session ab.pending: Die Zahlung wird später abgeschlossen (status=processingoder ein beliebigerrequires_*-Wert), oder der Parameterstatusfehlte oder wurde nicht erkannt. Gleiche sie wiecancelledab.expired: Die Checkout-Session ist abgelaufen (status=expired).
string
Der query parameter
payment_id, sofern die return URL einen enthält. Zeige ihn in deiner UI an, verwende ihn aber nicht zur Vergabe von Zugriff. Siehe Verify the Payment.string
Der query parameter
subscription_id. Wird für Subscription-Checkouts festgelegt.string[]
Der query parameter
license_key. Wird festgelegt, wenn der Checkout Produkte mit Lizenzschlüsseln enthält.string
Der query parameter
email. Wird festgelegt, wenn der Checkout eine E-Mail-Adresse erfasst.Record<string, string>
Jeder query parameter aus der return URL, unverändert.
Zahlung verifizieren
Webhooks
Dodo Payments ruft dein Backend auf, wenn eine Zahlung erfolgreich ist oder eine Subscription aktiviert wird.
Get Payment Detail
Rufe
paymentId mit deinem Secret Key ab, um den Status zu prüfen.result.status.
Darstellung anpassen
Um die Symbolleiste, Schaltflächen und das Farbschema des Checkout-Browsers zu ändern, übergibcustomization an start(...). Android Custom Tabs und iOS SFSafariViewController stellen unterschiedliche native Steuerelemente bereit. Deshalb sind die Optionen in ein android-Objekt und ein ios-Objekt gruppiert. Jede Plattform liest nur ihr eigenes Objekt. Jedes Feld ist optional. Wenn du ein Feld weglässt, verwendet die Plattform ihren eigenen Standardwert.
Android — Custom Tab
Android — Custom Tab
string
Hintergrundfarbe der Symbolleiste als Hex-String:
"#RRGGBB" oder "#AARRGGBB".Farbe der Navigationsleiste als Hex-String.
Farbe des Teilers über der Navigationsleiste als Hex-String.
'default' | 'back'
default zeigt das Systemsymbol “X” an. back zeigt einen vom SDK gezeichneten Zurück-Pfeil an.'start' | 'end'
Die Seite der Symbolleiste, auf der die Schaltfläche zum Schließen erscheint.
Zeigt das Teilen-Symbol der Symbolleiste an.
false blendet es aus.boolean
Zeigt den Seitentitel unter der URL in der Symbolleiste an.
boolean
Blendet die Symbolleiste beim Scrollen der Seite automatisch aus.
boolean
Zeigt “Bookmark this page” im Überlaufmenü an.
boolean
Zeigt “Download page” im Überlaufmenü an.
'system' | 'light' | 'dark'
light oder dark erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. system folgt der Systemeinstellung.iOS — SFSafariViewController
iOS — SFSafariViewController
'done' | 'close' | 'cancel'
Darstellung der Schaltfläche zum Schließen. iOS entscheidet, ob sie als Beschriftung oder Symbol gerendert wird.
'pageSheet' | 'fullScreen'
pageSheet (der Standardwert) zeigt eine Karte an, die der Kunde zum Schließen nach unten wischen kann. fullScreen nimmt den gesamten Bildschirm ein.boolean
Ermöglicht das Einklappen der Symbolleiste beim Scrollen der Seite. Dies wirkt sich nur aus, wenn
presentationStyle den Wert fullScreen hat. Bei pageSheet bleiben die Leisten unabhängig von dieser Einstellung fixiert.'system' | 'light' | 'dark'
light oder dark erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. system folgt der Systemeinstellung.SFSafariViewController ab iOS 26 veraltet sind.
Fehler
start wird nur bei Fehlverwendung oder einem Plattformfehler mit einem CheckoutError abgelehnt. Lies den Grund aus error.code. Ein Kunde, der abbricht, oder eine abgelehnte Zahlung ist immer ein Ergebnis, niemals eine Ablehnung.
INVALID_CHECKOUT_URL:checkoutUrlist keinehttpsCheckout-Session-URL (Pfad beginnend mit/session/) aufcheckout.dodopayments.comodertest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrlist keine absolute URL mit Schema und Host.ALREADY_IN_PROGRESS: Ein anderer Checkout läuft bereits. Es kann immer nur ein Checkout gleichzeitig ausgeführt werden.PLATFORM_ERROR: Ein unerwarteter Plattformfehler. Das SDK meldet auch jeden nicht erkannten nativen Fehler mit diesem Code.
Abandoned Sessions
Das native SDK zeichnet die Checkout-Session beim Start des Checkouts auf und löscht den Eintrag nur, wenn der Checkout mitsucceeded, failed oder expired endet. Der Eintrag bleibt bestehen, wenn die App oder das JavaScript-Bundle während des Checkouts beendet wird, wodurch das start-Promise verloren geht, sowie nach einem Ergebnis cancelled oder pending. Prüfe beim nächsten Mounting und nach jedem Ergebnis cancelled oder pending darauf:
abandoned.sessionId ist die ID der Checkout-Session, die mit cks_ beginnt. abandoned.createdAt ist der Zeitpunkt, an dem der Date-Checkout gestartet wurde. Dein Backend kann die Session mit Get Checkout Session abrufen. Diese liefert payment_id und payment_status. Bis die Zahlung einen finalen Status erreicht, behandle sie als ausstehend, nicht als fehlgeschlagen.
Verwandte Inhalte
Mobile Integration Guide
Derselbe Vertrag für Android, iOS und Flutter.
Expo Boilerplate
Ein vollständiges Expo-Beispiel mit Checkout-Integration.