Troubleshooting

Resolve common integration issues by finding the symptom that matches what you see.

Each entry gives the symptom, its likely cause, a fix, and a way to confirm the fix worked. For errors specific to one payment method, also check the results section of the payment method guide.

Build and dependency

These are the build and dependency errors you're most likely to hit while adding the SDK.

Failed to resolve: com.paypal.android:...

• Cause: the module or version is not available, or Maven Central is not in your repositories.
• Fix: confirm mavenCentral() is in your repositories and use a current v3 version; add only the modules you use.
• Verify: a clean Gradle sync and build completes without the unresolved-dependency error.

Duplicate class or version conflict at build time

• Cause: a transitive dependency (for example browser-switch, Kotlin stdlib) conflicts with another library.
• Fix: align to the SDK's expected toolchain: Java 17, a recent Android Gradle Plugin, and a compatible Kotlin version. Then resolve conflicting transitive versions.
• Verify: the build completes without duplicate-class or dependency-resolution errors.

SDK classes missing in a minified (R8/ProGuard) release build

• Cause: code shrinking stripped classes the SDK needs.
• Fix: add keep rules for the PayPal SDK packages you use, then re-test the release build.
• Verify: the release build completes and the SDK's classes are present in the resulting APK or bundle.

Setup and initialization

These errors show up early, usually on your first call into the SDK, and generally trace back to config or call order.

PayPalEvent.SESSION_NOT_STARTED reported, and the start() or vault() callback receives a PayPalError.sessionNotCreatedError failure

• Cause: you did not call createPayPalSession() first.
• Fix: call createPayPalSession(tokenType, userIdentity, urlConfig, userAction) in your button's onClick, before or alongside order creation.
• Verify: start() or vault() proceeds without a sessionNotCreatedError failure.

Auth or configuration errors right after start()

• Cause: wrong coreEnvironment, or a missing or not-valid merchantId, required in v3 and distinct from your client ID.
• Fix: recheck CoreConfig: clientId, merchantId, and whether you set CoreEnvironment.SANDBOX or .LIVE as intended.
• Verify: start() launches the checkout flow without an auth or configuration error.

Return and redirect

These problems appear after the buyer leaves your app for checkout and needs to find their way back.

The buyer completes checkout but never returns to your app

• Cause: Android has not verified your App Link, or the return and cancel URLs do not match the host + path prefix you registered for your activity.
• Fix: verify /.well-known/assetlinks.json, with your app's SHA-256 fingerprint, android:autoVerify="true", and Open supported links enabled. Keep return and cancel URLs under the registered host + prefix. Registering a fallbackSchemeUrl alongside your App Link covers delivery failures. The SDK only requires at least one of returnAppUrl or fallbackSchemeUrl to be set, but setting both is the safer default.
• Verify: completing checkout returns the buyer to your app and delivers the return intent to your registered activity.

No PayPalFinishStartResult after the buyer returns

• Cause: you did not forward the return intent, or the activity relaunches instead of resuming. Remember that the start() callback only reports PayPalPresentAuthChallengeResult (Success or Failure), meaning whether checkout launched. The Success, Canceled, Failure, or NoResult outcome comes from finishStart(intent). Also remember finishStart(intent) returns PayPalFinishStartResult?. A null result, meaning no matching start() or vault() call in this process, is a distinct case from NoResult and needs its own branch.
• Fix: call checkoutClient.finishStart(intent) in onNewIntent, and set the return activity to launchMode="singleTop".
• Verify: finishStart(intent) returns a non-null PayPalFinishStartResult after the buyer returns.

Checkout stayed in the browser instead of opening the PayPal app

• Cause: expected fallback. The buyer is not App Switch eligible, or the PayPal app is not installed. Other triggers are a buyer outside the US or an identity email that does not match the signed-in PayPal account.
• Fix: to exercise the app-switch path in testing, meet all trigger conditions; see PayPal Checkout → Test and go live.
• Verify: with all trigger conditions met, checkout opens in the PayPal app instead of the browser.

Result and challenge

These come up after the buyer returns, when the SDK is reporting an outcome you didn't expect.

Unexpected Cancel

• Cause: the buyer backed out, or the SDK did not receive the return cleanly and resolved it as canceled.
• Fix: treat Cancel as a normal outcome, returning the buyer to checkout; if it happens unexpectedly often, re-check your App Link and return handling.
• Verify: a completed checkout no longer resolves as Cancel, and a genuine cancel still returns the buyer to checkout cleanly.

A card 3DS challenge never appears

• Cause: you did not call presentAuthChallenge() on an AuthorizationRequired result, or did not call finishApproveOrder(intent) on return.
• Fix: on AuthorizationRequired, call cardClient.presentAuthChallenge(activity, authChallenge), then cardClient.finishApproveOrder(intent) in onNewIntent.
• Verify: the 3DS challenge appears on an AuthorizationRequired result and finishApproveOrder(intent) completes after it.

Process death

This happens when Android reclaims your app's process while a challenge is still in flight.

An in-flight 3DS challenge disappears when Android recreates the activity

• Cause: the client's in-flight state did not survive process death.
• Fix: persist cardClient.instanceState before the process dies and call cardClient.restore(instanceState) on recreation.
• Verify: after forcing process death during a 3DS challenge, restoring the activity resumes the challenge.

Still stuck?

• Re-check Install and set up.
• Run the sample app to compare against a known-good integration.
• Contact your PayPal account team or PayPal Technical Support.

See also

• Install and set up: add the SDK, initialize CoreConfig, and register your return links.
• PayPal Checkout: integrate one-time checkout, save payment methods, Pay Later, and PayPal Credit.
• Cards: integrate card payments and saving cards.