iOS v3 is deprecated. We recommend migrating to the latest version of our iOS SDK. The best way to start is by making an incremental upgrade from v3 to v4.

Vaulting a PayPal account will allow you to charge the account in the future without requiring your customer to re-authenticate with PayPal.

When the customer completes the PayPal authentication flow, the PayPal interface closes and returns the nonce and additional PayPal data to your app. At this point in time a PayPal pre-approved payment is created between you and the customer, displayed in the customer's account profile on PayPal.com. Send the nonce to your server where it can be used to create a transaction.

The vaulted payment flow supports the following features:

  • PayPal One Touch™
  • Two factor authentication support (currently only for US, UK, CA, DE, AT, and AU)

Typical use cases for the vaulted payment flow:

  • Faster payments for repeat customers
  • Subscriptions
  • Recurring billing (e.g. automatic top-up or usage based charges)

Collecting device data

Collecting device data from your customers is required when initiating non-recurring transactions from Vault records. Collecting and passing this data with transactions will help reduce decline rates.

Braintree Data enables you to collect data about a customer's device and include it when creating a transaction or verification on your server. For more information, refer to the iOS header file for BTData.

  1. Add the Braintree/Data subspec to your Podfile. For example:

    pod 'Braintree', '~> 3.9'
    pod 'Braintree/Data', '~> 3.9'
  2. In your app, initialize BTData using initWithClient: for your environment, e.g. sandbox:

    #import "Braintree.h"
    #import "BTData.h"
    // ...
    // Retain your `BTData` instance for your entire application lifecycle.
    @property (nonatomic, strong) BTData *data;
    // ...
    // Example. You should use your existing Braintree or BTClient object.
    // If YOUR_CLIENT_TOKEN is invalid, `braintree.client` and
    // the subsequent `self.data` object will be nil.
    Braintree *braintree = [Braintree braintreeWithClientToken:YOUR_CLIENT_TOKEN];
    BTClient *client = braintree.client;
    self.data = [[BTData alloc] initWithClient:client environment:BTDataEnvironmentSandbox];
  3. Optionally, set a delegate to receive lifecycle notifications.
  4. Before submitting a transaction from your server, call collectDeviceData:
    NSString *deviceData = [self.data collectDeviceData];
    NSLog(@"Send this device data to your server: %@", deviceData);
  5. Send the returned string to your server along with transaction data to be included with the request to the Braintree gateway.

Shipping address

Shipping addresses are not collected during the PayPal Vault flow. However, if you choose to collect shipping addresses yourself, it can be passed along with the server side Transaction.Sale call. Look at the Server-side page for more information.

Country and language support

Below are the supported language and country combinations. We auto-detect your customer's location when using the Vault flow on a mobile device.

Country Language
Andorra Spanish
Andorra English
Australia English
Austria German
Austria English
Belgium English
Belgium Dutch
Belgium French
Bulgaria English
Canada English
Canada French
Croatia English
Cyprus English
Czech Republic English
Denmark Danish
Denmark English
Estonia English
Finland English
France French
France English
Germany German
Germany English
Gibraltar English
Great Britain English
Greece English
Hong Kong English
Hong Kong Chinese
Hungary English
Iceland English
Ireland English
Italy Italian
Italy English
Latvia English
Liechtenstein German
Liechtenstein English
Lithuania English
Lithuania Russian
Luxembourg English
Luxembourg German
Malta English
Malaysia English
Netherlands Dutch
Netherlands English
New Zealand English
Norway Norwegian
Norway English
Poland Polish
Poland English
Portugal English
Portugal Portuguese
Romania English
San Marino Italian
San Marino English
Singapore English
Slovakia English
Slovenia English
Spain Spanish
Spain English
Sweden Swedish
Switzerland German
Switzerland French
Switzerland English
United States English

Currency presentment

In the Vault flow itself, the transaction currency and amount are not displayed to the customer. It is up to you to display these details in your checkout flow somewhere (e.g. cart page, order review page, etc.). Our Server-Side guide outlines which currencies are supported for PayPal transactions.