Mobile Integrationsleitfaden

​

Voraussetzungen

• Dodo Payments-Konto: Aktives Händlerkonto mit API-Zugriff
• API-Zugangsdaten: API-Schlüssel und Webhook-Secret-Key aus Ihrem Dashboard
• Mobiles App-Projekt: Android-, iOS-, React-Native- oder Flutter-Anwendung
• Backend-Server: Zur sicheren Erstellung von Checkout-Sitzungen

​

Integrationsablauf

func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
    let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
    
    let requestData: [String: Any] = [
        "productId": productId,
        "customerEmail": customerEmail,
        "customerName": customerName
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
    return response.checkout_url
}

suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
    val client = OkHttpClient()
    val requestBody = JSONObject().apply {
        put("productId", productId)
        put("customerEmail", customerEmail)
        put("customerName", customerName)
    }.toString().toRequestBody("application/json".toMediaType())
    
    val request = Request.Builder()
        .url("https://your-backend.com/api/create-checkout-session")
        .header("Authorization", "Bearer $userSessionToken")
        .post(requestBody)
        .build()
    
    val response = client.newCall(request).execute()
    val responseBody = response.body?.string()
    val jsonResponse = JSONObject(responseBody ?: "")
    return jsonResponse.getString("checkout_url")
}

const getCheckoutURL = async (productId, customerEmail, customerName) => {
  try {
    const response = await fetch('https://your-backend.com/api/create-checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userSessionToken}`,
      },
      body: JSON.stringify({
        productId,
        customerEmail,
        customerName
      })
    });
    
    const data = await response.json();
    return data.checkout_url;
  } catch (error) {
    console.error('Failed to get checkout URL:', error);
    throw error;
  }
};

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String> getCheckoutUrl({
  required String productId,
  required String customerEmail,
  required String customerName,
}) async {
  final response = await http.post(
    Uri.parse('https://your-backend.com/api/create-checkout-session'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $userSessionToken',
    },
    body: jsonEncode({
      'productId': productId,
      'customerEmail': customerEmail,
      'customerName': customerName,
    }),
  );

  if (response.statusCode != 200) {
    throw Exception('Failed to get checkout URL: ${response.statusCode}');
  }
  return jsonDecode(response.body)['checkout_url'] as String;
}

​

SDK auswählen

​

Callback-URL-Schema registrieren

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

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

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

​

Darstellung anpassen

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

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

val result = DodoCheckout.start(
    activity,
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
        )
    )
) { event -> }

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

​

Checkout-Seite anpassen

​

Für Mobilgeräte optimierte Rezepte

Minimal Mobile Checkout - fastest path to payment

Verwenden Sie dies, wenn Sie das kürzestmögliche Formular wünschen: Zahlungsmethoden oben, für die Adresse nur eine Postleitzahl erforderlich, kein Rabattfeld und ein Theme passend zum Gerät.

• Node.js SDK
• Python SDK

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  return_url: 'myapp://checkout/success',
  cancel_url: 'myapp://checkout/cancelled',
  billing_currency: 'USD',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  feature_flags: {
    allow_discount_code: false,
    allow_currency_selection: false,
  },
});

console.log(session.checkout_url);

See all 26 lines

import os
import dodopayments

client = dodopayments.DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    return_url="myapp://checkout/success",
    cancel_url="myapp://checkout/cancelled",
    billing_currency="USD",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "system",
    },
    feature_flags={
        "allow_discount_code": False,
        "allow_currency_selection": False,
    },
)

print(session.checkout_url)

See all 27 lines

Alle verfügbaren Parameter und ihre Standardwerte finden Sie unter Checkout Sessions.

Branded Mobile Checkout - custom colors, fonts, and button label

Verwenden Sie dies, wenn sich die Checkout-Seite wie ein Teil Ihrer App anfühlen soll. Legen Sie Ihre Markenfarben, eine benutzerdefinierte Schriftart und eine lokalisierte Beschriftung der Bezahlschaltfläche fest.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'dark',
    theme_config: {
      dark: {
        button_primary: '#7C3AED',
        button_primary_hover: '#6D28D9',
        button_text_primary: '#FFFFFF',
        bg_primary: '#1A1A2E',
        bg_secondary: '#16213E',
        text_primary: '#E2E8F0',
      },
      pay_button_text: 'Complete Purchase',
      radius: '8px',
    },
  },
});

See all 24 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "dark",
        "theme_config": {
            "dark": {
                "button_primary": "#7C3AED",
                "button_primary_hover": "#6D28D9",
                "button_text_primary": "#FFFFFF",
                "bg_primary": "#1A1A2E",
                "bg_secondary": "#16213E",
                "text_primary": "#E2E8F0",
            },
            "pay_button_text": "Complete Purchase",
            "radius": "8px",
        },
    },
)

See all 24 lines

