React Native

Dies ist das offizielle Dodo Payments React Native Checkout SDK, @dodopayments/react-native-checkout. Es öffnet den gehosteten Checkout von Dodo in einer nativen Browseransicht und gibt ein typisiertes Ergebnis zurück. Hinweis: Es gibt ein älteres, nicht verwandtes Paket namens dodopayments-react-native-sdk (unscoped) mit einer vollständig anderen API. Diese Seite dokumentiert ausschließlich das aktuelle offizielle Scoped-Paket.

Checkout Sessions API

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

Mobile Integration Guide

Erfahre, wie dies in den vollständigen mobilen Zahlungsablauf passt.

Das React Native SDK ist ein schlanker Turbo-Module-Wrapper über denselben nativen Swift- und Kotlin-Kern. Es öffnet SFSafariViewController auf iOS und einen Chrome Custom Tab auf Android, enthält keinen API-Schlüssel und ruft die Dodo API niemals direkt auf. Die gesamte Checkout-Logik läuft im Browser; das SDK verwaltet lediglich den Lebenszyklus der Ansicht und erfasst die Return-URL.

Dieses SDK erfordert ausschließlich New Architecture, React Native 0.76+, iOS 16+ und Android minSdk 24.

Installation

Install the Package

Android
iOS
Expo

Das Paket wird automatisch verknüpft und ruft com.dodopayments.api:checkout-android aus Maven ab.

npm i @dodopayments/react-native-checkout

Keine zusätzliche Einrichtung erforderlich; die native Abhängigkeit wird automatisch aufgelöst.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Der Swift-Kern ist im Paket enthalten und wird über CocoaPods installiert.

Nur für Development Builds (nicht Expo Go).

npm i @dodopayments/react-native-checkout

Konfiguriere anschließend dein app.json (siehe unten unter „Callback-URL-Schema registrieren“).

Deine App muss ein URL-Schema registrieren, um die Return-URL vom Checkout zu empfangen.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

In android/app/build.gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Ersetze "myapp" durch das Schema deiner App.

In ios/YourApp/Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Du kannst dies auch über die Xcode-Benutzeroberfläche Info → URL Types hinzufügen.

