PR Comments

Author: baubrey91

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Braintree iOS SDK Release Notes
 
+## unreleased
+* PayPal
+  * Add optional `fallbackURLScheme` parameter to support custom URL scheme fallback in PayPal App Switch
+
 ## 6.40.0 (2025-11-20)
 * PayPal
     * Add `offerCredit` property to `PayPalCheckoutRequest`. Enables merchants to offer PayPal Credit for Checkout requests.
@@ -12,7 +16,6 @@
   * Add `userAction` property to `BTPayPalVaultRequest`
   * Add `paypal:tokenize:default-browser-switch:started` event for when the appSwitch fails for universalLink and `openURLInDefaultBrowser` is triggered.
   * Add `paypal:tokenize:default-browser-switch:succeeded` and `paypal:tokenize:default-browser-switch:failed` events for when the browser switch succeeds or fails.
-  * Add `fallbackUrlScheme` to client initializer for merchants to have fallback return url if https url fails
 
 ## 6.38.0 (2025-09-09)
 * BraintreeShopperInsights (BETA)

Sources/BraintreePayPal/BTPayPalCheckoutRequest.swift

@@ -168,15 +168,11 @@ import BraintreeCore
     public override func parameters(
         with configuration: BTConfiguration,
         universalLink: URL? = nil,
-        fallbackUrlScheme: String? = nil,
+        fallbackURLScheme: String? = nil,
         isPayPalAppInstalled: Bool = false
     ) -> [String: Any] {
-        var baseParameters = super.parameters(
-            with: configuration,
-            universalLink: universalLink,
-            fallbackUrlScheme: fallbackUrlScheme,
-            isPayPalAppInstalled: isPayPalAppInstalled
-        )
+        var baseParameters = super.parameters(with: configuration, universalLink: universalLink, isPayPalAppInstalled: isPayPalAppInstalled)
+        
         var checkoutParameters: [String: Any] = [
             "intent": intent.stringValue,
             "amount": amount,

Sources/BraintreePayPal/BTPayPalClient.swift

@@ -59,7 +59,7 @@ import BraintreeDataCollector
 
     private var universalLink: URL?
 
-    private var fallbackUrlScheme: String?
+    private var fallbackURLScheme: String?
 
     /// Indicates if the user returned back to the merchant app from the `BTWebAuthenticationSession`
     /// Will only be `true` if the user proceed through the `UIAlertController`
@@ -70,7 +70,7 @@ import BraintreeDataCollector
     private var contextID: String?
 
     /// Used to determine whether or not to render the WAS popup.
-    /// If the experiement is enabled, set the `prefersEphemeralWebBrowserSession` flag to true.
+    /// If the experiment is enabled, set the `prefersEphemeralWebBrowserSession` flag to true.
     private var experiment: String?
 
     /// Used for analytics purposes, to determine if browser-presentation event is associated with a locally cached, or remotely fetched `BTConfiguration`
@@ -103,15 +103,16 @@ import BraintreeDataCollector
     /// - Parameters:
     ///   - apiClient: The API Client
     ///   - universalLink: The URL to use for the PayPal app switch flow. Must be a valid HTTPS URL dedicated to Braintree app switch returns. This URL must be allow-listed in your Braintree Control Panel.
+    ///   - fallbackURLScheme: Optional: A custom URL scheme to use as a fallback if the universal link fails. This scheme must be registered in your app's Info.plist and allow-listed in the Braintree Control Panel.
     /// - Warning: This initializer should be used for merchants using the PayPal App Switch flow. This feature is currently in beta and may change or be removed in future releases.
-    @objc(initWithAPIClient:universalLink:fallbackUrlScheme:)
-    public convenience init(apiClient: BTAPIClient, universalLink: URL, fallbackUrlScheme: String? = nil) {
+    @objc(initWithAPIClient:universalLink:fallbackURLScheme:)
+    public convenience init(apiClient: BTAPIClient, universalLink: URL, fallbackURLScheme: String? = nil) {
         self.init(apiClient: apiClient)
 
         /// appending a PayPal app switch specific path to verify we are in the correct flow when
         /// `canHandleReturnURL` is called
         self.universalLink = universalLink.appendingPathComponent("braintreeAppSwitchPayPal")
-        self.fallbackUrlScheme = fallbackUrlScheme
+        self.fallbackURLScheme = fallbackURLScheme
     }
 
     // MARK: - Public Methods
@@ -461,7 +462,7 @@ import BraintreeDataCollector
                 parameters: request.parameters(
                     with: configuration,
                     universalLink: self.universalLink,
-                    fallbackUrlScheme: self.fallbackUrlScheme,
+                    fallbackURLScheme: self.fallbackURLScheme,
                     isPayPalAppInstalled: self.application.isPayPalAppInstalled()
                 )
             ) { body, _, error in
@@ -769,6 +770,6 @@ extension BTPayPalClient: BTAppContextSwitchClient {
     /// :nodoc:
     @_documentation(visibility: private)
     @objc public static func canHandleReturnURL(_ url: URL) -> Bool {
-        BTPayPalReturnURL.isValid(url, fallbackUrlScheme: payPalClient?.fallbackUrlScheme)
+        BTPayPalReturnURL.isValid(url, fallbackURLScheme: payPalClient?.fallbackURLScheme)
     }
 }

Sources/BraintreePayPal/BTPayPalRequest.swift

@@ -181,7 +181,7 @@ import BraintreeCore
     public func parameters(
         with configuration: BTConfiguration,
         universalLink: URL? = nil,
-        fallbackUrlScheme: String? = nil,
+        fallbackURLScheme: String? = nil,
         isPayPalAppInstalled: Bool = false
     ) -> [String: Any] {
         var experienceProfile: [String: Any] = [:]
@@ -243,15 +243,12 @@ import BraintreeCore
         }
 
         if let universalLink, enablePayPalAppSwitch, isPayPalAppInstalled {
-            var appSwitchParameters: [String: Any] = [
+            let appSwitchParameters: [String: Any] = [
                 "launch_paypal_app": enablePayPalAppSwitch,
                 "os_version": UIDevice.current.systemVersion,
                 "os_type": UIDevice.current.systemName,
                 "merchant_app_return_url": universalLink.absoluteString
             ]
-            if let fallbackUrlScheme {
-                appSwitchParameters["fallback_url_scheme"] = fallbackUrlScheme
-            }
 
             return parameters.merging(appSwitchParameters) { $1 }
         }

Sources/BraintreePayPal/BTPayPalReturnURL.swift

@@ -36,15 +36,23 @@ struct BTPayPalReturnURL {
     // MARK: - Static Methods
 
     /// Evaluates whether the url represents a valid PayPal return URL.
-    /// - Parameter url: an app switch or ASWebAuthenticationSession return URL
+    /// - Parameters:
+    ///   - url: an app switch or ASWebAuthenticationSession return URL
+    ///   - fallbackURLScheme: Optional fallback URL scheme to check against if universal link check fails
     /// - Returns: `true` if the url represents a valid PayPal app switch return
-    static func isValid(_ url: URL, fallbackUrlScheme: String?) -> Bool {
-        let isValidScheme = url.scheme == "https" || url.scheme == fallbackUrlScheme
+    static func isValid(_ url: URL, fallbackURLScheme: String? = nil) -> Bool {
+        let containsExpectedAction = url.path.contains("cancel") || url.path.contains("success")
         let containsAppSwitchPath = url.path.contains("braintreeAppSwitchPayPal")
-        let containsExpectedPath = url.path.contains("cancel") || url.path.contains("success")
-        let isValidAppSwitchURL = isValidScheme && containsAppSwitchPath && containsExpectedPath
 
-        return isValidAppSwitchURL
+        // Check for valid HTTPS universal link
+        let isHTTPSScheme = url.scheme == "https"
+        let isValidUniversalLink = isHTTPSScheme && containsAppSwitchPath && containsExpectedAction
+        
+        // Check for valid fallback URL scheme
+        let isFallbackScheme = fallbackURLScheme != nil && url.scheme == fallbackURLScheme
+        let isValidFallbackURL = isFallbackScheme && containsAppSwitchPath && containsExpectedAction
+        
+        return isValidUniversalLink || isValidFallbackURL
     }
 
     static func isValidURLAction(url: URL, didPayPalServerAttemptAppSwitch: Bool) -> Bool {

Sources/BraintreePayPal/BTPayPalVaultBaseRequest.swift

@@ -44,10 +44,15 @@ import BraintreeCore
     public override func parameters(
         with configuration: BTConfiguration,
         universalLink: URL? = nil,
-        fallbackUrlScheme: String? = nil,
+        fallbackURLScheme: String? = nil,
         isPayPalAppInstalled: Bool = false
     ) -> [String: Any] {
-        let baseParameters = super.parameters(with: configuration, universalLink: universalLink, isPayPalAppInstalled: isPayPalAppInstalled)
+        let baseParameters = super.parameters(
+            with: configuration,
+            universalLink: universalLink,
+            fallbackURLScheme: fallbackURLScheme,
+            isPayPalAppInstalled: isPayPalAppInstalled
+        )
         var vaultParameters: [String: Any] = ["offer_paypal_credit": offerCredit]
 
         if let billingAgreementDescription {
@@ -67,6 +72,10 @@ import BraintreeCore
 
             vaultParameters["shipping_address"] = shippingAddressParameters
         }
+        
+        if let fallbackURLScheme {
+            vaultParameters["merchant_app_fallback_url_scheme"] = fallbackURLScheme
+        }
 
         return baseParameters.merging(vaultParameters) { $1 }
     }

Sources/BraintreePayPal/BTPayPalVaultRequest.swift

@@ -54,13 +54,13 @@ import BraintreeCore
     public override func parameters(
         with configuration: BTConfiguration,
         universalLink: URL? = nil,
-        fallbackUrlScheme: String? = nil,
+        fallbackURLScheme: String? = nil,
         isPayPalAppInstalled: Bool = false
     ) -> [String: Any] {
         super.parameters(
             with: configuration,
             universalLink: universalLink,
-            fallbackUrlScheme: fallbackUrlScheme,
+            fallbackURLScheme: fallbackURLScheme,
             isPayPalAppInstalled: isPayPalAppInstalled
         )
     }

UnitTests/BraintreePayPalTests/BTPayPalCheckoutRequest_Tests.swift

@@ -276,7 +276,7 @@ class BTPayPalCheckoutRequest_Tests: XCTestCase {
     func testParametersWithConfiguration_setsAppSwitchParameters_WithoutUserAuthenticationEmail() {
         let request = BTPayPalCheckoutRequest(enablePayPalAppSwitch: true, amount: "1")
 
-        let parameters = request.parameters(with: configuration, universalLink: URL(string: "some-url")!, isPayPalAppInstalled: true)
+        let parameters = request.parameters(with: configuration, universalLink: URL(string: "some-url")!, fallbackURLScheme: "paypal", isPayPalAppInstalled: true)
 
         XCTAssertNil(parameters["payer_email"])
         XCTAssertEqual(parameters["launch_paypal_app"] as? Bool, true)

UnitTests/BraintreePayPalTests/BTPayPalClient_Tests.swift

@@ -20,7 +20,7 @@ class BTPayPalClient_Tests: XCTestCase {
         mockAPIClient.cannedResponseBody = BTJSON(value: [
             "paymentResource": ["redirectUrl": "http://fakeURL.com"]
         ])
-        payPalClient = BTPayPalClient(apiClient: mockAPIClient, universalLink: URL(string: "https://www.paypal.com")!, fallbackUrlScheme: "paypal")
+        payPalClient = BTPayPalClient(apiClient: mockAPIClient, universalLink: URL(string: "https://www.paypal.com")!, fallbackURLScheme: "paypal")
         mockWebAuthenticationSession = MockWebAuthenticationSession()
         payPalClient.webAuthenticationSession = mockWebAuthenticationSession
     }
@@ -840,20 +840,20 @@ class BTPayPalClient_Tests: XCTestCase {
         XCTAssertNil(BTPayPalClient.payPalClient)
     }
 
-    func testHandleReturnURL_whenFallBack_withPath() {
-        let url = URL(string: "paypal://path")!
+    func testHandleReturnURL_withFallBack() {
+        let url = URL(string: "paypal://braintree-payments/braintreeAppSwitchPayPal/success")!
         BTPayPalClient.payPalClient = self.payPalClient
         XCTAssertTrue(BTPayPalClient.canHandleReturnURL(url))
     }
 
-    func testHandleReturnURL_whenFallBack_withoutPath() {
-        let url = URL(string: "paypal://")!
+    func testHandleReturnURL_withFallBack_noSuccess() {
+        let url = URL(string: "paypal://braintree-payment/braintreeAppSwitchPayPal")!
         BTPayPalClient.payPalClient = self.payPalClient
-        XCTAssertTrue(BTPayPalClient.canHandleReturnURL(url))
+        XCTAssertFalse(BTPayPalClient.canHandleReturnURL(url))
     }
-    
+
     func testHandleReturnURL_whenFallBack_wrongScheme() {
-        let url = URL(string: "palpay://")!
+        let url = URL(string: "incorrect-scheme://braintree-payment/braintreeAppSwitchPayPal/success")!
         BTPayPalClient.payPalClient = self.payPalClient
         XCTAssertFalse(BTPayPalClient.canHandleReturnURL(url))
     }