Troubleshooting

The Paze Android component surfaces BaseSdkException errors with structured codes in the SDK12XX range. The following table maps common exception types to their error codes:

Shopper cancellation and closing the Custom Tab without completing checkout call onCheckoutIncomplete rather than throwing an exception. Missing Paze clientId surfaces as SDK1202 at presentment. Authorisation submission failures (SDK1235) route to onSubmitError, not onError. Create-session and complete API provider errors may also surface through PazeProviderException or PazeInitializationFailedException with provider-specific codes — map these using error.message and your backend logs. Codes such as SDK1231 and SDK1232 are defined in the SDK but are typically returned by the create-session API rather than thrown locally at presentment.

Route onError, onCheckoutIncomplete, and onSubmitError to appropriate user messaging and logging:

config.onError = { error ->
    Log.e("Paze", "Error: ${error.errorCode} ${error.message}")

    when (error.errorCode) {
        "SDK1202", "SDK1202A" -> {
            showAlternativePaymentMethods()
            showMessage("Paze is not available for this order.")
        }
        "SDK1210", "SDK1212" -> showMessage("Please check your contact details.")
        "SDK1213" -> showMessage("Paze is only available for USD transactions.")
        "SDK1233" -> showMessage("Payment token could not be processed. Please try again.")
        "SDK1200", "SDK1214" -> showMessage("Paze checkout failed. Please try again.")
        else -> showMessage("Payment could not be completed. Please try again.")
    }
}

config.onCheckoutIncomplete = { result ->
    if (result.reason?.contains("cancel", ignoreCase = true) == true) {
        showMessage("Payment cancelled.")
    } else {
        showMessage("Payment was not completed. Please try again.")
    }
}

config.onSubmitError = { submitResult ->
    val failed = submitResult as? FailedSubmitResult
    Log.e("Paze", "Submit error: ${failed?.errorCode} ${failed?.errorReason}")
    showMessage("Payment could not be processed. Please try another method.")
}

Include these fields when logging errors for PXP or Paze support:

fun logPazeError(error: BaseSdkException, context: Map<String, Any> = emptyMap()) {
    val payload = buildMap {
        put("errorCode", error.errorCode)
        put("errorMessage", error.message ?: "")
        put("timestamp", Instant.now().toString())
        putAll(context)
    }
    // Send to your logging or crash reporting service
    Log.e("Paze", "Support log: $payload")
}

Use this section when Paze is not appearing in the Unity Portal, missing from your session response, or failing during presentment with SDK1202. For portal setup steps, see Onboarding.

Symptom: The Paze service doesn't appear in your site's Services tab.

Solution: Enable Paze at the merchant group level first (Onboarding, Step 1), then return to the site configuration.

Symptom: Session response doesn't include allowedFundingTypes.wallets.paze.clientId.

Solution:

1. Verify the client ID is saved in Paze Account Settings for the correct site.
2. Create a new session after saving portal changes.
3. Confirm you are using the correct site name in your session request.

Symptom: Presentment fails with missing clientId.

Solution: Confirm clientId is in the session response from your backend and passed through SessionConfig when initialising the SDK. Re-create the session after saving portal changes. Non-USD currency surfaces separately as SDK1213; invalid identity fields surface as SDK1210 or SDK1212.

The symptoms of this are:

• onPresentmentResolved(false) fires alongside onError.
• The button is hidden in your Compose UI after you render Content().
• Checkout fails immediately on tap when presentment succeeded but checkout-time validation fails.

Log session and component configuration when presentment fails:

fun diagnosePazePresentment(sdkConfig: PxpSdkConfig, config: PazeButtonComponentConfig) {
    Log.d("Paze", "=== Presentment Diagnostics ===")
    val paze = sdkConfig.session.allowedFundingTypes?.wallets?.paze
    Log.d("Paze", "Client ID: ${if (paze?.clientId.isNullOrBlank()) "Missing" else "Present"}")
    Log.d("Paze", "MCC: ${paze?.merchantCategoryCode ?: "Not set"}")
    Log.d("Paze", "Currency: ${sdkConfig.transactionData.currency}")
    Log.d("Paze", "Email: ${config.emailAddress ?: "Not set"}")
    Log.d("Paze", "Phone: ${config.phoneNumber ?: "Not set"}")
}

These presentment and checkout validation issues map to the most frequent error codes:

The symptoms of this are:

• The shopper taps the Paze button but checkout doesn't complete.
• onCheckoutIncomplete fires unexpectedly.
• The Custom Tab opens but the shopper cannot complete payment.

Currency validation: Confirm transactionData.currency is "USD" before showing the Paze section.

User cancellation: When the shopper closes the Custom Tab, expect onCheckoutIncomplete:

config.onCheckoutIncomplete = { result ->
    if (result.reason?.contains("cancel", ignoreCase = true) == true) {
        showMessage("Payment cancelled. You can try again when ready.")
    } else {
        showMessage("Unable to complete checkout. Please try a different payment method.")
    }
}

Tab closed without redirect: If the shopper dismisses the Custom Tab without a redirect callback, onCheckoutIncomplete fires when the host Activity resumes.

Merchant rejection: Returning false from onCheckoutComplete triggers onCheckoutIncomplete.

Pre-checkout block: Disable the button in your UI until prerequisites are met. onPazeButtonClicked cannot cancel checkout — the SDK opens the Custom Tab when that callback completes.

UAT wallet access: In UAT, confirm the test shopper email or phone is provisioned for your Paze merchant account.

The symptoms of this are:

• The Paze Custom Tab completes but your app doesn't process the result.
• Checkout hangs after the shopper finishes in the browser.
• onCheckoutComplete never fires.

Verify your host Activity handles redirects:

import com.pxp.checkout.components.paze.payment.deliverPazeCheckoutResult

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    intent.deliverPazeCheckoutResult(pazeButton)
}

Confirm checkout was launched from an Activity context so PazeRedirectRegistry could register the host.

Common redirect handling issues and fixes:

The symptoms of this are:

• Checkout completes but the flow fails before decryption.
• onError fires with SDK1202A.

Solution: Include merchantCategoryCode in the session response from your backend. The SDK requires it when building the Paze complete request.

The symptoms of this are:

• Checkout completes but payment doesn't process.
• onPostDecryption never fires.
• onError fires with SDK1233.

Common decryption failure causes:

Decryption failures surface through onError with SDK1233. See Analytics for PazeDecryptionFailed events.

The symptoms of this are:

• onSubmitError fires with FailedSubmitResult.
• onPostAuthorisation may still fire with transaction IDs when Unity returns an error state and the callback is registered — always verify the outcome on your backend.

Log submission failures with correlation IDs for support:

config.onSubmitError = { result ->
    val failed = result as? FailedSubmitResult
    Log.e("Paze", "Submit failed: ${failed?.errorCode} ${failed?.errorReason}")
    Log.e("Paze", "Correlation ID: ${failed?.correlationId}")
}

Common authorisation submission failure causes:

Hard submission failures surface through onSubmitError.

Symptom: You expected a successful payment but the transaction outcome is unclear, or the callback did not run.

Solution: Register onPostAuthorisation on the component config — the SDK only invokes it when the callback is set. The SDK calls it when it receives a MerchantSubmitResult with merchantTransactionId and systemTransactionId. It does not run on the merchant-managed decryption path (onPreDecryption returns false). Verify the payment outcome on your backend — Unity may return an error state while still providing transaction identifiers. Hard submission failures route to onSubmitError instead.

config.onPostAuthorisation = { result ->
    verifyPaymentOnBackend(result.systemTransactionId)
}