Update iOS SDK from v2 to v3

Plan for a client rename, a new required merchantID, and return URLs that move into a URL config, which affects both your app code and your Universal Link setup.

The largest changes are in PayPal Checkout:

• PayPal replaced the client with a new class in a new module.
• Checkout is now session-first.
• CoreConfig requires a merchantID.
• Return URLs moved into a URL config.
• 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 account ID from the PayPal Developer Dashboard. The SDK now requires it to initialize.
• Add an Associated Domains entitlement and serve an AASA file for your return domain. V3 App Switch returns through Universal Links. 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. PayPal renamed the module 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. Then 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.
• The sessionNotStarted error 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.