Skip to content

Troubleshooting

Learn how to diagnose and fix common issues with Checkout Drop-in.

Quick diagnostics

If you're experiencing issues with Drop-in, start with these quick diagnostic checks:

import android.content.Context
import android.net.ConnectivityManager
import android.net.NetworkCapabilities
import android.os.Build
import android.util.Log
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.models.SessionConfig

// Drop-in diagnostic helper
fun diagnoseDropIn(
    context: Context,
    session: SessionConfig?,
    config: CheckoutDropInConfig
) {
    Log.d("DropInDiagnostics", "=== Checkout Drop-in diagnostics ===")
    
    // Check SDK import
    Log.d("DropInDiagnostics", "SDK imported: ${CheckoutDropIn::class.java.name}")
    
    // Check SessionConfig required fields
    Log.d("DropInDiagnostics", "Session ID: ${if (!session?.sessionId.isNullOrEmpty()) "Present" else "Missing"}")
    Log.d("DropInDiagnostics", "HMAC key: ${if (!session?.hmacKey.isNullOrEmpty()) "Present" else "Missing"}")
    Log.d("DropInDiagnostics", "Data: ${if (!session?.data.isNullOrEmpty()) "Present" else "Missing"}")
    Log.d("DropInDiagnostics", "Encryption key: ${if (!session?.encryptionKey.isNullOrEmpty()) "Present" else "Missing"}")
    Log.d("DropInDiagnostics", "Locale: ${if (!session?.locale.isNullOrEmpty()) "Present" else "Missing"}")
    // Optional on the type, but required for payment-method resolution
    Log.d("DropInDiagnostics", "Allowed funding types: ${session?.allowedFundingTypes}")
    
    // Card display overrides can hide the Card panel even when session.cards is present
    val cardConfig = config.methodConfig?.card
    Log.d("DropInDiagnostics", "showCOF: ${cardConfig?.showCOF}")
    Log.d("DropInDiagnostics", "showNewCard: ${cardConfig?.showNewCard}")
    
    // Check environment
    Log.d("DropInDiagnostics", "Environment: ${config.environment}")
    Log.d("DropInDiagnostics", "Owner ID: ${config.ownerId}")
    Log.d("DropInDiagnostics", "Owner type: ${config.ownerType}")
    
    // Check device info
    Log.d("DropInDiagnostics", "Android version: ${Build.VERSION.SDK_INT}")
    Log.d("DropInDiagnostics", "Device: ${Build.MANUFACTURER} ${Build.MODEL}")
    Log.d("DropInDiagnostics", "Screen density: ${context.resources.displayMetrics.density}")
    
    // Check network connectivity
    val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    val network = connectivityManager.activeNetwork
    val capabilities = connectivityManager.getNetworkCapabilities(network)
    Log.d("DropInDiagnostics", "Network available: ${capabilities != null}")
    
    Log.d("DropInDiagnostics", "===================================")
}

Common issues

Drop-in not rendering

Look for these symptoms:

  • The Drop-in component doesn't appear in your Compose UI.
  • No payment methods are visible.
  • There are no errors in Logcat.

Common causes and solutions:

CauseSolution
Compose recomposition issue.Ensure session data is loaded before rendering CheckoutDropIn. Use LaunchedEffect to fetch session data and conditional rendering with checkoutDropIn.Content().
Session data invalid.Verify SessionConfig includes required fields: sessionId, hmacKey, data, encryptionKey, and locale. Also check allowedFundingTypes (optional on the type, but needed for method resolution). Check backend session creation logs.
No payment methods enabled.Check allowedFundingTypes in your session. At least one payment method must be enabled in the Unity Portal. For cards, Drop-in requires the cards key (an empty list is valid). cardSchemes alone does not enable the card panel.
Card panel hidden by display config.If wallets aren't available and DropInCardConfig sets both showCOF and showNewCard to false, Drop-in creates no payment methods (and may surface SDK1119). Enable at least one card section, or enable another payment method in the session.
Incorrect configuration.Verify environment, ownerId, and ownerType are set correctly.
ProGuard or R8 stripping SDK classes.Rely on the SDK's bundled consumer ProGuard rules (see ProGuard section below). Add app-specific keeps only for your own models.