theme_config akzeptiert separate dark- und light-Objekte, damit sich die Palette an die aktuelle Darstellung des Geräts anpassen kann. Die vollständige Referenz der Farbschlüssel finden Sie unter Checkout Sessions.

One-Click Returning Customer - saved card, instant confirmation

Verwenden Sie dies für angemeldete Benutzer, die bereits bezahlt haben. Kombinieren Sie eine Kunden-ID, die gespeicherte Zahlungsmethode des Kunden und confirm: true, um das Checkout-Formular vollständig zu überspringen.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { customer_id: 'cus_returning_customer_id' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  payment_method_id: 'pm_saved_payment_method_id',
  confirm: true,
  show_saved_payment_methods: true,           // top-level parameter
  feature_flags: { redirect_immediately: true },
});

See all 11 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    payment_method_id="pm_saved_payment_method_id",
    confirm=True,
    show_saved_payment_methods=True,           # top-level parameter
    feature_flags={"redirect_immediately": True},
)

See all 11 lines

status in der Deep-Link-Rückgabe ist lediglich ein UI-Hinweis. Bestätigen Sie den Zugriff, indem Sie den payment.succeeded-Webhook in Ihrem Backend empfangen.

Subscription with Free Trial - trial before first charge

Verwenden Sie dies für Abonnementprodukte, die vor dem ersten Abrechnungszyklus eine kostenlose Testphase anbieten.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://subscription/activated',
  cancel_url: 'myapp://subscription/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  subscription_data: { trial_period_days: 14 },
});

See all 14 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://subscription/activated",
    cancel_url="myapp://subscription/cancelled",
    minimal_address=True,
    customization={"show_order_details": False, "theme": "system"},
    subscription_data={"trial_period_days": 14},
)

See all 11 lines

Gewähren Sie Zugriff auf das Feature, wenn Ihr Backend den subscription.active-Webhook empfängt – nicht wenn das mobile SDK zurückkehrt. Den vollständigen Webhook-Ablauf finden Sie im Leitfaden zur Abonnementintegration.

On-Demand Mandate - save a card for future variable charges

Verwenden Sie dies, um die Karte eines Kunden für spätere Abbuchungen zu tokenisieren (Wallet-Aufladungen, Pay-as-you-go, BNPL), ohne die Beschriftung „subscription“ anzuzeigen. Der Kunde autorisiert seine Zahlungsmethode einmal; später berechnen Sie variable Beträge nach Bedarf.

Dieses Muster wird von Apps verwendet, die nutzungsabhängig abrechnen – beispielsweise eine Astrologie-App, die pro Sitzung eine vorab autorisierte Karte belastet, statt nach einem festen Zeitplan.

• Node.js SDK
• Python SDK

// Step 1: Authorize the mandate (no charge yet)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://mandate/authorized',
  cancel_url: 'myapp://mandate/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    show_on_demand_tag: false, // hides the "on-demand" / "subscription" label
    theme: 'system',
  },
  subscription_data: {
    on_demand: { mandate_only: true },
  },
});

// Step 2: Later, charge any amount using the subscription ID
// (received via the subscription.active webhook after mandate authorization)
// await client.subscriptions.charge(subscriptionId, {
//   product_price: 2000,         // $20.00 in cents
//   product_currency: 'USD',
//   product_description: 'Session credits',
// });

See all 26 lines

# Step 1: Authorize the mandate (no charge yet)
session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://mandate/authorized",
    cancel_url="myapp://mandate/cancelled",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "show_on_demand_tag": False,  # hides the "on-demand" / "subscription" label
        "theme": "system",
    },
    subscription_data={"on_demand": {"mandate_only": True}},
)

# Step 2: Later, charge any amount using the subscription ID
# client.subscriptions.charge(subscription_id, {
#     "product_price": 2000,  # $20.00 in cents
#     "product_currency": "USD",
#     "product_description": "Session credits",
# })

See all 23 lines

On-Demand-Abbuchungen erfordern mindestens 1 USD (100 Cent). Beträge unter 1 USD werden mit "value out of range" abgelehnt. Für eine Autorisierung über null verwenden Sie wie oben gezeigt mandate_only: true und belasten Sie in nachfolgenden Aufrufen mindestens 1 USD.

Den vollständigen Abbuchungsablauf, Webhook-Ereignisse und Wiederholungsrichtlinien finden Sie unter On-Demand-Abonnements.

​

Abonnementabläufe auf Mobilgeräten

​

Reguläre wiederkehrende Abonnements

​

On-Demand-Abonnements

• Setzen Sie show_on_demand_tag: false, damit die Checkout-Seite keine Begriffe wie „subscription“ oder „on-demand“ anzeigt. Bei Anwendungsfällen zur Kartentokenisierung erwarten Kunden keine Abonnementterminologie.
• Nachdem das Mandat autorisiert wurde, empfängt Ihr Backend subscription.active. Speichern Sie subscription_id – Sie verwenden es für alle zukünftigen Abbuchungen.

