Android

Questa pagina illustra l’SDK Android per il checkout, com.dodopayments.api:checkout-android, che apre il checkout ospitato di Dodo Payments all’interno della tua app. Per chiamare l’API Dodo Payments dal tuo server, usa invece l’SDK Kotlin per il backend.

Checkout Sessions API

Crea checkout_url che questo SDK apre.

Mobile Integration Guide

Best practice per i flussi di checkout mobile.

L’SDK Android apre il checkout ospitato di Dodo Payments in una Custom Tab (androidx.browser.customtabs) e restituisce un CheckoutResult tipizzato quando il cliente completa o abbandona il checkout. Il tuo backend crea la sessione di checkout e ne invia checkout_url all’app. L’SDK non contiene codice di rete e non conserva alcuna API key, quindi non chiama mai l’API Dodo Payments. Requisiti: minSdk 23, Kotlin e Java 17. L’SDK dipende solo da androidx.activity, androidx.browser e kotlinx-coroutines-android.

Installazione

Add the Dependency

Aggiungi l’SDK da Maven Central al tuo build.gradle.kts del modulo app:

build.gradle.kts

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

La personalizzazione dell’aspetto richiede la versione 1.1.0 o successive.

Imposta lo schema di callback come manifest placeholder di Gradle. Il manifest dell’SDK dichiara il filtro intent dell’attività di reindirizzamento con il placeholder ${dodoCallbackScheme}, quindi questa proprietà è l’unico passaggio di configurazione. Non devi aggiungere XML al manifest:

build.gradle.kts

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

Usa lo stesso schema in CheckoutParams.returnUrl, ad esempio myapp://checkout/return, e imposta lo stesso URL come return_url della sessione di checkout quando il tuo backend crea la sessione. L’SDK confronta l’URL di ritorno in base a schema, host e percorso e ignora la query string. Non è necessario che l’URL carichi una pagina reale.

Se ometti il placeholder, la build fallisce con un errore di placeholder non risolto. Se il placeholder non corrisponde allo schema di returnUrl, l’SDK genera PLATFORM_ERROR prima di aprire il checkout.

Utilizzo

L’SDK offre due modi per avviare il checkout: un activity result launcher e una funzione suspend. Entrambi restituiscono lo stesso CheckoutResult.

Launcher (Recommended)
Suspend Function

Registra il contratto con registerForActivityResult, quindi avvialo:

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

Usa questo approccio quando possibile. Android distribuisce il risultato tramite il suo ActivityResultRegistry, quindi il risultato sopravvive alla terminazione del processo.

Chiama DodoCheckout.start da un coroutine scope:

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 riceve gli eventi checkout.opened, checkout.return_received e checkout.closed. Usali solo per il logging, mai per determinare l’esito.

Questo approccio attende un CompletableDeferred in memoria, quindi il risultato non sopravvive alla terminazione del processo. onEvent è disponibile solo con questo approccio, non con il launcher.

Cosa significa il risultato

L’SDK crea CheckoutResult dai parametri di query presenti nell’URL di ritorno.

Il campo status è un’indicazione per l’interfaccia, non una prova del pagamento. Prima di concedere l’accesso, conferma il pagamento sul tuo backend tramite un webhook o l’endpoint Get Payment Detail.

CheckoutStatus

obbligatorio

Uno di cinque valori:

SUCCEEDED: l’URL di ritorno contiene status=succeeded (pagamento una tantum) o status=active (abbonamento).
FAILED: il pagamento è stato rifiutato (status=failed).
CANCELLED: il cliente ha chiuso la Custom Tab prima dell’arrivo dell’URL di ritorno. L’SDK non conosce l’esito e il pagamento potrebbe essere andato a buon fine, quindi non mostrare una schermata di errore. Riconcilia invece la sessione abbandonata.
PENDING: il pagamento viene regolato in un secondo momento (status=processing o qualsiasi valore requires_*) oppure il parametro status era mancante o non riconosciuto. Riconcilialo come CANCELLED.
EXPIRED: la sessione di checkout è scaduta (status=expired).

String?

Il parametro di query payment_id, quando l’URL di ritorno ne include uno. Mostralo nell’interfaccia, ma non usarlo per concedere l’accesso. Consulta Verifica il pagamento.

String?

Il parametro di query subscription_id. Impostato per i checkout con abbonamento.

List<String>?

Il parametro di query license_key. Impostato quando il checkout include prodotti con chiavi di licenza.

String?

