Skip to main content
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.
Das React Native SDK ist ein Turbo Module, das die nativen iOS- und Android-Checkout-SDKs kapselt. Es öffnet 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.
Dieses SDK unterstützt ausschließlich die New Architecture. Es erfordert React Native 0.77 oder höher, iOS 16 oder höher und Android minSdk 24. Deine Android-App muss mit compileSdk 34 oder höher erstellt werden.

Installation

1

Install the Package

Das Paket wird automatisch verknüpft und lädt com.dodopayments.api:checkout-android aus Maven Central.
Die native Abhängigkeit wird automatisch aufgelöst, daher ist kein weiterer Installationsschritt erforderlich.
Appearance customization erfordert Version 1.2.0 oder höher.
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 das Schema in android/app/build.gradle als manifest placeholder fest:
android/app/build.gradle
Ersetze "myapp" durch das Schema deiner App.
Lege auf jeder Plattform dieselbe URL wie 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

Rufe DodoCheckout.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 Listener Linking 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.
Unter iOS löst 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.
result.status ist ein UI-Hinweis, kein Zahlungsnachweis. Bestätige jede Zahlung in deinem Backend mit dem Webhook payment.succeeded oder subscription.active.
CheckoutStatus
erforderlich
Einer von fünf Werten:
  • succeeded: Die return URL enthält status=succeeded (Einmalzahlung) oder status=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=processing oder ein beliebiger requires_*-Wert), oder der Parameter status fehlte oder wurde nicht erkannt. Gleiche sie wie cancelled ab.
  • 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.
Gewähre Zugriff erst, nachdem eine dieser Methoden die Zahlung bestätigt hat. Verlasse dich nicht allein auf result.status.

Darstellung anpassen

Um die Symbolleiste, Schaltflächen und das Farbschema des Checkout-Browsers zu ändern, übergib customization 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.
string
Hintergrundfarbe der Symbolleiste als Hex-String: "#RRGGBB" oder "#AARRGGBB".
string
Farbe der Navigationsleiste als Hex-String.
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.
boolean
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.
'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.
iOS bietet keine Option für die Farbe der Symbolleiste, da die zugrunde liegenden Tint-Eigenschaften von 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: checkoutUrl ist keine https Checkout-Session-URL (Pfad beginnend mit /session/) auf checkout.dodopayments.com oder test.checkout.dodopayments.com.
  • INVALID_RETURN_URL: returnUrl ist 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 mit succeeded, 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.
Zuletzt geändert am 26. September 2026