Das eigene Konfigurations-Plugin des Pakets registriert das Schema für beide Plattformen unter prebuild. Übergebe ihm eine scheme-Option in app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme muss mit dem übereinstimmen, was du als returnUrl übergibst (z. B. myappcheckout://return), und muss sich von expo.scheme unterscheiden. Expo registriert dieses bereits unter MainActivity. Wenn du es wiederverwendest, kann die Rückkehr von der Checkout-Seite zum falschen Bildschirm geleitet werden.Erstelle das native Projekt nach der Bearbeitung von app.json neu:

npx expo prebuild --clean

Dies funktioniert nur mit Development-Builds, nicht mit Expo Go.Wenn android/app/build.gradle manuell gepflegt wird und keinen standardmäßigen defaultConfig { }-Block enthält, den das Plugin finden kann, füge den Platzhalter stattdessen selbst hinzu. Siehe den Android-Tab oben.

Verwendung

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

Weiterleiten der Rückgabe-URL

Der Linking-Listener ist für die Verarbeitung der Rückgabe-URL unter iOS erforderlich. Unter Android ist handleOpenURL ein No-op, das false auflöst, da der Android-Kern die Weiterleitung nativ verarbeitet. Es ist sicher, den Listener auf beiden Plattformen bedingungslos zu registrieren.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Bedeutung des Ergebnisses

result.status ist ein UI-Hinweis und kein Zahlungsnachweis. Bestätige jede Zahlung über dein Backend mittels des payment.succeeded / subscription.active-Webhooks.

CheckoutStatus

erforderlich

Einer von succeeded, failed, cancelled, pending, expired.

string

Wird gesetzt, wenn die Rückgabe-URL einen solchen Wert enthielt. Zeige ihn in der UI an, verwende ihn aber nicht, um Zugriff zu gewähren. Siehe „Zahlung verifizieren“ weiter unten.

string

Wird für Subscription-Checkouts gesetzt.

string[]

Wird gesetzt, wenn der Checkout Produkte mit Lizenzschlüsseln enthält.

string

Wird gesetzt, wenn der Checkout eine E-Mail erfasst.

Record<string, string>

Jeder Abfrageparameter aus der Rückgabe-URL unverändert.

Zahlung verifizieren

Webhooks

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

Get Payment Detail

Rufe paymentId mit deinem Secret Key ab, um den Status direkt zu prüfen.

Gewähre Zugriff erst, nachdem einer dieser Mechanismen die Zahlung bestätigt hat, niemals allein aufgrund von result.status.

Anpassung des Erscheinungsbilds

Passe die Symbolleiste, Schaltflächen und das Farbschema des Checkout-Browsers über customization auf start(...) an. Die Optionen sind nach Plattform gruppiert, da Androids Custom Tab und iOS’ SFSafariViewController unterschiedliche native Steuerelemente bereitstellen. Alle Felder sind optional. Wenn customization weggelassen wird, verwendet jede Plattform das standardmäßige Erscheinungsbild.

Android — Custom Tab

Hintergrundfarbe der Symbolleiste.

Farbe der Navigationsleiste.

Farbe der Trennlinie über der Navigationsleiste.

'default' | 'back'

default zeigt das System-„X“-Symbol an; back zeichnet stattdessen einen Zurück-Pfeil.

'start' | 'end'

Auf welcher Seite der Symbolleiste die Schaltfläche zum Schließen angezeigt wird.

Zeigt das Teilen-Symbol der Symbolleiste an.

boolean

Zeigt den Seitentitel unter der URL in der Symbolleiste an.

boolean

Ermöglicht das automatische Ausblenden der Symbolleiste beim Scrollen der Seite.

boolean

Zeigt „Diese Seite als Lesezeichen speichern“ im Überlaufmenü an.

boolean

Zeigt „Seite herunterladen“ im Überlaufmenü an.

'system' | 'light' | 'dark'

Erzwingt unabhängig von der Systemeinstellung des Geräts ein helles oder dunkles Erscheinungsbild.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Beschriftung oder Symbol für die Schaltfläche zum Verwerfen.

'pageSheet' | 'fullScreen'

pageSheet wird als Karte mit Wischen zum Verwerfen angezeigt; fullScreen bedeckt den gesamten Bildschirm.

boolean

Ermöglicht das Einklappen der Symbolleiste beim Scrollen. Wird nur angezeigt, wenn presentationStyle fullScreen ist — pageSheet hält die Leisten unabhängig von dieser Einstellung fixiert.

'system' | 'light' | 'dark'

Erzwingt unabhängig von der Systemeinstellung des Geräts ein helles oder dunkles Erscheinungsbild.

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Fehler

start bricht nur bei fehlerhafter Verwendung oder einem Plattformfehler mit einem CheckoutError ab. Eine abgebrochene oder abgelehnte Zahlung ist immer ein Ergebnis und niemals eine Exception.

INVALID_CHECKOUT_URL: keine checkout.dodopayments.com-Session-URL.
INVALID_RETURN_URL: keine gültige absolute URL.
ALREADY_IN_PROGRESS: Ein Checkout läuft bereits.
PLATFORM_ERROR: unerwarteter Plattformfehler.

Verlassene Sessions

Wenn die App oder das JS-Bundle während des Checkouts beendet wird, geht das Promise verloren, aber die native Ebene behält die Session bei. Stelle sie beim nächsten Mount wieder her und gleiche sie mit deinem Backend ab.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Mobile Integration Guide

Derselbe Vertrag für Android, iOS und Flutter.

Expo Boilerplate

Ein vollständiges Expo-Beispiel mit Checkout-Integration.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Verwendung

Weiterleiten der Rückgabe-URL

Bedeutung des Ergebnisses

Zahlung verifizieren

Webhooks

Get Payment Detail

Anpassung des Erscheinungsbilds

Fehler

Verlassene Sessions

Verwandte Themen

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Installation

​Verwendung

​Weiterleiten der Rückgabe-URL

​Bedeutung des Ergebnisses

​Zahlung verifizieren

Webhooks

Get Payment Detail

​Anpassung des Erscheinungsbilds

​Fehler

​Verlassene Sessions

​Verwandte Themen

Mobile Integration Guide

Expo Boilerplate

Installation

Verwendung

Weiterleiten der Rückgabe-URL

Bedeutung des Ergebnisses

Zahlung verifizieren

Anpassung des Erscheinungsbilds

Fehler

Verlassene Sessions

Verwandte Themen