Troubleshooting (integración móvil)

Este error indica que MercadoPagoSDK.initialize(...) no fue llamado antes del primer uso del checkout, o fue llamado demasiado tarde en el ciclo de vida de la aplicación. El Mercado Pago SDK debe estar listo antes de cualquier llamada al checkout.

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

Si el checkout se muestra pero ninguna llamada de red se completa con éxito, o si paymentMethodId devuelve vacío, el problema suele ser una Public KeyClave pública que es utilizada en el frontend para acceder a información y cifrar datos. Puedes acceder a ella a través de Tus integraciones > Datos de integración, dirigiéndote a la sección Credenciales ubicada a la derecha de la pantalla y haciendo clic en Prueba o *Producción. Alternativamente, puedes ingresar a través de Tus integraciones > Datos de aplicación > Pruebas > Credenciales de prueba o Credenciales de producción*. (publicKey) inválida o un código de país incompatible con el país de la credencial.

kotlin
MercadoPagoSDK.initialize(
    context = this,
    publicKey = "{{YOUR_PUBLIC_KEY}}", // Confirma en el Panel del Desarrollador
    countryCode = CountryCode.BRA // Usa el código del país de la credencial
)

Este error indica que el proyecto no cumple los requisitos mínimos del Mercado Pago SDK para Android. Verifica los tres puntos a continuación.

1. Plugin Jetpack Compose deshabilitado:

La SDK renderiza pantallas en Compose y el plugin debe estar activo en el módulo de la app:

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

2. Kotlin por debajo de 2.0:

Las versiones anteriores no son compatibles con la generación de código Compose usada por la SDK. Actualiza a Kotlin 2.0+ en libs.versions.toml (o build.gradle.kts).

3. La versión mínima de la SDK (minSdk) por debajo de 23:

La SDK usa APIs de Android 6.0 que no están disponibles en versiones anteriores:

kotlin
android {
    defaultConfig {
        minSdk = 23
    }
}

Este error indica que el entorno de desarrollo no cumple los requisitos mínimos del Mercado Pago SDK para iOS. Verifica los puntos a continuación.

1. Xcode por debajo de 26.0:

La SDK requiere APIs de toolchain disponibles a partir de Xcode 26. Actualízalo a la versión más reciente.

2. Swift por debajo de 5.5:

Las construcciones async/await y la concurrencia estructurada requieren Swift 5.5+.

3. Deployment target por debajo de iOS 13.0:

La SDK usa APIs de SwiftUI y Combine que requieren iOS 13 como mínimo. Actualiza el deployment target en Xcode.

4. Dependencias transitivas en conflicto:

Si dos paquetes del workspace requieren versiones distintas de una dependencia de la SDK, el SPM falla en la resolución. Para limpiar la caché y forzar una nueva resolución:

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

Vuelve a abrir el proyecto en Xcode después de limpiar la caché.

Cuando Card Payment y Core Methods se declaran con versiones divergentes del mismo artefacto, el build falla con errores de Duplicate class (Android) o el SPM no puede resolver el grafo de dependencias (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")
    // No declares versiones individuales junto con el BOM
}

El callback de resultado del checkout es de uso único, es decir, tras la primera notificación se limpia automáticamente. Reutilizar la misma instancia del checkout sin crear una nueva no activa el callback de nuevo.

kotlin
checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> { /* maneja el pago */ }
        is MercadoPagoCheckoutResult.Error -> { /* muestra error u ofrece retry */ }
        is MercadoPagoCheckoutResult.UserCancelled -> { /* vuelve a la pantalla anterior */ }
    }
}