Troubleshooting

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

Build and dependency

This is the build error you're most likely to hit while adding the SDK.

Swift Package Manager or CocoaPods cannot resolve the PayPal products

• Cause: the product name is wrong or not added.
• Fix: add CorePayments plus the products you use (PayPalPayments, FraudProtection, PaymentButtons, CardPayments).
• Verify: the package resolves and the app builds successfully.

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.

PayPalError.sessionNotStartedError returned on start() or vault()

• Cause: createPayPalSession() was not called first.
• Fix: call createPayPalSession(sessionType:userIdentity:urlConfig:userAction:) on PayPalClient in your button's action, before or alongside order creation.
• Verify: start() or vault() proceeds without a sessionNotStartedError failure.

Auth or configuration errors right after start()

• Cause: wrong environment, or a missing or not-valid merchantID, required in v3 and distinct from your client ID.
• Fix: recheck CoreConfig: confirm clientID, merchantID, and whether you're using .sandbox or .live.
• 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 Universal Link is not associated with your domain, or the return/cancel URLs are not under the associated domain.
• Fix: confirm the Associated Domains entitlement, applinks:example.com, and that your AASA file is served at https://<domain>/.well-known/apple-app-site-association. Keep return/cancel URLs on that domain. Setting fallbackSchemeURL in CFBundleURLTypes covers Universal Link delivery failures.
• Verify: completing checkout returns the buyer to your app.

The completion handler never fires after the buyer returns

• Cause: the return URL was not forwarded to the SDK.
• Fix: call checkoutClient.handleReturnURL(url) on your PayPalClient, from scene(_:continue:), or .onOpenURL in SwiftUI.
• Verify: the completion handler fires with a result after the buyer returns.

Checkout stayed in the in-app browser instead of opening the PayPal app

• Cause: LSApplicationQueriesSchemes is missing paypal, or expected fallback: the buyer is not 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: declare paypal under LSApplicationQueriesSchemes. 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 in-app browser.

Result and challenge

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

Unexpected cancel, or a .failure you expected to be a cancel

• Cause: cancellation is always surfaced as a .failure, never a separate .cancel case, for either PayPal or Card.
• Fix: before treating a failure as an error, check PayPalError.isCheckoutCanceled(error) / isVaultCanceled(error) for PayPal, or CardError.isThreeDSecureCanceled(error) for Card, and route the buyer back to checkout.
• Verify: a genuine cancel is now identified by the isCanceled check instead of falling through as an unhandled error.

Card fails with a 3DS URL error

• Cause: CardError.threeDSecureURLError: the challenge URL failed iOS's PayPal 3DS validation. On approveOrder(), the SDK checks the URL is a genuine PayPal Helios flow=3ds page before opening it. On vault(), the check is slightly weaker: it only confirms the URL contains helios, without also requiring flow=3ds.
• Fix: confirm you are on a genuine PayPal environment and order. If it persists, capture the URL and contact support.
• Verify: the 3DS challenge opens without a threeDSecureURLError.

Still stuck?

• Re-check Install and set up.
• Look up exact class and method signatures in the generated API reference, DocC.
• 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.