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 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™
  • Select or add shipping addresses in the PayPal account
  • Select or add funding instruments in the PayPal account
  • 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)

Invoking the Vault flow

Make sure you have registered your URL type and updated your app delegate. Then, use BTPayPalDriver to start the process. An example integration might look like this:

// MyViewController.m
#import "MyViewController.h"
#import "BraintreePayPal.h"

@interface MyViewController () <BTAppSwitchDelegate, BTViewControllerPresentingDelegate>
@property (nonatomic, strong) BTAPIClient *braintreeClient;
@property (nonatomic, strong) BTPayPalDriver *payPalDriver;

@implementation MyViewController

- (void)startCheckout {
    // Example: Initialize BTAPIClient, if you haven't already
    self.braintreeClient = [[BTAPIClient alloc] initWithAuthorization:@"<#CLIENT_AUTHORIZATION#>"];
    BTPayPalDriver *payPalDriver = [[BTPayPalDriver alloc] initWithAPIClient:self.braintreeClient];
    payPalDriver.viewControllerPresentingDelegate = self;
    payPalDriver.appSwitchDelegate = self; // Optional

    BTPayPalRequest *checkout = [[BTPayPalRequest alloc] init];
    checkout.billingAgreementDescription = @"Your agreement description";
    [driver requestBillingAgreement:checkout completion:^(BTPayPalAccountNonce * _Nullable tokenizedPayPalCheckout, NSError * _Nullable error) {
        if (error) {
        } else if (tokenizedPayPalCheckout) {
        } else {


Finally, don't forget to implement the delegate protocols.

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.

PayPalDataCollector collects data about a customer's device and returns a device_data string that contains one or more identifiers that correlate with the collected data. You can include this device_data when creating a transaction on your server.

  1. Before making a request from your server, call the data collection method:

    #import "PPDataCollector.h"
    NSString *deviceData = [PPDataCollector collectPayPalDeviceData];
    NSLog(@"Send this device data to your server: %@", deviceData);
  2. Send the returned string to your server along with transaction data. Your server should include this device_data when submitting the request to the Braintree gateway.

Shipping address

Shipping addresses may or may not be 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

PayPal is available to merchants in all countries that we support and to customers in 140+ countries.

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.

Next Page: Server-side →