Migrating from v3 to v4

We recently made updates to our root SSL provider that require you to use at a minimum v4.10.0 of the iOS SDK.

We've made some big improvements to the Braintree iOS SDK in version 4.0.

Because the Braintree iOS SDK follows Semantic Versioning, version 4.0 contains API and architectural changes that require updates when upgrading from 3.x.

We believe this release will simplify your integration and provide more flexibility.

Why upgrade to v4?

  • Slimmer SDK size: integrate only the payment options you use
  • Use PayPal One Touch™ to accept PayPal payments by switching to the mobile browser. If the app/browser has an active session, then login is not required.
    • One Touch™ provides a Checkout flow for accepting one-time payments via PayPal
  • More ways to integrate: Carthage, static library (coming soon)
  • Block-based APIs
  • Nullability annotation for improved Swift interoperability

Minimum requirements: iOS 8, iOS SDK 9.0, Xcode 10

The Braintree iOS SDK requires Xcode 10+ and a base SDK of iOS 9.0+. It permits a deployment target of iOS 8 and above.


We now support installation via CocoaPods, Carthage, and manual integration.

The Getting Started section of the README has more information.

Setup and initialization

The setup and initialization of the SDK has changed slightly. The Braintree class has been replaced by BTAPIClient:

#import "BraintreeCore.h"

BTAPIClient *apiClient = [[BTAPIClient alloc] initWithAuthorization:@"<#CLIENT_AUTHORIZATION#>"];

Client authorization for BTAPIClient can be achieved using a client token or tokenization key.

Supporting app switch

If your app accepts payments via PayPal, then you must set up your app to handle app switching.

Accepting payments

Previously in 3.x, BTPaymentProvider was a centralized provider of BTPaymentMethod objects for each payment option. In 4.0, this has been re-architected so that each payment option has its own class responsible for tokenizing payment methods.

These classes are called drivers when they involve some UI interaction, or clients when they are headless:

Payment option Class
Cards BTCardClient
PayPal BTPayPalDriver
Apple Pay BTApplePayClient
3D Secure BTThreeDSecureDriver

Payment option clients and drivers use block-based APIs to return BTPaymentMethodNonce instances that have a nonce property.

Drivers have a required viewControllerPresentingDelegate property, which should be set to your view controller, which is responsible for modally presenting and dismissing the view controllers required to finalize payments.

See each class's header file for more information.

Other changes

Tokenization keys

BTAPIClient can also be initialized with a tokenization key, which is a static Braintree API key that is specified at compile-time. Tokenization keys support a subset of the client token's capabilities, but they have the advantage of allowing you to start interacting with our services without the overhead of a network call to generate a client token.

Project reorganization

The components of the Braintree iOS SDK have been renamed, and each component has an umbrella header that imports the publicly available classes for that component:

Component Header Import
Core #import "BraintreeCore.h"
Cards #import "BraintreeCard.h"
PayPal #import "BraintreePayPal.h"
Apple Pay #import "BraintreeApplePay.h"
UI #import "BraintreeUI.h"
3D Secure #import "Braintree3DSecure.h"
Data Collector #import "BraintreeDataCollector.h"

Credit and debit card

  • BTClientCardTokenizationRequest has been replaced with BTCard
  • BTClientCardRequest's functionality has been squashed into BTCard


  • Use BTPayPalDriver to initiate PayPal payment flows.
  • Braintree-PayPal.h has been replaced with BraintreePayPal.h


  • Braintree-Payments-UI.h has been replaced with BraintreeUI.h
  • BTPaymentButton
    • Uses a block-based API instead of a delegate to return payment method nonces
    • paymentProviderTypes has been replaced with the enabledPaymentOptions property

Anti-fraud changes

  • Data has been renamed to DataCollector. For example, if you have pod 'Braintree/Data' in your Podfile, rename it to pod 'Braintree/DataCollector'.