Use these diagnostic steps. Session fetch is app-specific — implement fetchSessionFromBackend() with your HTTP client (see Quickstart for a full sample). The SDK doesn't provide apiClient or SessionResponse.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import android.util.Log
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import java.time.Instant

/**
 * App-specific: call your backend sessions endpoint and map the response to [SessionConfig].
 * Do not call the PXP Sessions API from the Android app with merchant secrets.
 */
suspend fun fetchSessionFromBackend(): SessionConfig {
    // e.g. retrofit/okhttp/ktor → your server → JSON mapping to SessionConfig
    error("Implement session fetch from your backend")
}

@Composable
fun DiagnoseRenderingIssue() {
    val context = LocalContext.current
    var session by remember { mutableStateOf<SessionConfig?>(null) }
    var diagnostics by remember { mutableStateOf("") }

    LaunchedEffect(Unit) {
        diagnostics += "Step 1: Fetching session...\n"

        try {
            val sessionConfig = fetchSessionFromBackend()
            session = sessionConfig
            diagnostics += "Step 2: Session fetched successfully\n"
            diagnostics += "Session ID: ${sessionConfig.sessionId}\n"

            // Step 3: Check SessionConfig required fields
            diagnostics += "Step 3: Validating session data...\n"

            if (sessionConfig.sessionId.isEmpty()) {
                diagnostics += "ERROR: Session ID missing\n"
            } else {
                diagnostics += "Session ID present\n"
            }
            if (sessionConfig.hmacKey.isEmpty()) diagnostics += "ERROR: HMAC key missing\n"
            if (sessionConfig.data.isEmpty()) diagnostics += "ERROR: data missing\n"
            if (sessionConfig.encryptionKey.isEmpty()) diagnostics += "ERROR: encryptionKey missing\n"
            if (sessionConfig.locale.isEmpty()) diagnostics += "ERROR: locale missing\n"

            if (sessionConfig.allowedFundingTypes == null) {
                diagnostics += "ERROR: No allowed funding types\n"
            } else {
                val funding = sessionConfig.allowedFundingTypes
                var paymentMethodCount = 0
                // Drop-in enables cards only when the cards key is present (empty list is valid).
                // cardSchemes alone does not enable the card panel.
                if (funding.cards != null) paymentMethodCount++
                if (funding.wallets?.paypal != null) paymentMethodCount++
                if (funding.wallets?.googlePay != null) paymentMethodCount++
                if (funding.payByBanks?.aeropay != null) paymentMethodCount++

                if (paymentMethodCount == 0) {
                    diagnostics += "ERROR: No payment methods enabled in session\n"
                } else {
                    diagnostics += "$paymentMethodCount session payment method(s) available\n"
                    diagnostics += "Note: showCOF or showNewCard=false can still hide Card UI\n"
                }
            }
        } catch (e: Exception) {
            diagnostics += "ERROR: ${e.message}\n"
            Log.e("DropIn", "Session fetch error", e)
        }
    }

    val checkoutDropIn = remember(session) {
        session?.let { sessionConfig ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.TEST,
                    session = sessionConfig,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 1.00,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Authorisation
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = "test-${System.currentTimeMillis()}",
                        merchantTransactionDate = { Instant.now().toString() }
                    ),
                    onSuccess = { result ->
                        Log.d("DropIn", "Success: ${result.systemTransactionId}")
                    },
                    onError = { paymentMethod: PaymentMethod?, error: BaseSdkException ->
                        Log.e(
                            "DropIn",
                            "Error [${paymentMethod?.value}]: ${error.errorCode}: ${error.message}",
                            error
                        )
                    }
                )
            )
        }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    Column {
        Text(diagnostics)
        checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
    }
}

Session expired errors

Look for these symptoms:

  • A "Session expired" error message is displayed.
  • The drop-in loads but payment fails immediately.
  • Logcat shows session timeout errors.

Common causes and solutions:

