Android

Esta página cubre el SDK de checkout para Android, com.dodopayments.api:checkout-android, que abre el checkout alojado de Dodo Payments dentro de tu aplicación. Para llamar a la API de Dodo Payments desde tu servidor, usa el SDK de Kotlin para backend.

Checkout Sessions API

Crea el checkout_url que abre este SDK.

Mobile Integration Guide

Mejores prácticas para flujos de checkout móviles.

El SDK de Android abre el checkout alojado de Dodo Payments en un Custom Tab (androidx.browser.customtabs) y devuelve un CheckoutResult tipado cuando el cliente termina o abandona el checkout. Tu backend crea la sesión de checkout y envía su checkout_url a la aplicación. El SDK no contiene código de red ni almacena ninguna clave de API, por lo que nunca llama a la API de Dodo Payments. Requisitos: minSdk 23, Kotlin y Java 17. El SDK depende únicamente de androidx.activity, androidx.browser y kotlinx-coroutines-android.

Instalación

Add the Dependency

Añade el SDK desde Maven Central al build.gradle.kts del módulo de tu aplicación:

build.gradle.kts

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

La personalización de la apariencia requiere la versión 1.1.0 o posterior.

Configura tu esquema de callback como un placeholder de manifest de Gradle. El manifest propio del SDK declara el intent filter de la actividad de redirección con el placeholder ${dodoCallbackScheme}, por lo que esta propiedad es el único paso de configuración. No tienes que añadir ningún XML de manifest:

build.gradle.kts

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

Usa el mismo esquema en CheckoutParams.returnUrl, por ejemplo myapp://checkout/return, y establece la misma URL como return_url de la sesión de checkout cuando tu backend cree la sesión. El SDK compara la URL de retorno por esquema, host y ruta, e ignora la query string. La URL no necesita cargar una página real.

Si omites el placeholder, la compilación falla con un error de placeholder no resuelto. Si el placeholder no coincide con el esquema de returnUrl, el SDK lanza PLATFORM_ERROR antes de abrir el checkout.

Uso

El SDK ofrece dos formas de iniciar el checkout: un activity result launcher y una función suspend. Ambas devuelven el mismo CheckoutResult.

Launcher (Recommended)
Suspend Function

Registra el contrato con registerForActivityResult y, después, ejecútalo:

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 este estilo cuando sea posible. Android entrega el resultado mediante su ActivityResultRegistry, por lo que el resultado sobrevive a la finalización del proceso.

Llama a DodoCheckout.start desde 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 recibe eventos checkout.opened, checkout.return_received y checkout.closed. Úsalos únicamente para logging, nunca para decidir el resultado.

Este estilo espera un CompletableDeferred en memoria, por lo que el resultado no sobrevive a la finalización del proceso. onEvent solo está disponible con este estilo, no con el launcher.

Qué significa el resultado

El SDK construye CheckoutResult a partir de los parámetros de consulta de la URL de retorno.

El campo status es una indicación para la interfaz, no una prueba del pago. Antes de conceder acceso, confirma el pago en tu backend mediante un webhook o el endpoint Get Payment Detail.

CheckoutStatus

requerido

Uno de cinco valores:

SUCCEEDED: la URL de retorno tiene status=succeeded (pago único) o status=active (suscripción).
FAILED: el pago fue rechazado (status=failed).
CANCELLED: el cliente cerró el Custom Tab antes de que llegara la URL de retorno. El SDK desconoce el resultado y es posible que el pago se haya realizado correctamente, así que no muestres una pantalla de error. Reconcilia la sesión abandonada en su lugar.
PENDING: el pago se liquida más tarde (status=processing o cualquier valor requires_*), o el parámetro status faltaba o no se reconoció. Reconcílialo como CANCELLED.
EXPIRED: la sesión de checkout expiró (status=expired).

String?

El parámetro de consulta payment_id, cuando la URL de retorno incluye uno. Muéstralo en tu interfaz, pero no lo uses para conceder acceso. Consulta Verificar el pago.

String?

El parámetro de consulta subscription_id. Se establece para los checkouts de suscripción.

List<String>?

El parámetro de consulta license_key. Se establece cuando el checkout incluye productos con claves de licencia.

String?

