Overview

1. To allow your app to detect and switch to the PayPal app, add the PayPal URL scheme to the LSApplicationQueriesSchemes allowlist in your app’s Info.plist:
2. When creating a PayPal request, set enablePayPalAppSwitch to true. App Switch is triggered during tokenization if the PayPal app is installed and the buyer meets eligibility requirements. Include the buyer’s email address and phone number when available to personalize buyer’s experience and improve authentication and approval success rates. Use the request with BTPayPalClient.tokenize(_:completion:)
.

Vaulted Payments

import UIKit
import BraintreePayPal

class VaultedPaymentViewController: UIViewController {
    var apiClient: BTAPIClient!
    var payPalClient: BTPayPalClient!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        apiClient = BTAPIClient(authorization: "<#CLIENT_AUTHORIZATION#>")
        payPalClient = BTPayPalClient(
            apiClient: apiClient,
            universalLink: URL(string: "https://my-universal-link.com/braintree-payments")!
        )
    }
    private func payPalButtonTapped() {
    // vault flows
    let request = BTPayPalVaultRequest(
      enablePayPalAppSwitch: true,
      userAuthenticationEmail: "buyer@email.com",
      userPhoneNumber: BTPayPalPhoneNumber(
          countryCode: "1",
          nationalNumber: "2223334444"
      )
    )
    
    // enablePayPalAppSwitch are required for this flow
    // Configure other values on 'request' as needed.

    payPalClient.tokenize(request) { payPalNonce, error in
      if let payPalNonce { 
        // send payPalNonce.nonce to server 
      } else { 
        // handle error
      }
    }
  }
}

Best practices

These best practices are important to ensure optimal user experience and improved conversion

1. Show a loading indicator after PayPal button click
When the user taps the PayPal button:
• Immediately disable the PayPal button to prevent duplicate submissions.
• Show a loading indicator while the network request is in progress.
This prevents accidental double taps and clearly communicates that the checkout flow is in progress.
2. Provide buyer email and phone number
Although optional, providing the buyer’s email address and phone number whenever available is strongly recommended. Passing this information allows PayPal to:
• Personalize the buyer experience.
• Improve risk assessment.
• Optimize approval rates.
This often results in higher overall conversion.
Phone number formatting requirements

When passing a phone number, ensure it is sanitized into its canonical format:

• countryCode must contain numeric digits only (do not include a + prefix).
• nationalNumber must include digits only.
• Remove spaces, hyphens, parentheses, and other formatting characters.
• Do not include the country code in the national number.
• Do not include leading zeros unless they are part of the actual national number.
Example:
Copy

userPhoneNumber: BTPayPalPhoneNumber(
          countryCode: "1",
          nationalNumber: "2223334444"
    )

3. Handling return to your app
When the buyer returns to your app (either automatically or manually):
• Remove the loading indicator immediately when your app returns to the foreground.
• Allow the buyer to continue from where they left off, especially if they exited the PayPal app without approving or canceling the transaction (for example, by backgrounding the PayPal app).
When the SDK callback returns a nonce (indicating the buyer approved the transaction):
• Disable the PayPal button again.
• Display a loading indicator or overlay while finalizing the vault or transaction.
• Continue processing until completion.

You may optionally implement a timeout (for example, 10 seconds) for the loading indicator in case processing takes longer than expected.

This ensures UI consistency and prevents unintended user interactions during payment finalization.

4. Redirection to mobile browser
In some cases, after approving the transaction in the PayPal app, the OS may redirect the buyer to your website in the default mobile browser instead of returning to your app, even when return and cancel URLs are configured. This typically occurs when:
• The universal link configuration on the device does not match the registered domain, or
• The app cannot properly claim the universal link.

Recommended mitigations:

• Ensure universal links are correctly configured and associated with the domain.
• (Optional but recommended) Implement fallback logic on your website to:
  • Detect redirected buyers.
  • Retrieve or confirm the final token or payment status.
  • Guide the buyer back to the correct in-app flow when possible.

Testing and Go Live

For detailed testing procedures and production deployment guidance, see the Testing and Go Live section.