Troubleshooting (mobile integration)

This error indicates that MercadoPagoSDK.initialize(...) was not called before the first use of the checkout, or was called too late in the application lifecycle. The Mercado Pago SDK must be ready before any checkout call.

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

If the checkout is displayed but no network call completes successfully — or if paymentMethodId returns empty —, the problem is usually an invalid Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Integration data, going to the Credentials section located on the right side of the screen and clicking Test or *Production. Alternatively, you can go through Your integrations > Application data > Tests > Test credentials or Production credentials*. (publicKey) or a country code incompatible with the credential's country.

kotlin
MercadoPagoSDK.initialize(
    context = this,
    publicKey = "{{YOUR_PUBLIC_KEY}}", // Confirm in the Developer Panel
    countryCode = CountryCode.BRA // Use the code for the credential's country
)

This error indicates that the project does not meet the minimum requirements of the Mercado Pago SDK for Android. Check the three points below.

1. Jetpack Compose plugin disabled:

The SDK renders screens in Compose and the plugin must be active in the app module:

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

2. Kotlin below 2.0:

Earlier versions are not compatible with the Compose code generation used by the SDK. Update to Kotlin 2.0+ in libs.versions.toml (or build.gradle.kts).

3. The minimum SDK version (minSdk) below 23:

The SDK uses Android 6.0 APIs that are not available in earlier versions:

kotlin
android {
    defaultConfig {
        minSdk = 23
    }
}

This error indicates that the development environment does not meet the minimum requirements of the Mercado Pago SDK for iOS. Check the points below.

1. Xcode below 26.0:

The SDK requires toolchain APIs available from Xcode 26. Update it to the latest version.

2. Swift below 5.5:

async/await constructs and structured concurrency require Swift 5.5+.

3. Deployment target below iOS 13.0:

The SDK uses SwiftUI and Combine APIs that require iOS 13 as a minimum. Update the deployment target in Xcode.

4. Conflicting transitive dependencies:

If two packages in the workspace require different versions of an SDK dependency, SPM fails to resolve. To clear the cache and force a new resolution:

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

Reopen the project in Xcode after clearing the cache.

When Card Payment and Core Methods are declared with divergent versions of the same artifact, the build fails with Duplicate class errors (Android) or SPM cannot resolve the dependency graph (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")
    // Do not declare individual versions alongside the BOM
}

The checkout result callback is single-use, that is, after the first notification it is cleared automatically. Reusing the same checkout instance without creating a new one does not trigger the callback again.

kotlin
checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> { /* handle the payment */ }
        is MercadoPagoCheckoutResult.Error -> { /* show error or offer retry */ }
        is MercadoPagoCheckoutResult.UserCancelled -> { /* return to the previous screen */ }
    }
}