El parámetro de consulta email. Se establece cuando el checkout captura una dirección de correo electrónico.

Map<String, String>

Cada parámetro de consulta de la URL de retorno, textualmente.

Verificar el pago

Webhooks

Escucha eventos de pago en tiempo real.

Get Payment Detail

Consulta el estado del pago cuando lo necesites.

Concede acceso solo después de que uno de estos confirme el pago, por ejemplo mediante el webhook payment.succeeded o subscription.active. No dependas únicamente de CheckoutResult.status.

Personalización de la apariencia

Para cambiar la barra de herramientas, los botones y el esquema de colores del Custom Tab, pasa un BrowserCustomization como customization en CheckoutParams. Todos los campos son opcionales y su valor predeterminado es null. Para un campo null, el SDK no establece esa opción, por lo que el navegador que aloja el Custom Tab aplica su propio valor predeterminado.

Color de fondo de la barra de herramientas, como un entero Color ARGB.

Color de la barra de navegación, como un entero Color ARGB.

Color del separador situado sobre la barra de navegación, como un entero Color ARGB.

CloseButtonStyle?

DEFAULT muestra el icono de sistema “X”. BACK muestra una flecha de retroceso que dibuja el SDK.

CloseButtonPosition?

El lado de la barra de herramientas donde aparece el botón de cierre: START o END.

Muestra el icono de compartir de la barra de herramientas. false lo oculta.

Boolean?

Muestra el título de la página debajo de la URL en la barra de herramientas.

Boolean?

Oculta automáticamente la barra de herramientas mientras se desplaza la página.

Boolean?

Muestra “Añadir esta página a marcadores” en el menú adicional.

Boolean?

Muestra “Descargar página” en el menú adicional.

ColorScheme?

LIGHT o DARK fuerza esa apariencia independientemente de la configuración del sistema del dispositivo. SYSTEM sigue la configuración del sistema.

Este ejemplo reutiliza checkoutLauncher de Uso:

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

Errores

DodoCheckout.start lanza CheckoutError únicamente por un uso incorrecto o un fallo de la plataforma. Lee el motivo de CheckoutError.code:

INVALID_CHECKOUT_URL: checkoutUrl no es una URL de sesión de checkout https (con una ruta que empieza por /session/) en checkout.dodopayments.com o test.checkout.dodopayments.com.
INVALID_RETURN_URL: returnUrl no es una URL absoluta con un esquema y un host.
ALREADY_IN_PROGRESS: hay otro checkout en curso. Solo puede ejecutarse un checkout a la vez.
PLATFORM_ERROR: un fallo inesperado de la plataforma, incluido un esquema returnUrl que no coincide con tu placeholder dodoCallbackScheme.

Un cliente que cancela o un pago rechazado siempre es un resultado (CANCELLED o FAILED), nunca un error lanzado. Con el launcher, los errores de validación se lanzan desde launcher.launch(...). Un fallo de la plataforma posterior al inicio no puede lanzarse mediante el callback del resultado de la actividad, por lo que el launcher devuelve CANCELLED con el código de error en raw["error"].

Sesiones abandonadas

El SDK registra la sesión de checkout cuando este comienza y elimina el registro únicamente cuando el checkout termina con SUCCEEDED, FAILED o EXPIRED. El registro permanece si la aplicación se cierra durante el checkout y después de un resultado CANCELLED o PENDING, porque en esos casos el SDK desconoce el resultado. Compruébalo en el siguiente inicio de la aplicación y después de cada resultado 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 es el ID de la sesión de checkout, que comienza por cks_. abandoned.createdAt es la hora de inicio del checkout, como una marca de tiempo de época en milisegundos. Tu backend puede buscar la sesión mediante Get Checkout Session, que devuelve sus valores payment_id y payment_status. Hasta que el pago alcance un estado final, trátalo como pendiente, no como fallido.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalación

Uso

Qué significa el resultado

Verificar el pago

Webhooks

Get Payment Detail

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Instalación

​Uso

​Qué significa el resultado

​Verificar el pago

Webhooks

Get Payment Detail

​Personalización de la apariencia

​Errores

​Sesiones abandonadas

​Relacionado

Mobile Integration Guide

Kotlin SDK

Instalación

Uso

Qué significa el resultado

Verificar el pago

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado