# MD for: https://www.mercadopago.com.pe/developers/es/docs/checkout-api-orders/resources/troubleshooting.md

\# Troubleshooting (mobile integration) The following is a list of issues that may occur during mobile integration with Mercado Pago and how to resolve them. > SUCCESS\_MESSAGE > > If you are experiencing an issue, before consulting this documentation, make sure all our services are working correctly by checking our \[real-time status report\](https://status.mercadopago.com/). :::::AccordionComponent{title="The app closes when the checkout opens because the SDK was not initialized"} 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. ::::TabsComponent :::TabComponent{title="Android"} Initialize the SDK in \`Application.onCreate\`, before any screen component is created: \`\`\`kotlin class MyApp : Application() { override fun onCreate() { super.onCreate() MercadoPagoSDK.initialize( context = this, publicKey = "{{YOUR\_PUBLIC\_KEY}}", countryCode = CountryCode.BRA ) } } \`\`\` > WARNING > > Initializing in an \`Activity\` or \`Fragment\` does not guarantee the SDK is ready when the checkout is opened from another screen. Always use \`Application.onCreate\`. ::: :::TabComponent{title="iOS"} Initialize the SDK in \`AppDelegate.application(\_:didFinishLaunchingWithOptions:)\` or in the \`App\` \`init()\` (SwiftUI), before any checkout call: \`\`\`swift // AppDelegate func application(\_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: \[UIApplication.LaunchOptionsKey: Any\]?) -> Bool { let configuration = MercadoPagoSDK.Configuration( publicKey: "{{YOUR\_PUBLIC\_KEY}}", country: .BRA ) MercadoPagoSDK.shared.initialize(configuration) return true } // SwiftUI App @main struct MyApp: App { init() { let configuration = MercadoPagoSDK.Configuration( publicKey: "{{YOUR\_PUBLIC\_KEY}}", country: .BRA ) MercadoPagoSDK.shared.initialize(configuration) } var body: some Scene { WindowGroup { ContentView() } } } \`\`\` > WARNING > > Initializing in \`viewDidLoad\` of a \`UIViewController\` or in \`onAppear\` of a \`View\` is not sufficient — the SDK must be ready before the first use. ::: :::: ::::: :::::AccordionComponent{title="No checkout operation completes because the credential is incorrect"} If the checkout is displayed but no network call completes successfully — or if \`paymentMethodId\` returns empty —, the problem is usually an invalid :toolTipComponent\[Public Key\]{content="Public 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. ::::TabsComponent :::TabComponent{title="Android"} Verify that you are using the correct :toolTipComponent\[Public Key\]{content="Public 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\`) — a \*\*test\*\* credential for \[test environments\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/integration-test) and a \*\*production\*\* one to \[start receiving real payments\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/go-to-production) — and that the \`CountryCode\` passed at initialization matches 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 ) \`\`\` A \`publicKey\` from a different country than the \`countryCode\` causes the API to silently reject all requests without returning an explicit error. ::: :::TabComponent{title="iOS"} Verify that you are using the correct :toolTipComponent\[Public Key\]{content="Public 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\`) — a \*\*test\*\* credential for \[test environments\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/integration-test) and a \*\*production\*\* one to \[start receiving real payments\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/go-to-production) — and that the \`Country\` passed at initialization matches the credential's country: \`\`\`swift let configuration = MercadoPagoSDK.Configuration( publicKey: "{{YOUR\_PUBLIC\_KEY}}", // Confirm in the Developer Panel country: .BRA // Use the country of the credential's country ) MercadoPagoSDK.shared.initialize(configuration) \`\`\` Using the wrong \`Country\` or mixing test and production credentials are the most frequent causes of this symptom. ::: :::: ::::: :::::AccordionComponent{title="The Android build fails because the project does not meet the requirements"} 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 } } \`\`\` ::::: :::::AccordionComponent{title="The iOS build fails because the environment does not meet the requirements"} 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. ::::: :::::AccordionComponent{title="The build fails because the two integrations are on different versions"} 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). ::::TabsComponent :::TabComponent{title="Android"} Use the BOM (\`sdk-android-bom\`) so that the versions of all SDK artifacts are managed automatically: \`\`\`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 } \`\`\` To identify conflicts: \`./gradlew app:dependencies | grep mercadopago\`. Remove manually declared fixed versions for artifacts covered by the BOM. ::: :::TabComponent{title="iOS"} Both Card Payment and Core Methods are products of the same Swift package. Declare them from the same repository and avoid pinning divergent versions: \`\`\`swift // Package.swift .package(url: "https://github.com/mercadopago/sdk-ios", from: "x.y.z") // Targets .product(name: "MercadoPagoCheckout", package: "sdk-ios"), .product(name: "MercadoPagoCoreSDK", package: "sdk-ios"), \`\`\` If two targets in the project reference the same package with different versions, SPM does not know which version to use and fails to resolve. Use the same version constraint for both. ::: :::: ::::: :::::AccordionComponent{title="The checkout result does not arrive because the instance was reused"} 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. ::::TabsComponent :::TabComponent{title="Android"} Handle the three results within a single call to \`checkout.show\`: \`\`\`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 \*/ } } } \`\`\` To reopen the checkout after any result, create a new instance via \`Builder\`. Reusing the previous instance does not trigger the callback. ::: :::TabComponent{title="iOS"} Handle the three results within a single call to \`show\`, \`present\` or \`push\`: \`\`\`swift checkout.show { result in switch result { case .success(let paymentData): /\* handle the payment \*/ case .error(let error): /\* show error or offer retry \*/ case .userCancelled(let context): /\* return to the previous screen \*/ } } \`\`\` To reopen the checkout after any result, create a new instance via \`Builder\`. Reusing the previous instance does not trigger the callback. ::: :::: :::::