CauseSolution
Session timeout exceeded.Sessions expire based on the sessionTimeout value (default = 120 minutes). Create a new session if expired.
Clock skewEnsure that the server and device clocks are synchronised.
Session reusedSessions are single-use. Create a new session for each checkout attempt.
Invalid HMAC signatureVerify that the HMAC key matches between session creation and SDK initialisation.

Solution: Implement session refresh. Call destroy() on the previous CheckoutDropIn instance before creating a new one.

import android.util.Log
import android.widget.Toast
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import kotlinx.coroutines.launch
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.DropInSubmitResult
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import java.time.Instant
import java.util.UUID

/**
 * App-specific: call your backend sessions endpoint and map the response to [SessionConfig].
 */
suspend fun fetchSessionFromBackend(): SessionConfig {
    // e.g. retrofit/okhttp/ktor → your server → JSON mapping to SessionConfig
    error("Implement session fetch from your backend")
}

/**
 * App-specific: verify [result] on your backend (and/or wait for webhook) before fulfilling.
 */
suspend fun verifyPaymentOnBackend(result: DropInSubmitResult) {
    // POST systemTransactionId / merchantTransactionId to your server for authoritative checks
}

@Composable
fun CheckoutScreenWithSessionRefresh() {
    val context = LocalContext.current
    val coroutineScope = rememberCoroutineScope()
    var session by remember { mutableStateOf<SessionConfig?>(null) }
    var refreshKey by remember { mutableStateOf(0) }

    // Fetch session
    LaunchedEffect(refreshKey) {
        try {
            session = fetchSessionFromBackend()
        } catch (e: Exception) {
            Log.e("Checkout", "Failed to fetch session", e)
            Toast.makeText(
                context,
                "Failed to load checkout. Please try again.",
                Toast.LENGTH_LONG
            ).show()
        }
    }

    val checkoutDropIn = remember(session) {
        session?.let { sessionConfig ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.LIVE,
                    session = sessionConfig,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 99.99,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Authorisation
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = UUID.randomUUID().toString(),
                        merchantTransactionDate = { Instant.now().toString() }
                    ),
                    onSuccess = { result ->
                        coroutineScope.launch {
                            verifyPaymentOnBackend(result)
                        }
                    },
                    onError = { paymentMethod: PaymentMethod?, error: BaseSdkException ->
                        // Prefer errorCode when available; message matching is a fallback.
                        // Match network-layer copy ("Session has expired.") — avoid bare "session"
                        // (it also matches unrelated config messages that mention SessionData).
                        val looksLikeSessionExpiry =
                            error.message?.contains("Session has expired", ignoreCase = true) == true

                        if (looksLikeSessionExpiry) {
                            Log.w(
                                "Checkout",
                                "Session expired [${paymentMethod?.value}]: ${error.errorCode}",
                                error
                            )

                            Toast.makeText(
                                context,
                                "Session expired. Refreshing checkout...",
                                Toast.LENGTH_SHORT
                            ).show()

                            // Trigger session refresh (DisposableEffect destroys the old instance)
                            refreshKey++
                        } else {
                            Log.e(
                                "Checkout",
                                "Payment error [${paymentMethod?.value}]: ${error.errorCode}",
                                error
                            )
                            Toast.makeText(
                                context,
                                "Payment failed: ${error.message}",
                                Toast.LENGTH_LONG
                            ).show()
                        }
                    }
                )
            )
        }
    }

    DisposableEffect(checkoutDropIn) {
        onDispose { checkoutDropIn?.destroy() }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    // Render Drop-in (shows loading while create() runs)
    checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
}

Payment method not appearing

Look for these symptoms:

  • An expected payment method isn't shown.
  • Only the card payment method is visible.
  • Google Pay doesn't appear even though it's enabled.

Common causes and solutions:

Payment methodCommon causesSolutions
CardsSession missing the cards key (having only cardSchemes is not enough), or both showCOF and showNewCard are false.Enable the Card service in the Unity Portal and verify the session includes allowedFundingTypes.cards (an empty list is valid). cardSchemes is used for network resolution but does not substitute for cards. Check methodConfig.card: at least one of showCOF or showNewCard must resolve to true. For card-on-file only, also return a non-empty shopper id from onGetShopper. Saved cards appear only when tokens are available.
PayPalMissing wallets.paypal, wrong entry type, or empty funding options.Complete PayPal onboarding in the Unity Portal. Verify the session includes allowedFundingTypes.wallets.paypal, transactionData.entryType == EntryType.Ecom (otherwise SDK1118), and a non-empty allowedFundingOptions on the PayPal wallet config (or a methodConfig.paypal.fundingSources override).
Google PayGoogle Play Services not available, no cards in Google Wallet or the test suite, or unsupported device.Verify Google Play Services is installed, set up Google Pay test cards via Google's test card suite (not Drop-in form PANs), and test on a physical device or emulator with Play Services. Confirm allowedFundingTypes.wallets.googlePay is present.
AeropayMissing payByBanks.aeropay, currency isn't USD, entry type isn't Ecom, missing intent, or invalid non-empty shopper data at load.Enable Aeropay in the Unity Portal. Confirm the session includes allowedFundingTypes.payByBanks.aeropay with externalMerchantId and configurationId. Use currency = "USD" and EntryType.Ecom. Set aeropayDropInIntent. Malformed non-empty shopper fields fire SDK1300 and hide the panel when methodConfig.aeropay.userId is not set; empty fields are OK. When userId is set, consumer validation at load is skipped. Alternatively, set methodConfig.aeropay.userId for a returning shopper (use UAT-approved test user IDs). See Aeropay.

Use these diagnostic steps:

import android.content.Context
import android.os.Build
import android.util.Log
import com.google.android.gms.common.ConnectionResult
import com.google.android.gms.common.GoogleApiAvailability
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.services.models.transaction.Shopper

fun diagnosePaymentMethodVisibility(
    context: Context,
    session: SessionConfig?,
    config: CheckoutDropInConfig? = null,
    entryType: EntryType? = null,
    shopper: Shopper? = null,
) {
    Log.d("PaymentMethods", "=== Payment method diagnostics ===")
    
    val fundingTypes = session?.allowedFundingTypes
    Log.d("PaymentMethods", "Session funding types: $fundingTypes")
    
    // Check cards: requires the cards key (empty list OK). cardSchemes alone is insufficient.
    if (fundingTypes?.cards != null) {
        Log.d("PaymentMethods", "Cards key present: ${fundingTypes.cards}")
        Log.d("PaymentMethods", "cardSchemes (networks only): ${fundingTypes.cardSchemes}")
    } else {
        Log.w("PaymentMethods", "Cards not enabled in session (cards key missing)")
        if (fundingTypes?.cardSchemes != null) {
            Log.w("PaymentMethods", "cardSchemes is set but does not enable the Card panel")
        }
    }

    val showCOF = config?.methodConfig?.card?.showCOF
    val showNewCard = config?.methodConfig?.card?.showNewCard
    Log.d("PaymentMethods", "showCOF=$showCOF showNewCard=$showNewCard")
    if (showCOF == false && showNewCard == false) {
        Log.w(
            "PaymentMethods",
            "Both showCOF and showNewCard are false. Card panel will be hidden even if session.cards is present"
        )
    }
    if (showCOF != false && shopper?.id.isNullOrEmpty()) {
        Log.w("PaymentMethods", "COF may be unavailable: onGetShopper id is empty")
    }
    
    // Check PayPal
    val paypal = fundingTypes?.wallets?.paypal
    if (paypal != null) {
        Log.d("PaymentMethods", "PayPal enabled: $paypal")
        Log.d("PaymentMethods", "PayPal allowedFundingOptions: ${paypal.allowedFundingOptions}")
        if (paypal.allowedFundingOptions.isNullOrEmpty() &&
            config?.methodConfig?.paypal?.fundingSources.isNullOrEmpty()
        ) {
            Log.w("PaymentMethods", "PayPal funding options empty. Buttons may not render")
        }
        if (entryType != null && entryType != EntryType.Ecom) {
            Log.w("PaymentMethods", "PayPal requires EntryType.Ecom (SDK1118 if not)")
        }
    } else {
        Log.w("PaymentMethods", "PayPal not enabled in session")
    }
    
    // Check Google Pay
    if (fundingTypes?.wallets?.googlePay != null) {
        Log.d("PaymentMethods", "Google Pay configuration present")
        
        val apiAvailability = GoogleApiAvailability.getInstance()
        val resultCode = apiAvailability.isGooglePlayServicesAvailable(context)
        
        if (resultCode == ConnectionResult.SUCCESS) {
            Log.d("PaymentMethods", "Google Play Services available")
        } else {
            Log.w("PaymentMethods", "Google Play Services not available: $resultCode")
        }
    } else {
        Log.w("PaymentMethods", "Google Pay not configured in session")
    }

    // Check Aeropay
    val aeropay = fundingTypes?.payByBanks?.aeropay
    if (aeropay != null) {
        Log.d("PaymentMethods", "Aeropay funding present: $aeropay")
        if (aeropay.externalMerchantId.isNullOrBlank() ||
            aeropay.configurationId.isNullOrBlank()
        ) {
            Log.w(
                "PaymentMethods",
                "Aeropay credentials incomplete (externalMerchantId or configurationId). Expect SDK1125"
            )
        }
        if (entryType != null && entryType != EntryType.Ecom) {
            Log.w("PaymentMethods", "Aeropay requires EntryType.Ecom (SDK0114 if not)")
        }
        val currency = config?.transactionData?.currency
        if (currency != null && currency != "USD") {
            Log.w("PaymentMethods", "Aeropay requires USD currency (SDK0116 if not)")
        }
        val aeropayIntent = config?.transactionData?.intent?.aeropayDropInIntent
        if (aeropayIntent == null) {
            Log.w(
                "PaymentMethods",
                "aeropayDropInIntent not set. Expect SDK0115 underlying (surfaces as SDK1125)"
            )
        }
    } else {
        Log.w("PaymentMethods", "Aeropay not configured in session (payByBanks.aeropay missing)")
    }
    
    // Check device info
    Log.d("PaymentMethods", "Android API level: ${Build.VERSION.SDK_INT}")
    Log.d("PaymentMethods", "Device: ${Build.MANUFACTURER} ${Build.MODEL}")
    
    Log.d("PaymentMethods", "===================================")
}

