Mobile Integrationsleitfaden

​

Voraussetzungen

• Dodo Payments-Konto: Aktives Händlerkonto mit API-Zugriff
• API-Zugangsdaten: API-Schlüssel und Webhook-Secret-Key aus deinem Dashboard
• Projekt der mobilen App: Android-, iOS-, React-Native- oder Flutter-Anwendung
• Backend-Server: Zur sicheren Verarbeitung der 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;
}

​

Wähle dein SDK

​

Ein 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>

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        { "android": { "manifestPlaceholders": { "dodoCallbackScheme": "myapp" } } }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [{ "CFBundleURLSchemes": ["myapp"] }]
      }
    }
  }
}

​

Best Practices

• Sicherheit: Liefere niemals einen API-Schlüssel in deiner App aus. Erstelle Checkout-Sitzungen in deinem Backend und übergib dem Client nur die resultierende checkout_url.
• Maßgeblichkeit: Behandle CheckoutResult.status als UI-Hinweis. Gewähre Zugriff erst, nachdem dein Backend die Zahlung bestätigt hat.
• Benutzererfahrung: Zeige einen Ladezustand an, während dein Backend die Sitzung erstellt, und behandle cancelled als normales Ergebnis und nicht als Fehler.
• Tests: Verwende den Testmodus und Testkarten und überprüfe den Roundtrip der Rückgabe-URL sowohl auf einem echten Gerät als auch in einem Simulator.

​

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 zu deiner App zurück: Du hast die eingehende URL nicht weitergeleitet. Rufe DodoCheckout.handleOpenURL(url) aus .onOpenURL, scene(_:openURLContexts:) oder einem React-Native- Linking-Listener auf.
• PLATFORM_ERROR unter Android: Meist liegt ein Schema-Konflikt vor. Dies kann auch auftreten, wenn dein MainActivity android:taskAffinity="" setzt (der standardmäßige flutter create-Wert), wodurch einige OEM-Builds den laufenden Checkout verlieren können.
• ALREADY_IN_PROGRESS: Ein Checkout ist noch geöffnet. Warte, bis der vorherige abgeschlossen ist, oder schließe ihn, bevor du einen weiteren startest.
• Build schlägt wegen eines nicht aufgelösten Platzhalters fehl: Du hast das Android-SDK hinzugefügt, aber manifestPlaceholders["dodoCallbackScheme"] nie gesetzt.
• Zahlung erfolgreich, aber kein Zugriff gewährt: Dies ist zu erwarten, wenn du dich am mobilen Ergebnis orientierst. Gewähre den Zugriff stattdessen über den payment.succeeded-/subscription.active-Webhook.

​

Zusätzliche Ressourcen

• Leitfaden zur Zahlungsintegration
• Webhook-Dokumentation
• Testprozess
• Technische FAQs