Android

Dies ist das offizielle Android-Checkout-SDK (com.dodopayments.api:checkout-android), um den gehosteten Checkout von Dodo zu öffnen. Es unterscheidet sich vom Backend-Kotlin-SDK, das die Dodo Payments API von deinem Server aus aufruft.

Checkout Sessions API

Erstelle den checkout_url, den dieses SDK öffnet

Mobile Integration Guide

Best Practices für mobile Checkout-Abläufe

Das Android SDK öffnet den gehosteten Checkout von Dodo in einem Chrome Custom Tab mit androidx.browser.customtabs. Es enthält keinen Netzwerkcode und speichert keinen API-Key. Du übergibst ein checkoutUrl aus der Checkout-Session deines Backends, und das SDK gibt ein typisiertes CheckoutResult zurück, wenn der Benutzer den Ablauf abschließt oder abbricht. Voraussetzungen: minSdk 23, Kotlin, Java 17.

Installation

Add the Dependency

build.gradle.kts

dependencies {
    implementation("com.dodopayments.api:checkout-android:1.0.0")
}

Lege dein Callback-Schema als Gradle-Manifest-Placeholder fest. Das Manifest der Bibliothek deklariert den Intent-Filter der Redirect-Aktivität bereits mit dem Token ${dodoCallbackScheme}. Daher ist diese eine Eigenschaft die gesamte Einrichtung – du fügst kein Manifest-XML hinzu:

build.gradle.kts

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

Der Wert muss mit dem Schema in CheckoutParams.returnUrl übereinstimmen (z. B. myapp://checkout/return).

Wenn du den Placeholder vollständig weglässt, schlägt der Build sofort mit einem Fehler wegen eines nicht aufgelösten Placeholders fehl, anstatt beim Checkout-Zeitpunkt still zu scheitern. Wenn du ihn festlegst, aber er nicht mit dem Schema von returnUrl übereinstimmt, löst DodoCheckout.start vor der Anzeige von irgendetwas PLATFORM_ERROR aus.

Verwendung

Das SDK unterstützt zwei Aufrufstile.

Launcher (Recommended)
Suspend Function

Registriere den Vertrag mit registerForActivityResult und starte ihn anschließend:

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> dismiss()
            CheckoutStatus.PENDING -> showPending()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl, // from your backend's checkout session
        returnUrl = "myapp://checkout/return"
    )
)

Bevorzuge diesen Stil. Das Ergebnis wird über Androids vom Betriebssystem verwaltetes ActivityResultRegistry zugestellt und bleibt daher auch nach dem Tod des Prozesses erhalten.

Rufe DodoCheckout.start aus einem Coroutine-Scope auf:

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

lifecycleScope.launch {
    val result = DodoCheckout.start(
        activity = this@MyActivity,
        params = CheckoutParams(
            checkoutUrl = checkoutUrl, // from your backend's checkout session
            returnUrl = "myapp://checkout/return"
        ),
        onEvent = { event -> println(event.name) } // logging only
    )

    when (result.status) {
        CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
        CheckoutStatus.FAILED -> showFailure()
        CheckoutStatus.CANCELLED -> dismiss()
        CheckoutStatus.PENDING -> showPending()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

Dieser Stil löst ein im Speicher gehaltenes CompletableDeferred auf und bleibt daher nicht nach dem Tod des Prozesses erhalten. onEvent ist nur hier verfügbar, nicht auf dem Vertrag.

Bedeutung des Ergebnisses

Das Feld status ist ein UI-Hinweis und kein Zahlungsnachweis. Verifiziere die Zahlung immer in deinem Backend mithilfe von Webhooks oder des Endpunkts „Get Payment Detail“, bevor du Zugriff gewährst.

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 unten „Zahlung verifizieren“.

String?

Wird für Subscription-Checkouts gesetzt.

List<String>?

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

String?

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

Map<String, String>

Jeder Query-Parameter aus der Rückgabe-URL, unverändert.

Zahlung verifizieren

Webhooks

Höre in Echtzeit auf Zahlungsereignisse

Get Payment Detail

Frage den Zahlungsstatus bei Bedarf ab

Gewähre dem Benutzer erst Zugriff, wenn einer dieser Mechanismen die Zahlung bestätigt. Verlasse dich nicht allein auf CheckoutResult.status.

Anpassung des Erscheinungsbilds

Passe die Symbolleiste, Schaltflächen und das Farbschema des Custom Tab über customization auf CheckoutParams an. Alle Felder sind optional; wenn customization weggelassen wird, wird das standardmäßige Erscheinungsbild des Android Custom Tab verwendet.

Hintergrundfarbe der Symbolleiste als ARGB-Integer Color.

Farbe der Navigationsleiste.

Farbe der Trennlinie oberhalb der Navigationsleiste.

CloseButtonStyle

DEFAULT zeigt das Systemsymbol „X“ an; BACK zeichnet stattdessen einen Zurück-Pfeil.

CloseButtonPosition

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

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.

ColorScheme

Erzwingt unabhängig von der Systemeinstellung des Geräts ein helles oder dunkles Erscheinungsbild: SYSTEM, LIGHT oder DARK.

import com.dodopayments.checkout.BrowserCustomization

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            colorScheme = BrowserCustomization.ColorScheme.DARK,
        )
    )
)

Fehler

DodoCheckout.start löst CheckoutError nur bei Fehlbedienung oder einem Plattformfehler aus. Lies den Code aus CheckoutError.code:

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, einschließlich eines returnUrl, dessen Schema nicht mit deinem dodoCallbackScheme-Platzhalter übereinstimmt.

Das Abbrechen durch den Benutzer oder eine abgelehnte Zahlung führt immer zu einem Ergebnis (CANCELLED oder FAILED), niemals zu einem ausgelösten Fehler. Beim Launcher-Stil werden Validierungsfehler aus launcher.launch(...) ausgelöst.

Abgebrochene Sessions

Wenn die App während des Checkouts beendet oder vom Benutzer zwangsweise gestoppt wird, speichert das SDK die Session lokal. Überprüfe beim nächsten Start der App, ob eine abgebrochene Session vorhanden ist, und gleiche sie mit deinem Backend ab:

DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession(context)
}

abandoned.createdAt ist ein Zeitstempel in Millisekunden seit der Unix-Epoche.

Mobile Integration Guide

Best Practices für mobile Checkout-Abläufe

Kotlin SDK

Backend-SDK für serverseitige Vorgänge

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Verwendung

Bedeutung des Ergebnisses

Zahlung verifizieren

Webhooks

Get Payment Detail

Anpassung des Erscheinungsbilds

Fehler

Abgebrochene Sessions

Verwandte Themen

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Installation

​Verwendung

​Bedeutung des Ergebnisses

​Zahlung verifizieren

Webhooks

Get Payment Detail

​Anpassung des Erscheinungsbilds

​Fehler

​Abgebrochene Sessions

​Verwandte Themen

Mobile Integration Guide

Kotlin SDK

Installation

Verwendung

Bedeutung des Ergebnisses

Zahlung verifizieren

Anpassung des Erscheinungsbilds

Fehler

Abgebrochene Sessions

Verwandte Themen