Android

Diese Seite behandelt das Android-Checkout-SDK, com.dodopayments.api:checkout-android, das den von Dodo Payments gehosteten Checkout innerhalb deiner App öffnet. Um die Dodo Payments API von deinem Server aufzurufen, verwende stattdessen das Backend-Kotlin-SDK.

Checkout Sessions API

Erstelle die checkout_url, die dieses SDK öffnet.

Mobile Integration Guide

Best Practices für mobile Checkout-Abläufe.

Das Android SDK öffnet den von Dodo Payments gehosteten Checkout in einem Custom Tab (androidx.browser.customtabs) und gibt ein typisiertes CheckoutResult zurück, wenn der Kunde den Checkout abschließt oder verlässt. Dein Backend erstellt die Checkout-Session und sendet ihre checkout_url an die App. Das SDK enthält keinen Netzwerkcode und speichert keinen API-Schlüssel. Daher ruft es die Dodo Payments API niemals auf. Voraussetzungen: minSdk 23, Kotlin und Java 17. Das SDK hängt nur von androidx.activity, androidx.browser und kotlinx-coroutines-android ab.

Installation

Add the Dependency

Füge das SDK aus Maven Central zur build.gradle.kts deines App-Moduls hinzu:

build.gradle.kts

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

Darstellung anpassen erfordert Version 1.1.0 oder höher.

Lege dein Callback-Schema als Gradle-Manifest-Platzhalter fest. Das eigene Manifest des SDK definiert den Intent-Filter der Weiterleitungsaktivität mit dem Platzhalter ${dodoCallbackScheme}. Daher ist diese Eigenschaft der einzige Einrichtungsschritt. Du musst kein Manifest-XML hinzufügen:

build.gradle.kts

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

Verwende dasselbe Schema in CheckoutParams.returnUrl, zum Beispiel myapp://checkout/return, und setze dieselbe URL als return_url der Checkout-Session, wenn dein Backend die Session erstellt. Das SDK gleicht die Rückgabe-URL anhand von Schema, Host und Pfad ab und ignoriert die Query-Zeichenfolge. Die URL muss keine echte Seite laden.

Wenn du den Platzhalter weglässt, schlägt der Build mit einem Fehler wegen eines nicht aufgelösten Platzhalters fehl. Wenn der Platzhalter nicht mit dem Schema von returnUrl übereinstimmt, löst das SDK PLATFORM_ERROR aus, bevor es den Checkout öffnet.

Verwendung

Das SDK bietet zwei Möglichkeiten, den Checkout zu starten: einen Activity-Result-Launcher und eine Suspend-Funktion. Beide geben dasselbe CheckoutResult zurück.

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

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> reconcileAbandonedSession() // outcome unknown, not a failure
            CheckoutStatus.PENDING -> reconcileAbandonedSession()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

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

Verwende diesen Ansatz, wenn möglich. Android übermittelt das Ergebnis über seinen ActivityResultRegistry, sodass das Ergebnis den Prozessabbruch überlebt.

Rufe DodoCheckout.start aus einem Coroutine-Scope auf:

import androidx.lifecycle.lifecycleScope
import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout
import kotlinx.coroutines.launch

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
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 -> reconcileAbandonedSession() // outcome unknown, not a failure
        CheckoutStatus.PENDING -> reconcileAbandonedSession()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

onEvent empfängt checkout.opened-, checkout.return_received- und checkout.closed-Ereignisse. Verwende sie nur für das Logging, niemals zur Bestimmung des Ergebnisses.

Dieser Ansatz wartet auf ein im Speicher gehaltenes CompletableDeferred. Daher überlebt das Ergebnis keinen Prozessabbruch. onEvent ist nur bei diesem Ansatz verfügbar, nicht mit dem Launcher.

Bedeutung des Ergebnisses

Das SDK erstellt CheckoutResult aus den Query-Parametern der Rückgabe-URL.

Das Feld status ist ein UI-Hinweis und kein Zahlungsnachweis. Bevor du Zugriff gewährst, bestätige die Zahlung in deinem Backend über einen Webhook oder den Endpunkt „Get Payment Detail“.

CheckoutStatus

erforderlich

Einer von fünf Werten:

SUCCEEDED: Die Rückgabe-URL enthält status=succeeded (einmalige Zahlung) oder status=active (Abonnement).
FAILED: Die Zahlung wurde abgelehnt (status=failed).
CANCELLED: Der Kunde hat den Custom Tab geschlossen, bevor die Rückgabe-URL eingetroffen ist. Das SDK kennt das Ergebnis nicht, und die Zahlung kann erfolgreich gewesen sein. Zeige daher keinen Fehlerbildschirm an. Gleiche stattdessen die abgebrochene Session ab.
PENDING: Die Zahlung wird später abgeschlossen (status=processing oder ein beliebiger requires_*-Wert), oder der Parameter status fehlte oder war unbekannt. Gleiche sie wie CANCELLED ab.
EXPIRED: Die Checkout-Session ist abgelaufen (status=expired).

