Android

Cette page présente le SDK Android de checkout, com.dodopayments.api:checkout-android, qui ouvre le checkout hébergé de Dodo Payments dans votre application. Pour appeler l’API Dodo Payments depuis votre serveur, utilisez plutôt le SDK Kotlin backend.

Checkout Sessions API

Créez le checkout_url que ce SDK ouvre.

Mobile Integration Guide

Bonnes pratiques pour les parcours de checkout mobile.

Le SDK Android ouvre le checkout hébergé de Dodo Payments dans un Custom Tab (androidx.browser.customtabs) et renvoie un CheckoutResult typé lorsque le client termine ou quitte le checkout. Votre backend crée la session de checkout et envoie son checkout_url à l’application. Le SDK ne contient aucun code réseau et ne stocke aucune clé API ; il n’appelle donc jamais l’API Dodo Payments. Prérequis : minSdk 23, Kotlin et Java 17. Le SDK dépend uniquement de androidx.activity, androidx.browser et kotlinx-coroutines-android.

Installation

Add the Dependency

Ajoutez le SDK depuis Maven Central au build.gradle.kts de votre module d’application :

build.gradle.kts

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

La personnalisation de l’apparence nécessite la version 1.1.0 ou ultérieure.

Définissez votre schéma de callback comme placeholder de manifeste Gradle. Le manifeste du SDK déclare lui-même le filtre d’intention de l’activité de redirection avec le placeholder ${dodoCallbackScheme} ; cette propriété est donc la seule étape de configuration. Vous n’avez pas besoin d’ajouter de XML au manifeste :

build.gradle.kts

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

Utilisez le même schéma dans CheckoutParams.returnUrl, par exemple myapp://checkout/return, et définissez la même URL que celle indiquée dans le return_url de la session de checkout lorsque votre backend crée la session. Le SDK fait correspondre l’URL de retour selon le schéma, l’hôte et le chemin, et ignore la query string. L’URL n’a pas besoin de charger une page réelle.

Si vous omettez le placeholder, le build échoue avec une erreur de placeholder non résolu. Si le placeholder ne correspond pas au schéma de returnUrl, le SDK lève PLATFORM_ERROR avant d’ouvrir le checkout.

Utilisation

Le SDK propose deux façons de démarrer le checkout : un activity result launcher et une suspend function. Les deux renvoient le même CheckoutResult.

Launcher (Recommended)
Suspend Function

Enregistrez le contrat avec registerForActivityResult, puis lancez-le :

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"
    )
)

Utilisez ce style lorsque c’est possible. Android transmet le résultat via son ActivityResultRegistry ; le résultat est donc conservé après l’arrêt du processus.

Appelez DodoCheckout.start depuis un scope de coroutine :

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 reçoit les événements checkout.opened, checkout.return_received et checkout.closed. Utilisez-les uniquement pour la journalisation, jamais pour déterminer le résultat.

Ce style attend un CompletableDeferred en mémoire ; le résultat ne survit donc pas à l’arrêt du processus. onEvent est disponible uniquement avec ce style, et non avec le launcher.

Signification du résultat

Le SDK construit CheckoutResult à partir des paramètres de requête de l’URL de retour.

Le champ status est un indice d’interface utilisateur, et non une preuve de paiement. Avant d’accorder l’accès, confirmez le paiement sur votre backend avec un webhook ou le endpoint Get Payment Detail.

CheckoutStatus

requis

L’une des cinq valeurs suivantes :

SUCCEEDED : l’URL de retour contient status=succeeded (paiement unique) ou status=active (abonnement).
FAILED : le paiement a été refusé (status=failed).
CANCELLED : le client a fermé le Custom Tab avant l’arrivée de l’URL de retour. Le SDK ne connaît pas le résultat et le paiement peut avoir abouti ; n’affichez donc pas d’écran d’échec. Effectuez plutôt le rapprochement de la session abandonnée.
PENDING : le paiement est finalisé ultérieurement (status=processing ou toute valeur requires_*), ou le paramètre status était absent ou non reconnu. Effectuez le rapprochement comme pour CANCELLED.
EXPIRED : la session de checkout a expiré (status=expired).

String?

Le paramètre de requête payment_id, lorsque l’URL de retour en contient un. Affichez-le dans votre interface, mais ne l’utilisez pas pour accorder l’accès. Consultez Vérifier le paiement.

String?

Le paramètre de requête subscription_id. Défini pour les checkouts d’abonnement.

List<String>?

Le paramètre de requête license_key. Défini lorsque le checkout inclut des produits avec clé de licence.

String?

Le paramètre de requête email. Défini lorsque le checkout recueille une adresse e-mail.

