Troubleshooting

Common problems integrating the PayPal Mobile SDK v3.0.0 on Android, organized by symptom. For an error that happens inside one specific flow, also check that guide's Result handling section.

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: createPayPalSession() was not called 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 CoreEnvironment.SANDBOX or .LIVE is set as intended.
• Verify: start() launches the checkout flow without an auth or configuration error.

Return and redirect

These problems appear once 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: your App Link is not verified, or the return and cancel URLs do not match the host + path prefix your activity is registered for.
• 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: the return intent was not forwarded, or the activity relaunches instead of resuming. Remember that start()'s own callback only reports PayPalPresentAuthChallengeResult (Success or Failure), meaning whether checkout launched, not the outcome. The actual 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, the PayPal app is not installed, the buyer is not in the US, or the identity email 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 return was not delivered cleanly and resolved 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 is lost when the activity is recreated

• 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 instead of losing it.

Still stuck?

• Re-check Install and set up.
• Look up exact class and method signatures in the generated API reference, Dokka.
• Run the sample app to compare against a known-good integration.
• Contact your PayPal account team or 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.