String?

Der Query-Parameter payment_id, sofern die Rückgabe-URL einen solchen enthält. Zeige ihn in deiner Benutzeroberfläche an, verwende ihn aber nicht zur Gewährung von Zugriff. Siehe Zahlung verifizieren.

String?

Der Query-Parameter subscription_id. Wird für Abonnement-Checkouts gesetzt.

List<String>?

Der Query-Parameter license_key. Wird gesetzt, wenn der Checkout Produkte mit Lizenzschlüsseln enthält.

String?

Der Query-Parameter email. 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 den Zugriff erst, nachdem eine dieser Methoden die Zahlung bestätigt hat, zum Beispiel über den payment.succeeded- oder subscription.active-Webhook. Verlasse dich nicht allein auf CheckoutResult.status.

Darstellung anpassen

Um die Symbolleiste, Schaltflächen und das Farbschema des Custom Tabs zu ändern, übergib ein BrowserCustomization als customization an CheckoutParams. Jedes Feld ist optional und verwendet standardmäßig null. Bei einem Feld mit dem Wert null setzt das SDK diese Option nicht, sodass der Browser, der den Custom Tab hostet, seinen eigenen Standardwert verwendet.

Hintergrundfarbe der Symbolleiste als ARGB-Integer Color.

Farbe der Navigationsleiste als ARGB-Integer Color.

Farbe der Trennlinie über der Navigationsleiste als ARGB-Integer Color.

CloseButtonStyle?

DEFAULT zeigt das Systemsymbol „X“. BACK zeigt einen Zurück-Pfeil, den das SDK zeichnet.

CloseButtonPosition?

Die Seite der Symbolleiste, auf der die Schaltfläche zum Schließen angezeigt wird: START oder END.

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 „Diese Seite als Lesezeichen speichern“ im Überlaufmenü an.

Boolean?

Zeigt „Seite herunterladen“ im Überlaufmenü an.

ColorScheme?

LIGHT oder DARK erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. SYSTEM folgt der Systemeinstellung.

Dieses Beispiel verwendet checkoutLauncher aus Verwendung erneut:

import android.graphics.Color
import com.dodopayments.checkout.BrowserCustomization
import com.dodopayments.checkout.CheckoutParams

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 falscher Verwendung oder einem Plattformfehler aus. Lies den Grund aus CheckoutError.code ab:

INVALID_CHECKOUT_URL: checkoutUrl ist keine https-URL einer Checkout-Session (Pfad beginnend mit /session/) auf checkout.dodopayments.com oder test.checkout.dodopayments.com.
INVALID_RETURN_URL: returnUrl ist keine absolute URL mit einem Schema und einem 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, einschließlich eines returnUrl-Schemas, das nicht mit deinem dodoCallbackScheme-Platzhalter übereinstimmt.

Das Abbrechen durch einen Kunden oder eine abgelehnte Zahlung ist immer ein Ergebnis (CANCELLED oder FAILED), niemals ein ausgelöster Fehler. Beim Launcher werden Validierungsfehler aus launcher.launch(...) ausgelöst. Ein Plattformfehler nach dem Start kann nicht über den Activity-Result-Callback ausgelöst werden. Daher gibt der Launcher CANCELLED mit dem Fehlercode in raw["error"] zurück.

Abgebrochene Sessions

Das 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 während des Checkouts beendet wird, sowie nach einem Ergebnis CANCELLED oder PENDING, da das SDK in diesen Fällen das Ergebnis nicht kennt. Suche beim nächsten App-Start und nach jedem Ergebnis CANCELLED oder PENDING danach:

// context is any Context, such as your Activity.
DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // Ask your backend for the outcome of abandoned.sessionId, and show it.
    // Clear the record only after the outcome is final:
    DodoCheckout.clearAbandonedSession(context)
}

abandoned.sessionId ist die ID der Checkout-Session, die mit cks_ beginnt. abandoned.createdAt ist der Zeitpunkt, zu dem der Checkout gestartet wurde, als Epoch-Zeitstempel in Millisekunden. Dein Backend kann die Session mit Get Checkout Session abrufen. Dieser Aufruf gibt payment_id und payment_status zurück. Bis die Zahlung einen endgültigen Status erreicht, behandle sie als ausstehend und nicht als fehlgeschlagen.

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

Darstellung anpassen

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

​Darstellung anpassen

​Fehler

​Abgebrochene Sessions

​Verwandte Themen

Mobile Integration Guide

Kotlin SDK

Installation

Verwendung

Bedeutung des Ergebnisses

Zahlung verifizieren

Darstellung anpassen

Fehler

Abgebrochene Sessions

Verwandte Themen