Map<String, String>

Chaque paramètre de requête de l’URL de retour, verbatim.

Vérifier le paiement

Webhooks

Écoutez les événements de paiement en temps réel.

Get Payment Detail

Interrogez l’état du paiement à la demande.

N’accordez l’accès qu’après confirmation du paiement par l’un de ces mécanismes, par exemple avec le webhook payment.succeeded ou subscription.active. Ne vous fiez pas uniquement à CheckoutResult.status.

Personnalisation de l’apparence

Pour modifier la barre d’outils, les boutons et le jeu de couleurs du Custom Tab, transmettez un BrowserCustomization comme customization à CheckoutParams. Chaque champ est facultatif et prend par défaut la valeur null. Pour un champ null, le SDK ne définit pas cette option ; le navigateur qui héberge le Custom Tab applique donc sa propre valeur par défaut.

Couleur d’arrière-plan de la barre d’outils, sous forme d’entier ARGB Color.

Couleur de la barre de navigation, sous forme d’entier ARGB Color.

Couleur du séparateur au-dessus de la barre de navigation, sous forme d’entier ARGB Color.

CloseButtonStyle?

DEFAULT affiche l’icône système “X”. BACK affiche une flèche de retour dessinée par le SDK.

CloseButtonPosition?

Côté de la barre d’outils où le bouton de fermeture apparaît : START ou END.

Affiche l’icône de partage de la barre d’outils. false la masque.

Boolean?

Affiche le titre de la page sous l’URL dans la barre d’outils.

Boolean?

Masque automatiquement la barre d’outils lorsque la page défile.

Boolean?

Affiche “Ajouter cette page aux favoris” dans le menu supplémentaire.

Boolean?

Affiche “Télécharger la page” dans le menu supplémentaire.

ColorScheme?

LIGHT ou DARK force cette apparence, quel que soit le réglage système de l’appareil. SYSTEM suit le réglage système.

Cet exemple réutilise checkoutLauncher de Utilisation :

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,
        )
    )
)

Erreurs

DodoCheckout.start lève CheckoutError uniquement en cas de mauvaise utilisation ou d’échec de la plateforme. Lisez la raison dans CheckoutError.code :

INVALID_CHECKOUT_URL : checkoutUrl n’est pas une URL de session de checkout https (chemin commençant par /session/) sur checkout.dodopayments.com ou test.checkout.dodopayments.com.
INVALID_RETURN_URL : returnUrl n’est pas une URL absolue avec un schéma et un hôte.
ALREADY_IN_PROGRESS : un autre checkout est en cours. Un seul checkout peut être exécuté à la fois.
PLATFORM_ERROR : échec inattendu de la plateforme, notamment lorsque le schéma returnUrl ne correspond pas à votre placeholder dodoCallbackScheme.

L’annulation par un client ou le refus d’un paiement renvoie toujours un résultat (CANCELLED ou FAILED), et jamais une erreur levée. Avec le launcher, les erreurs de validation sont levées par launcher.launch(...). Un échec de la plateforme après le lancement ne peut pas être propagé par le callback de résultat de l’activité ; le launcher renvoie donc CANCELLED avec le code d’erreur dans raw["error"].

Sessions abandonnées

Le SDK enregistre la session de checkout au démarrage du checkout et n’efface cet enregistrement que lorsque le checkout se termine avec SUCCEEDED, FAILED ou EXPIRED. L’enregistrement est conservé si l’application est arrêtée pendant le checkout, ainsi qu’après un résultat CANCELLED ou PENDING, car dans ces cas le SDK ne connaît pas le résultat. Recherchez-le au prochain lancement de l’application et après chaque résultat CANCELLED ou PENDING :

// 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 est l’ID de la session de checkout, qui commence par cks_. abandoned.createdAt correspond à l’heure de début du checkout, sous forme d’horodatage epoch en millisecondes. Votre backend peut rechercher la session avec Get Checkout Session, qui renvoie son payment_id et son payment_status. Tant que le paiement n’a pas atteint un statut final, traitez-le comme en attente et non comme échoué.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Utilisation

Signification du résultat

Vérifier le paiement

Webhooks

Get Payment Detail

Personnalisation de l’apparence

Erreurs

Sessions abandonnées

Voir aussi

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Installation

​Utilisation

​Signification du résultat

​Vérifier le paiement

Webhooks

Get Payment Detail

​Personnalisation de l’apparence

​Erreurs

​Sessions abandonnées

​Voir aussi

Mobile Integration Guide

Kotlin SDK

Installation

Utilisation

Signification du résultat

Vérifier le paiement

Personnalisation de l’apparence

Erreurs

Sessions abandonnées

Voir aussi