Look for these symptoms:

  • The store-card consent checkbox appears when you expect silent storage.
  • A new card payment succeeds but the card isn't saved for card-on-file.
  • A new card is saved, but the saved-cards list doesn't update until the shopper leaves checkout.

Common causes and solutions:

SymptomCauseSolution
Consent checkbox still shownSite storeCardConsent is still AskSet the Unity site configuration to ConsentAlreadyObtained (or DontAsk if you don't want storage). Confirm the value returned by the checkout Drop-in configurations API.
New card not storedMissing shopper id, site is DontAsk, or site is Ask without a checked checkbox and without onGetConsent returning trueImplement onGetShopper with a non-empty id. Align site storeCardConsent with your consent flow. For Ask without a checkbox, implement onGetConsent. See Cards — Store-card consent.
New card succeeds but card-on-file list unchangedshowCOF is off, payment used a saved card (not new card), shopper id missing, or site mode doesn't store the cardSet showCOF to true, confirm the payment was a new card that was stored, and that site mode and shopper id allow storage. Card-on-file submit doesn't refresh tokens after success.
Expected onGetConsent to run for cards under ConsentAlreadyObtainedDrop-in grants consent at tokenisation without calling onGetConsent in that modeExpected behaviour. Collect consent outside Drop-in before relying on ConsentAlreadyObtained.

Aeropay panel not shown

Look for these symptoms:

  • The Aeropay payment method isn't visible.
  • Other methods appear, but Pay by bank via Aeropay doesn't.

Check the following:

  • Session includes allowedFundingTypes.payByBanks.aeropay with externalMerchantId and configurationId.
  • transactionData.currency is "USD".
  • transactionData.entryType is EntryType.Ecom.
  • transactionData.intent.aeropayDropInIntent is set.
  • Non-empty invalid onGetShopper fields at load fire SDK1300 and hide the panel when methodConfig.aeropay.userId is not set. Empty fields are allowed. When userId is provided, consumer validation at load is skipped.
  • Alternatively, set methodConfig.aeropay.userId for a returning shopper (skips consumer-data validation at load; use UAT-approved test user IDs from your integration contact).

If onError fires with SDK0114 (entry type), SDK0116 (currency), SDK1125 (create failure, including blank credentials or missing aeropayDropInIntent), or SDK1300 (shopper data), see Aeropay.

Google Pay not working

Look for these symptoms:

  • Google Pay button doesn't appear.
  • Google Pay sheet doesn't open when tapped.
  • Payment fails with Google Pay errors.

Common causes and solutions:

CauseSolution
Google Play Services not installed.Install Google Play Services on the device or use an emulator with Play Services. Complete Google Pay onboarding in the Unity Portal and verify that the session includes allowedFundingTypes.wallets.googlePay.
No cards in Google Wallet or the test suite.Set up Google Pay test cards via the Google Pay test card suite. Don't reuse Drop-in manual card-entry PANs.
Minimum API level not met.Google Pay requires Android 7.0 (API level 24) or higher.
Merchant ID missing or invalid.Add a valid Google Pay merchant ID in production (optional for testing).
Device not supported.Test on a physical device or emulator with Google Play.

Solution: optional standalone Google Pay API probe. Drop-in already checks Google Pay readiness internally when allowedFundingTypes.wallets.googlePay is present.

import android.content.Context
import android.util.Log
import com.google.android.gms.wallet.PaymentsClient
import com.google.android.gms.wallet.Wallet
import com.google.android.gms.wallet.WalletConstants
import com.google.android.gms.wallet.IsReadyToPayRequest
import org.json.JSONObject
import org.json.JSONArray

fun checkGooglePayAvailability(context: Context) {
    val paymentsClient: PaymentsClient = Wallet.getPaymentsClient(
        context,
        Wallet.WalletOptions.Builder()
            .setEnvironment(WalletConstants.ENVIRONMENT_TEST)
            .build()
    )
    
    val request = IsReadyToPayRequest.fromJson(
        JSONObject().apply {
            put("apiVersion", 2)
            put("apiVersionMinor", 0)
            put("allowedPaymentMethods", JSONArray().apply {
                put(JSONObject().apply {
                    put("type", "CARD")
                    put("parameters", JSONObject().apply {
                        put("allowedAuthMethods", JSONArray().apply {
                            put("PAN_ONLY")
                            put("CRYPTOGRAM_3DS")
                        })
                        put("allowedCardNetworks", JSONArray().apply {
                            put("VISA")
                            put("MASTERCARD")
                        })
                    })
                })
            })
        }.toString()
    )
    
    paymentsClient.isReadyToPay(request).addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d("GooglePay", "Google Pay is available: ${task.result}")
        } else {
            Log.w("GooglePay", "Google Pay check failed", task.exception)
        }
    }
}

