Android

Este é o SDK oficial de checkout para Android (com.dodopayments.api:checkout-android), para abrir o checkout hospedado do Dodo. Ele é diferente do SDK Kotlin de backend, que chama a API do Dodo Payments a partir do seu servidor.

Checkout Sessions API

Crie o checkout_url que este SDK abre

Mobile Integration Guide

Práticas recomendadas para fluxos de checkout móvel

O SDK para Android abre o checkout hospedado do Dodo em uma Chrome Custom Tab usando androidx.browser.customtabs. Ele não contém nenhum código de rede e não armazena nenhuma chave de API. Você passa um checkoutUrl da sessão de checkout do seu backend, e o SDK retorna um CheckoutResult tipado quando o usuário conclui ou abandona o fluxo. Requisitos: minSdk 23, Kotlin, Java 17.

Instalação

Add the Dependency

build.gradle.kts

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

Defina seu esquema de callback como um placeholder de manifesto do Gradle. O manifesto da própria biblioteca já declara o intent filter da atividade de redirecionamento usando o token ${dodoCallbackScheme}, portanto esta única propriedade é toda a configuração necessária — você não adiciona nenhum XML de manifesto:

build.gradle.kts

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

O valor deve corresponder ao esquema em CheckoutParams.returnUrl (por exemplo, myapp://checkout/return).

Se você omitir completamente o placeholder, o build falhará imediatamente com um erro de placeholder não resolvido, em vez de falhar silenciosamente no momento do checkout. Se você defini-lo, mas ele não corresponder ao esquema de returnUrl, DodoCheckout.start lançará PLATFORM_ERROR antes de apresentar qualquer conteúdo.

Uso

O SDK oferece suporte a dois estilos de invocação.

Launcher (Recommended)
Suspend Function

Registre o contrato com registerForActivityResult e inicie-o:

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

Prefira este estilo. O resultado é entregue por meio do ActivityResultRegistry gerenciado pelo sistema operacional do Android, portanto ele sobrevive à morte do processo.

Chame DodoCheckout.start a partir de um escopo de coroutine:

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()
    }
}

Este estilo resolve um CompletableDeferred em memória, portanto não sobrevive à morte do processo. onEvent está disponível somente aqui, não no contrato.

O que o resultado significa

O campo status é uma indicação para a UI, não uma prova de pagamento. Sempre verifique o pagamento no seu backend usando webhooks ou o endpoint Get Payment Detail antes de conceder acesso.

CheckoutStatus

obrigatório

Um entre SUCCEEDED, FAILED, CANCELLED, PENDING, EXPIRED.

String?

Definido quando a URL de retorno incluiu um. Exiba-o na UI; não o use para conceder acesso. Consulte Verificar o pagamento abaixo.

String?

Definido para checkouts de assinatura.

List<String>?

Definido quando o checkout inclui produtos com chaves de licença.

String?

Definido quando o checkout coleta um e-mail.

Map<String, String>

Todos os parâmetros de consulta da URL de retorno, literalmente.

Verificar o pagamento

Webhooks

Ouça os eventos de pagamento em tempo real

Get Payment Detail

Consulte o status do pagamento sob demanda

Conceda acesso ao usuário somente depois que uma dessas opções confirmar o pagamento. Não dependa apenas de CheckoutResult.status.

Personalização da aparência

Personalize a barra de ferramentas, os botões e o esquema de cores da Custom Tab por meio de customization em CheckoutParams. Todos os campos são opcionais; omitir customization usa a aparência padrão da Custom Tab do Android.

Cor de fundo da barra de ferramentas, como um int ARGB Color.

Cor da barra de navegação.

Cor do divisor acima da barra de navegação.

CloseButtonStyle

DEFAULT exibe o ícone de sistema “X”; BACK desenha uma seta de voltar.

CloseButtonPosition

Em qual lado da barra de ferramentas o botão de fechar aparece: START ou END.

Exibe o ícone de compartilhamento da barra de ferramentas.

Boolean

Exibe o título da página abaixo da URL na barra de ferramentas.

Boolean

Permite que a barra de ferramentas se oculte automaticamente conforme a página é rolada.

Boolean

Exibe “Adicionar esta página aos favoritos” no menu de opções.

Boolean

Exibe “Baixar página” no menu de opções.

ColorScheme

Força a aparência clara ou escura, independentemente da configuração do sistema do dispositivo: SYSTEM, LIGHT ou 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,
        )
    )
)

Erros

DodoCheckout.start lança CheckoutError apenas em caso de uso incorreto ou falha da plataforma. Leia o código de CheckoutError.code:

INVALID_CHECKOUT_URL: não é uma URL de sessão checkout.dodopayments.com.
INVALID_RETURN_URL: não é uma URL absoluta válida.
ALREADY_IN_PROGRESS: já há um checkout em andamento.
PLATFORM_ERROR: falha inesperada da plataforma, incluindo um returnUrl cujo esquema não corresponde ao seu placeholder dodoCallbackScheme.

O cancelamento pelo usuário ou um pagamento recusado sempre resulta em um resultado (CANCELLED ou FAILED), nunca em um erro lançado. Com o estilo launcher, os erros de validação são lançados para fora de launcher.launch(...).

Sessões abandonadas

Se o aplicativo for encerrado ou o usuário forçar sua parada durante o checkout, o SDK armazenará a sessão localmente. Na próxima inicialização do aplicativo, verifique se há uma sessão abandonada e reconcilie-a com seu backend:

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

abandoned.createdAt é um timestamp de época em milissegundos.

Relacionado

Mobile Integration Guide

Práticas recomendadas para fluxos de checkout em dispositivos móveis

Kotlin SDK

SDK de backend para operações do lado do servidor

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalação

Uso

O que o resultado significa

Verificar o pagamento

Webhooks

Get Payment Detail

Personalização da aparência

Erros

Sessões abandonadas

Relacionado

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Instalação

​Uso

​O que o resultado significa

​Verificar o pagamento

Webhooks

Get Payment Detail

​Personalização da aparência

​Erros

​Sessões abandonadas

​Relacionado

Mobile Integration Guide

Kotlin SDK

Instalação

Uso

O que o resultado significa

Verificar o pagamento

Personalização da aparência

Erros

Sessões abandonadas

Relacionado