Il parametro di query email. Impostato quando il checkout acquisisce un indirizzo email.

Map<String, String>

Ogni parametro di query dell’URL di ritorno, alla lettera.

Verifica il pagamento

Webhooks

Ascolta gli eventi di pagamento in tempo reale.

Get Payment Detail

Interroga lo stato del pagamento su richiesta.

Concedi l’accesso solo dopo che uno di questi conferma il pagamento, ad esempio tramite il webhook payment.succeeded o subscription.active. Non fare affidamento solo su CheckoutResult.status.

Personalizzazione dell’aspetto

Per modificare la barra degli strumenti, i pulsanti e la combinazione di colori della Custom Tab, passa un BrowserCustomization come customization su CheckoutParams. Ogni campo è facoltativo e per impostazione predefinita è null. Per un campo null, l’SDK non imposta quell’opzione, quindi il browser che ospita la Custom Tab applica il proprio valore predefinito.

Colore di sfondo della barra degli strumenti, come intero ARGB Color.

Colore della barra di navigazione, come intero ARGB Color.

Colore del divisore sopra la barra di navigazione, come intero ARGB Color.

CloseButtonStyle?

DEFAULT mostra l’icona di sistema “X”. BACK mostra una freccia indietro disegnata dall’SDK.

CloseButtonPosition?

Il lato della barra degli strumenti in cui appare il pulsante di chiusura: START o END.

Mostra l’icona di condivisione della barra degli strumenti. false la nasconde.

Boolean?

Mostra il titolo della pagina sotto l’URL nella barra degli strumenti.

Boolean?

Nasconde automaticamente la barra degli strumenti quando la pagina scorre.

Boolean?

Mostra “Aggiungi questa pagina ai preferiti” nel menu overflow.

Boolean?

Mostra “Scarica pagina” nel menu overflow.

ColorScheme?

LIGHT o DARK forza quell’aspetto indipendentemente dall’impostazione di sistema del dispositivo. SYSTEM segue l’impostazione di sistema.

Questo esempio riutilizza checkoutLauncher da Utilizzo:

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

Errori

DodoCheckout.start genera CheckoutError solo in caso di uso scorretto o di un errore della piattaforma. Leggi il motivo da CheckoutError.code:

INVALID_CHECKOUT_URL: checkoutUrl non è un URL di sessione di checkout https (percorso che inizia con /session/) su checkout.dodopayments.com o test.checkout.dodopayments.com.
INVALID_RETURN_URL: returnUrl non è un URL assoluto con schema e host.
ALREADY_IN_PROGRESS: è in esecuzione un altro checkout. È possibile eseguire un solo checkout alla volta.
PLATFORM_ERROR: errore imprevisto della piattaforma, incluso uno schema returnUrl che non corrisponde al tuo placeholder dodoCallbackScheme.

Un cliente che annulla o un pagamento rifiutato producono sempre un risultato (CANCELLED o FAILED), mai un errore generato. Con il launcher, gli errori di convalida vengono generati da launcher.launch(...). Un errore della piattaforma dopo l’avvio non può essere generato tramite il callback del risultato dell’attività, quindi il launcher restituisce CANCELLED con il codice di errore in raw["error"].

Sessioni abbandonate

L’SDK registra la sessione di checkout quando il checkout inizia e cancella il record solo quando il checkout termina con SUCCEEDED, FAILED o EXPIRED. Il record rimane quando l’app viene terminata durante il checkout e dopo un risultato CANCELLED o PENDING, perché in questi casi l’SDK non conosce l’esito. Verifica la presenza del record al successivo avvio dell’app e dopo ogni risultato CANCELLED o 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 è l’ID della sessione di checkout, che inizia con cks_. abandoned.createdAt è l’ora di inizio del checkout, come timestamp epoch in millisecondi. Il tuo backend può cercare la sessione con Get Checkout Session, che restituisce payment_id e payment_status. Finché il pagamento non raggiunge uno stato finale, consideralo in sospeso, non fallito.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installazione

Utilizzo

Cosa significa il risultato

Verifica il pagamento

Webhooks

Get Payment Detail

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Installazione

​Utilizzo

​Cosa significa il risultato

​Verifica il pagamento

Webhooks

Get Payment Detail

​Personalizzazione dell’aspetto

​Errori

​Sessioni abbandonate

​Correlati

Mobile Integration Guide

Kotlin SDK

Installazione

Utilizzo

Cosa significa il risultato

Verifica il pagamento

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati