Skip to main content
Primer Checkout Android SDK is currently in beta (v3.0.0-beta.2). The API is subject to change before the stable release.

​
Installation issues

​
Compose version conflict

Problem: Build fails with Compose compiler version mismatch. Solution: Ensure your Compose compiler version is compatible: 
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
}

​
Runtime issues

​
Checkout stays in Loading state

Problem: PrimerCheckoutState.Loading never transitions to Ready. Possible causes:
  • Invalid or expired client token
  • Network connectivity issues
  • Incorrect API key in client session creation
Solution: Check Logcat for error messages from the SDK. Ensure your client token is fresh and generated correctly.

​
Payment methods not showing

Problem: PrimerPaymentMethods shows empty list. Possible causes:
  • No payment methods configured in Primer Dashboard
  • Client session missing required fields
  • Payment methods not enabled for the currency/country
Solution: Verify your Primer Dashboard configuration and ensure your client session includes the correct currencyCode and countryCode.

​
Card form fields not appearing

Problem: Some card form fields (cardholder name, billing address) don’t appear. Explanation: Fields are configured by your Primer Dashboard settings. Only fields marked as required in the Dashboard will appear in the form. This is expected behavior.

​
3DS challenge not completing

Problem: Payment gets stuck during 3DS authentication. Solution: Ensure your app’s Activity has android:configChanges="orientation|screenSize" to prevent the WebView from being destroyed during configuration changes.

​
Compose-specific issues

​
Recomposition causes re-initialization

Problem: Checkout reinitializes on every recomposition. Solution: Use rememberPrimerCheckoutController() which survives recomposition. Don’t create the controller inside conditionals or callbacks: 
// Correct
val checkout = rememberPrimerCheckoutController(clientToken)

// Incorrect - creates new controller on recomposition
val checkout = PrimerCheckoutController(clientToken) // Don't do this

​
State not updating in UI

Problem: UI doesn’t reflect state changes. Solution: Use collectAsStateWithLifecycle(): 
val state by checkout.state.collectAsStateWithLifecycle()

​
Getting help

If you encounter an issue not covered here:
  1. Check the error’s diagnosticsId in logs
  2. Verify your configuration in the Primer Dashboard
  3. Contact Primer support with the diagnosticsId

​
Next steps

Best Practices

Production-ready tips

First Payment

Verify your integration