Backend verification failing

Look for these symptoms:

  • Frontend onSuccess fires but backend verification fails.
  • Orders aren't being fulfilled.
  • "Payment verification failed" errors.

Common causes and solutions:

CauseSolution
Webhook not configured.Set up a webhook URL in the Unity Portal and implement a webhook handler on your backend.
Webhook authentication failing.Verify your webhook signature or authentication. Check your HMAC implementation.
Race condition (GET before webhook).Implement a fallback to the Get transaction details API if the webhook hasn't arrived yet.
Transaction ID mismatchVerify that the systemTransactionId and merchantTransactionId match database records.

Implement robust backend verification:

// Backend webhook handler (Node.js/Express example)
app.post('/webhooks/pxp', async (req, res) => {
  try {
    const events = req.body;
    
    // Verify webhook authenticity using HMAC
    if (!verifyWebhookSignature(req)) {
      console.error('Invalid webhook signature');
      return res.status(401).json({ error: 'Unauthorised' });
    }
    
    for (const event of events) {
      if (event.eventCategory === 'Transaction') {
        const txn = event.eventData;
        
        console.log('Processing transaction:', txn.systemTransactionId);
        
        // Idempotency check
        const existing = await db.transactions.findOne({
          systemTransactionId: txn.systemTransactionId
        });
        
        if (existing) {
          console.log('Transaction already processed, skipping');
          continue;
        }
        
        // Verify transaction state
        if (txn.state === 'Authorised' || txn.state === 'Captured') {
          // Find order by merchant transaction ID
          const order = await db.orders.findOne({
            transactionId: txn.merchantTransactionId
          });
          
          if (!order) {
            console.error('Order not found:', txn.merchantTransactionId);
            continue;
          }
          
          // Verify amount matches
          const transactionAmount = txn.amounts?.transactionValue || txn.amount;
          if (Math.abs(transactionAmount - order.amount) > 0.01) {
            console.error('Amount mismatch:', {
              expected: order.amount,
              actual: transactionAmount
            });
            continue;
          }
          
          // Mark transaction as processed
          await db.transactions.create({
            systemTransactionId: txn.systemTransactionId,
            merchantTransactionId: txn.merchantTransactionId,
            amount: transactionAmount,
            state: txn.state,
            processedAt: new Date()
          });
          
          // Fulfill order
          await fulfillOrder(order.id, txn.systemTransactionId);
          
          console.log('Order fulfilled:', order.id);
        }
      }
    }
    
    // Always return success
    res.json({ state: 'Success' });
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Android-specific issues

ProGuard or R8 stripping SDK classes

Look for these symptoms:

  • Drop-in works in debug builds but crashes in release builds.
  • ClassNotFoundException or NoSuchMethodException in production.

Solution: use the SDK's bundled consumer rules

The io.pxp:android-components-sdk AAR ships consumer-rules.pro (packaged as proguard.txt) for merchant apps with minifyEnabled true. Those rules already keep the public SDK API, components, analytics Gson fields, and related dependencies. You don't need to duplicate broad keep rules for normal integrations.

The SDK uses Gson, not Kotlin Serialization. Don't add -keep @kotlinx.serialization.Serializable class ** unless your own app uses Kotlin Serialization independently.

Only add app-specific ProGuard rules for:

  • Your own Gson or reflection models
  • Any third-party libraries your app uses outside the SDK

Example of an optional, narrow app keep (only if needed):

# Optional: keep your own models used with Gson reflection
-keep class com.example.checkout.models.** { *; }

Memory leaks

Look for these symptoms:

  • App performance degrades over time.
  • Android Studio Profiler shows growing memory usage.
  • Out of memory crashes after multiple checkout attempts.

Solution: call CheckoutDropIn.destroy() when disposing, and prefer checkoutDropIn.Content() over retaining CheckoutDropInComponent.

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import java.time.Instant
import java.util.UUID

// Implement or reuse fetchSessionFromBackend() from the session-refresh sample above.

@Composable
fun CheckoutScreenDisposeDestroy() {
    val context = LocalContext.current
    var session by remember { mutableStateOf<SessionConfig?>(null) }

    LaunchedEffect(Unit) {
        session = fetchSessionFromBackend()
    }

    val checkoutDropIn = remember(session) {
        session?.let { sessionConfig ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.TEST,
                    session = sessionConfig,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 25.00,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Authorisation
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = UUID.randomUUID().toString(),
                        merchantTransactionDate = { Instant.now().toString() }
                    )
                )
            )
        }
    }

    DisposableEffect(checkoutDropIn) {
        onDispose {
            checkoutDropIn?.destroy()
        }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
}

Keyboard covering input fields

Look for these symptoms:

  • Keyboard covers the submit button.
  • User can't see what they're typing.
  • Layout doesn't adjust when keyboard appears.

Handle window insets so the keyboard does not cover fields:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import java.time.Instant
import java.util.UUID

// Implement or reuse fetchSessionFromBackend() from the session-refresh sample above.

@Composable
fun CheckoutScreenKeyboardSafe() {
    val context = LocalContext.current
    val scrollState = rememberScrollState()
    var session by remember { mutableStateOf<SessionConfig?>(null) }

    LaunchedEffect(Unit) {
        session = fetchSessionFromBackend()
    }

    val checkoutDropIn = remember(session) {
        session?.let { sessionConfig ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.TEST,
                    session = sessionConfig,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 25.00,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Authorisation
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = UUID.randomUUID().toString(),
                        merchantTransactionDate = { Instant.now().toString() }
                    )
                )
            )
        }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    Scaffold(
        modifier = Modifier
            .fillMaxSize()
            .imePadding() // Adjust for keyboard
    ) { paddingValues ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(paddingValues)
                .verticalScroll(scrollState)
                .padding(16.dp)
        ) {
            checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
        }
    }
}

