Update iOS SDK from v2 to v3

This guide describes how to move an existing PayPal Mobile SDK v2 (2.x) iOS integration to v3.0.0. The largest changes are in PayPal Checkout: the client was replaced with a new class in a new module, checkout is now session-first, CoreConfig requires a merchantID, return URLs moved into a URL config, and App Switch now requires Universal Links (v2's web flow used a hardcoded callback scheme for its own redirects).

Review what changed in PayPal Checkout

Card (ACDC) keeps its own client; the main change it inherits is the merchantID on CoreConfig. Card's approveOrder() still resolves 3DS inline on iOS.

Before you upgrade

• Get your merchant ID, the encrypted merchant account ID, from the PayPal Developer Dashboard, which is now required to initialize the SDK.
• Add an Associated Domains entitlement and serve an AASA file for your return domain. v3 App Switch returns through Universal Links, whereas v2's web flow used the hardcoded sdk.ios.paypal scheme for its own redirect.
• Toolchain is unchanged: Xcode 15+, iOS 16+, Swift 5.9+.

Update the dependency

Bump CorePayments and swap the PayPal Checkout product for its v3 successor. The module was renamed along with the client:

# Podfile
pod 'PayPal/CorePayments', '~> 3.0'
pod 'PayPal/PayPalPayments', '~> 3.0'   # was PayPal/PayPalWebPayments in v2
pod 'PayPal/PaymentButtons', '~> 3.0'
pod 'PayPal/FraudProtection', '~> 3.0'

Migrate PayPal Checkout

Use this diff to guide the change:

  let config = CoreConfig(
      clientID: "<CLIENT_ID>",
      environment: .sandbox,
+     merchantID: "<MERCHANT_ID>"   // now required, distinct from your client ID
  )

- let client = PayPalWebCheckoutClient(config: config)
+ let client = PayPalClient(config: config)
+ let urlConfig = PayPalURLConfig(
+     returnAppURL: URL(string: "https://example.com/merchant-app/return")!,
+     cancelAppURL: URL(string: "https://example.com/merchant-app/cancel")!,
+     fallbackSchemeURL: URL(string: "merchantapp://return")!
+ )

  func onPayPalButtonTapped() async throws {
+     // NEW: prepare the session before start()
+     client.createPayPalSession(
+         sessionType: .checkout,
+         userIdentity: PayPalUserIdentity(email: "buyer@example.com", phone: nil),
+         urlConfig: urlConfig,
+         userAction: .continue
+     )
      let orderID = try await myServer.createOrder()
-     client.start(request: PayPalWebCheckoutRequest(orderID: orderID)) { result in /* ... */ }
+     client.start(orderID: orderID) { result in
+         switch result {
+         case .success(let checkout): captureOrder(checkout.orderID)
+         case .failure(let error):
+             if PayPalError.isCheckoutCanceled(error) {
+                 showCheckoutScreen()
+             } else {
+                 showError(error.localizedDescription)
+             }
+         }
+     }
  }

+ // NEW in v3: forward the Universal Link return to the SDK
+ func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
+     guard let url = userActivity.webpageURL else { return }
+     client.handleReturnURL(url)
+ }

Configure Info.plist and entitlements

Add the custom-scheme fallbackSchemeURL under CFBundleURLTypes. It's optional on PayPalURLConfig; see Install and set up for why you should set it regardless. Also declare paypal under LSApplicationQueriesSchemes so the SDK can detect the PayPal app, and add the Associated Domains entitlement for your return domain. v2's web flow needed none of these for PayPal Checkout, because its return handling was internal to ASWebAuthenticationSession, built on the hardcoded sdk.ios.paypal scheme.

Verify the upgrade

• The project compiles with PayPalClient (module PayPalPayments) and no references to PayPalWebCheckoutClient or PayPalWebPayments remain.
• A sandbox checkout completes end to end: createPayPalSession(sessionType:) → start(orderID:) → return through handleReturnURL(url) → capture.
• sessionNotStarted does not occur, confirming createPayPalSession() runs before start().

See also

• Install and set up: add the SDK, initialize CoreConfig, and register your return links.
• PayPal Checkout integration guide: integrate One-Time Checkout, save payment methods, Pay Later, and PayPal Credit.
• Troubleshooting: diagnose common build and integration failures by symptom.