Client SDK

Setupanchor

important

The SSL certificates for all Braintree SDKs are set to expire by June 30, 2025. This will impact existing versions of the SDK in published versions of your app. To reduce the impact, upgrade the iOS SDK to version 6.17.0+ for the new SSL certifications.

If you do not decommission your app versions that include the older SDK versions or force upgrade your app with the updated certificates by the expiration date, 100% of your customer traffic will fail.

The Braintree iOS SDK helps you accept payments in your iOS app.

Requirementsanchor

  • Xcode 12+
  • A minimum deployment target of iOS 12.0
  • Swift 5.1+ (or Objective-C)

It goes without saying, but we’ll say it anyway: we always recommend using the latest versions of our SDKs. In order to communicate securely with the Braintree gateway, you must use at least version 4.10.0 of the iOS SDK.

note

Our iOS SDK and its frameworks follow semantic versioning. When updating your integration, be sure to update each framework to the latest version.

Installationanchor

There are multiple ways to include Braintree in your project. See the Installation section of our README.

Setup for app context switchinganchor

To handle workflows that involve switching to another app or SFSafariViewController for authentication, you must register a URL type and configure your app to handle return URLs.

Register a URL typeanchor

  1. In Xcode, click on your project in the Project Navigator and navigate to App Target > Info > URL Types
  2. Click [+] to add a new URL type
  3. Under URL Schemes, enter your app switch return URL scheme. This scheme must start with your app's Bundle ID and be dedicated to Braintree app switch returns. For example, if the app bundle ID is com.your-company.your-app, then your URL scheme could be com.your-company.your-app.payments.
important

If you have multiple app targets, be sure to add the return URL type for all of the targets.

Testing the URL typeanchor

You can test out your new URL scheme by opening up a URL that starts with it (e.g. com.your-company.your-app.payments://test) in Mobile Safari on your iOS Device or Simulator.

In addition, always test your app switching on a real device.

Set your return URLanchor

In your AppDelegate's application:didFinishLaunchingWithOptions: implementation, use setReturnURLScheme: with the value you set above.

For example:

  1. Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BTAppContextSwitcher.setReturnURLScheme("com.your-company.your-app.payments")
    return true
}

Handle app context switchinganchor

Then pass the payment authorization URL to Braintree for finalization.

If you're using UISceneDelegate (introduced in iOS 13), call BTAppContextSwitcher's handleOpenURLContext method from within the scene:openURLContexts scene delegate method.

  1. Swift
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    URLContexts.forEach { context in
        if context.url.scheme?.localizedCaseInsensitiveCompare("com.your-company.your-app.payments") == .orderedSame {
            BTAppContextSwitcher.handleOpenURLContext(context)
        }
    }
}

Otherwise, if you aren't using UISceneDelegate, call BTAppContextSwitcher's handleOpenURL method from within the application:openURL:options app delegate method.

  1. Swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if url.scheme?.localizedCaseInsensitiveCompare("com.your-company.your-app.payments") == .orderedSame {
        return BTAppContextSwitcher.handleOpenURL(url)
    }
    return false
}

Location Permissionsanchor

The Braintree iOS SDK uses device and browser location data for fraud detection when available (i.e. when location permissions have already been requested by your app and granted by the user). While you do not need to request location data from users in order to use Braintree, Apple requires a NSLocationWhenInUseUsageDescription key in your Info.plist if your app contains code referencing location APIs. If your app does not request location data, you will still need to include a NSLocationWhenInUseUsageDescription plist entry.

See also