​

Abonnement mit kostenloser Testphase

​

Upgrades und Downgrades

​

Checkout-Abbrüche reduzieren

​

Formular optimieren

​

Kundendaten vorausfüllen

• Neue Kunden – customer.email und customer.name aus Ihrer Authentifizierungssitzung setzen.
• Wiederkehrende Kunden – customer.customer_id setzen, um alle gespeicherten Daten automatisch vorauszufüllen.
• Währung – billing_currency und billing_address.country immer gemeinsam übergeben.

​

Tools zur Wiederherstellung

​

Best Practices

• Sicherheit: Liefern Sie niemals einen API-Schlüssel in Ihrer App aus. Erstellen Sie Checkout-Sitzungen in Ihrem Backend und übergeben Sie dem Client nur das resultierende checkout_url.
• Berechtigung: Behandeln Sie CheckoutResult.status als UI-Hinweis. Gewähren Sie Zugriff erst, nachdem Ihr Backend die Zahlung bestätigt hat.
• Benutzererfahrung: Zeigen Sie einen Ladestatus an, während Ihr Backend die Sitzung erstellt, und behandeln Sie cancelled als normales Ergebnis, nicht als Fehler.
• Tests: Verwenden Sie den Testmodus und Testkarten und überprüfen Sie den Roundtrip der Rückgabe-URL sowohl auf einem echten Gerät als auch in einem Simulator.
• Conversion: Setzen Sie show_order_details: false und minimal_address: true, um die besten Abschlussraten beim mobilen Checkout zu erzielen. Zahlungsmethoden oberhalb des sichtbaren Bereichs zu platzieren und Formularfelder zu reduzieren, sind die wirkungsvollsten Änderungen.
• Währung: Übergeben Sie billing_currency und billing_address.country immer explizit – fehlt einer der beiden, kann Adaptive Currency die Abrechnungswährung anhand der IP-Adresse des Kunden ändern.
• On-Demand-Abrechnung: Setzen Sie show_on_demand_tag: false, wenn Sie On-Demand-Abonnements zur Kartentokenisierung verwenden. Kunden in einem Wallet-Aufladungsablauf erwarten keine Begriffe wie „subscription“.
• Wiederherstellung: Aktivieren Sie die Wiederherstellung abgebrochener Warenkörbe in Ihrem Dodo Payments-Dashboard, um Kunden, die den Checkout nicht abschließen, automatisch erneut anzusprechen.

​

Fehlerbehebung

​

Häufige Probleme

• Callback trifft nie ein: Das Schema in returnUrl muss mit dem registrierten Schema übereinstimmen. Unter Android ist dies der dodoCallbackScheme-Manifest-Platzhalter, unter iOS und React Native der Info.plist-URL-Typ.
• Checkout kehrt unter iOS zum Browser statt zur App zurück: Sie haben die eingehende URL nicht weitergeleitet. Rufen Sie DodoCheckout.handleOpenURL(url) aus .onOpenURL, scene(_:openURLContexts:) oder einem React-Native-Listener Linking auf.
• PLATFORM_ERROR unter Android: Meist liegt ein nicht übereinstimmendes Schema vor. Der Fehler kann auch auftreten, wenn MainActivity android:taskAffinity="" setzt (den standardmäßigen flutter create), wodurch einige OEM-Builds den laufenden Checkout verlieren können.
• ALREADY_IN_PROGRESS: Ein Checkout ist noch geöffnet. Warten Sie den vorherigen Checkout ab oder schließen Sie ihn, bevor Sie einen neuen starten.
• Build schlägt mit einem nicht aufgelösten Platzhalter fehl: Sie haben das Android SDK hinzugefügt, aber manifestPlaceholders["dodoCallbackScheme"] nicht gesetzt.
• Zahlung erfolgreich, aber kein Zugriff gewährt: Das ist zu erwarten, wenn Sie sich auf das mobile Ergebnis stützen. Gewähren Sie Zugriff stattdessen über den payment.succeeded / subscription.active Webhook.
• Apple Pay / Google Pay werden mobil nicht angezeigt: Der Checkout wird in einer eingebetteten WebView (WKWebView / Android WebView) geladen, die Wallets unterdrückt und 3-D Secure beeinträchtigen kann. Öffnen Sie ihn stattdessen mit dem SDK oder im Systembrowser (Custom Tabs / SFSafariViewController).

​

Zusätzliche Ressourcen

• Leitfaden zur Zahlungsintegration
• Webhook-Dokumentation
• Testprozess
• Technische FAQs
• Anpassung von Checkout-Sitzungen
• On-Demand-Abonnements
• Upgrade/Downgrade von Abonnements
• Wiederherstellung abgebrochener Warenkörbe
• Customer Portal