Troubleshooting (integração mobile)

Este erro indica que MercadoPagoSDK.initialize(...) não foi chamado antes da primeira utilização do checkout, ou foi chamado tarde demais no ciclo de vida do aplicativo. O Mercado Pago SDK precisa estar pronto antes de qualquer chamada ao checkout.

kotlin
class MeuApp : Application() {
    override fun onCreate() {
        super.onCreate()
        MercadoPagoSDK.initialize(
            context = this,
            publicKey = "{{YOUR_PUBLIC_KEY}}",
            countryCode = CountryCode.BRA
        )
    }
}

Se o checkout é exibido mas nenhuma chamada de rede é concluída com sucesso (ou se paymentMethodId retorna vazio), o problema costuma ser uma Public KeyChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Dados da integração, indo até a seção Credenciais, localizada à direita da tela, e clicando em Teste ou *Produção. Alternativamente, você também poderá acessá-la a partir de Suas integrações > Dados da aplicação > Testes > Credenciais de teste ou Credenciais de teste de produção*. (publicKey) inválida ou um código de país incompatível com o país da credencial.

kotlin
MercadoPagoSDK.initialize(
    context = this,
    publicKey = "{{YOUR_PUBLIC_KEY}}", // Confirme no Painel do Desenvolvedor
    countryCode = CountryCode.BRA // Use o código do país da credencial
)

Esse erro indica que o projeto não atende aos requisitos mínimos do Mercado Pago SDK para Android. Verifique os três pontos a seguir.

1. Plugin Jetpack Compose desabilitado:

O SDK renderiza telas em Compose e o plugin deve estar ativo no módulo do app:

kotlin
// build.gradle.kts (app)
android {
    buildFeatures {
        compose = true
    }
}

2. Kotlin abaixo de 2.0:

Versões anteriores não são compatíveis com a geração de código Compose usada pelo SDK. Atualize para Kotlin 2.0+ no libs.versions.toml (ou build.gradle.kts).

3. A versão mínima do SDK (minSdk) abaixo de 23:

O SDK usa APIs do Android 6.0 que não estão disponíveis em versões anteriores:

kotlin
android {
    defaultConfig {
        minSdk = 23
    }
}

Esse erro indica que o ambiente de desenvolvimento não atende aos requisitos mínimos do Mercado Pago SDK para iOS. Verifique os pontos a seguir.

1. Xcode abaixo de 26.0:

O SDK requer APIs de toolchain disponíveis a partir do Xcode 26. Atualize-o para a versão mais recente.

2. Swift abaixo de 5.5:

Construções async/await e concorrência estruturada exigem Swift 5.5+.

3. Deployment target abaixo de iOS 13.0:

O SDK usa APIs de SwiftUI e Combine que requerem iOS 13 no mínimo. Atualize o deployment target no Xcode.

4. Dependências transitivas em conflito:

Se dois pacotes do workspace exigirem versões diferentes de uma dependência do SDK, o SPM falha na resolução. Para limpar o cache e forçar uma nova resolução:

bash
rm -rf ~/Library/Caches/org.swift.swiftpm

Reabra o projeto no Xcode após limpar o cache.

Quando Card Payment e Core Methods são declarados com versões divergentes do mesmo artefato, o build falha com erros de Duplicate class (Android) ou o SPM não consegue resolver o grafo de dependências (iOS).

kotlin
// build.gradle.kts (app)
dependencies {
    implementation(platform("com.mercadopago.android.px:sdk-android-bom:x.y.z"))
    implementation("com.mercadopago.android.px:checkout")
    implementation("com.mercadopago.android.px:core-methods")
    // Não declare versões individuais junto com o BOM
}

O callback de resultado do checkout é de uso único, ou seja, após a primeira notificação ele é limpo automaticamente. Reutilizar a mesma instância do checkout sem criar uma nova não aciona o callback novamente.

kotlin
checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> { /* trate o pagamento */ }
        is MercadoPagoCheckoutResult.Error -> { /* exiba erro ou ofereça retry */ }
        is MercadoPagoCheckoutResult.UserCancelled -> { /* retorne à tela anterior */ }
    }
}