Client SDK

Migration

Migrating from v4 to v5

While iOS v5 is a major version bump and contains breaking changes, we kept these changes to a minimum. In fact, depending how you are integrating with the Braintree iOS SDK, you may not experience any breaking changes.

Why upgrade to v5?

Support for Swift Package Manager
Simplified Pay with PayPal integration
Updates for the latest versions of iOS and Xcode

Minimum requirements

The Braintree iOS v5 SDK requires Xcode 12+, Swift 5.1+ and a minimum deployment target of iOS 12.0.

If your application contains Objective-C code, the Enable Modules build setting must be set to YES.

Installation

iOS v5 supports installation via Swift Package Manager, CocoaPods and Carthage.

The Installation section of the README has more information.

Additional instructions for SPM

We recommend using the latest version for the simplest SPM integration. If using Braintree 5.4.1 and below, see our GitHub repo's Swift Package Manager guide for specific workarounds required to use these older versions.

Required code changes

App context switching

v5 renames the BTAppSwitch class to BTAppContextSwitcher to clarify that it is used for flows that require switching contexts, either by opening an SFSafariViewController or by opening a different app (specifically, Venmo).

BTAppSwitchDelegate was removed in v5. If you were using these delegate methods to determine when control switched between your app and the Venmo app, we recommend using app or scene delegate methods instead. If you were using BTAppSwitchDelegate to determine when an SFSafariViewController was presented or dismissed, we recommend using the BTViewControllerPresentingDelegate methods instead.

Swift

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

If you're using UISceneDelegate, use the following code to pass a return URL to BTAppContextSwitcher:

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(urlContext)
    }
  }
}

If you aren't using UISceneDelegate, you will need to update the handleOpenURL method you call from within the application:OpenURL:options app delegate method. Note that v5 removes the options and sourceApplication params from BTAppContextSwitcher methods.

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
}

Apple Pay

For CocoaPods integrations, the Braintree Apple Pay subspec has been renamed from Braintree/Apple-Pay to Braintree/ApplePay.

Card

v5 removes the initWithParameters and initWithNumber initializers from BTCard. To construct a BTCard, set the properties directly:

Swift

let card = BTCard()
card.number = "4111111111111111"
card.expirationMonth = "12"
card.expirationYear = "2025"
card.cvv = "123"

Data Collector

v5 removes the BTDataCollector.collectCardFraudData() method. You should instead use BTDataCollector.collectDeviceData() which will collect Fraud Protection Advanced data if your merchant account is properly setup for a Fraud Protection Advanced integration.

v5 also removes the BTDataCollectorDelegate. You should call collectDeviceData() as early as possible, e.g. at app launch. If that's too early, calling it when the customer initiates checkout is also fine.

PayPal

Custom URL scheme

Registering a custom URL scheme in your Xcode project is no longer required for the PayPal flow.

Code previously used to set your return URL scheme can be deleted.

note
Other payment methods (e.g. Venmo, Local Payment Methods, 3DS) still require a custom URL scheme.

Swift

// This line is no longer required for Pay with PayPal flows
BTAppSwitch.setReturnURLScheme("com.your-company.your-app.payments")

PayPal request

v5 introduces two subclasses of BTPayPalRequest:

BTPayPalCheckoutRequest, for Checkout flows
BTPayPalVaultRequest, for Vault flows.

The requestOneTimePayment and requestBillingAgreement methods on BTPayPalDriver have been updated to expect instances of BTPayPalCheckoutRequest and BTPayPalVaultRequest, respectively.

However, requestOneTimePayment and requestBillingAgreement have been deprecated in favor of tokenizePayPalAccount:

Swift

let request = BTPayPalCheckoutRequest(amount: "10.00")
payPalDriver.tokenizePayPalAccount(with: request) { nonce, error in
  // handle errors or send nonce to server to transact
}

If your app supports multi-tasking, you must set the BTPayPalRequest.activeWindow property to ensure that the PayPal flow launches from the correct window.

The offerCredit property has been removed in favor of offerPayLater.

Other changes

Implementing the BTViewControllerPresentingDelegate is no longer required for the PayPal flow.

Venmo

The authorizeAccount methods on BTVenmoDriver have been replaced with a tokenizeVenmoAccount method.

Swift

let venmoRequest = BTVenmoRequest()
venmoRequest.profileID = "my-profile-id"
venmoRequest.vault = true

venmoDriver.tokenizeVenmoAccount(with: venmoRequest) { (venmoAccountNonce, error) -> Void in
  if (error != nil) {
    // handle error
  }

  // transact with nonce on server
}

3D Secure

In v4, 3D Secure classes were housed in the BraintreePaymentFlow module. In v5, BraintreeThreeDSecure is a standalone module offering the same 3DS functionality. The BraintreePaymentFlow module still houses Local Payment functionality.

CocoaPods

In your Podfile, add:

Ruby

pod `Braintree/ThreeDSecure`

Carthage

important
Long term support for Carthage is not guaranteed. Please update to SPM, if possible. Open a GitHub issue if there are concerns.

You will need to add the BraintreeThreeDSecure framework to your project. See the Carthage docs for integration instructions.

Swift Package Manager

If you're using v5.3.0 or above, include BraintreeThreeDSecure, CardinalMobile and PPRiskMagnes. See the GitHub repo's Swift Package Manager guide for instructions for versions 5.0.0 to 5.2.0.

BTThreeDSecureRequestDelegate

The signature for the BTThreeDSecureRequestDelegate method onLookupComplete has changed:

Swift

public func onLookupComplete(_ request: BTThreeDSecureRequest, lookupResult result: BTThreeDSecureResult, next: @escaping () -> Void) {
    // Optionally inspect the result and prepare UI if a challenge is required
    next()
}

The lookup information, such as requiresUserAuthentication, can be found on the result's lookup property:

Swift

result.lookup?.requiresUserAuthentication

3DS2 UI customization

On BTThreeDSecureRequest, the uiCustomization property was replaced with v2UICustomization of type BTThreeDSecureV2UICustomization. For 3DS2 UI customization, use the following new classes:

BTThreeDSecureV2UICustomization
BTThreeDSecureV2ButtonCustomization
BTThreeDSecureV2LabelCustomization
BTThreeDSecureV2TextBoxCustomization
BTThreeDSecureV2ToolbarCustomization

Default 3DS version

Previously, the versionRequested property on BTThreeDSecureRequest defaulted to .version1. It now defaults to .version2.

Shipping method

The shippingMethod property on BTThreeDSecureRequest is now an enum rather than a string. Possible values:

.sameDay
.expedited
.priority
.ground
.electronicDelivery
.shipToStore

Available frameworks

The following frameworks are available in Braintree iOS v5:

BraintreeAmericanExpress
BraintreeApplePay
BraintreeCard
BraintreeCore
BraintreeDataCollector
BraintreePayPal
BraintreePaymentFlow
BraintreeThreeDSecure
BraintreeVenmo
PayPalDataCollector