In AndroidManifest.xml:

<activity
    android:name=".CheckoutActivity"
    android:windowSoftInputMode="adjustResize">
</activity>

Error codes reference

For a complete list of error codes and their meanings, see the Error handling guide.

Getting additional help

If you're still experiencing issues, try these troubleshooting steps.

Enable debug logging

Add detailed logging using Logcat. BaseAnalyticsEvent exposes eventName, sessionId, and timestamp only. There is no toMap(). For subclass-specific properties, cast to the concrete event type before logging.

CheckoutDropInConfig(
    // ... other config
    analyticsEvent = { event ->
        if (BuildConfig.DEBUG) {
            Log.d(
                "DropInAnalytics",
                "event=${event.eventName} sessionId=${event.sessionId} ts=${event.timestamp}",
            )
        }
    }
)

BaseAnalyticsEvent.timestamp is epoch milliseconds (Long), not an ISO 8601 string. Convert it for human-readable logs if needed.

Collect diagnostic information

When contacting support, include:

import android.content.ClipData
import android.content.ClipboardManager
import android.content.Context
import android.os.Build
import android.util.Log
import androidx.core.content.pm.PackageInfoCompat
import com.pxp.checkout.models.SessionConfig
import java.time.Instant
import org.json.JSONObject

fun collectDiagnosticInfo(context: Context, session: SessionConfig?): String {
    val info = JSONObject().apply {
        // Device information
        put("manufacturer", Build.MANUFACTURER)
        put("model", Build.MODEL)
        put("androidVersion", Build.VERSION.SDK_INT)
        put("androidRelease", Build.VERSION.RELEASE)
        
        // Screen information
        val metrics = context.resources.displayMetrics
        put("screenWidth", metrics.widthPixels)
        put("screenHeight", metrics.heightPixels)
        put("screenDensity", metrics.density)
        
        // App information
        val packageInfo = context.packageManager.getPackageInfo(context.packageName, 0)
        put("appVersion", packageInfo.versionName)
        // Prefer longVersionCode when targeting API 28+
        put("appVersionCode", PackageInfoCompat.getLongVersionCode(packageInfo))
        
        // SDK information. There is no CheckoutDropIn.sdkVersion API.
        // Record the resolved Maven artifact from your lockfile or Gradle report, e.g.:
        // ./gradlew :app:dependencies --configuration debugCompileClasspath | findstr android-components-sdk
        put("sdkArtifact", "io.pxp:android-components-sdk:{versionNumber}")
        put("environment", "test") // Replace with actual environment from your config
        
        // Session info (sanitised)
        put("sessionIdPresent", !session?.sessionId.isNullOrEmpty())
        put("dataPresent", !session?.data.isNullOrEmpty())
        put("encryptionKeyPresent", !session?.encryptionKey.isNullOrEmpty())
        put("localePresent", !session?.locale.isNullOrEmpty())
        put("allowedFundingTypes", session?.allowedFundingTypes.toString())
        
        // Timestamp
        put("timestamp", Instant.now().toString())
    }
    
    val diagnostics = info.toString(2)
    Log.d("Diagnostics", diagnostics)
    
    // Copy to clipboard
    val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    val clip = ClipData.newPlainText("Diagnostic Info", diagnostics)
    clipboard.setPrimaryClip(clip)
    
    return diagnostics
}

When contacting support, always include your merchant ID, environment (test or live), Android version, device model, resolved SDK artifact version (io.pxp:android-components-sdk:{versionNumber}), and any relevant error messages or Logcat logs.