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

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


The examples on this page now use the PayPal Checkout component released in version 3.7.0 of the Braintree JavaScript SDK. Documentation and examples for the deprecated PayPal component are available in the JavaScript reference.

With this change, you must link your PayPal sandbox test account to your Braintree sandbox account for testing.

An integration with our Vault would typically be used in conjunction with your standard checkout flow. The only difference is the options you provide when tokenizing with the PayPal Checkout component.

Enable the Vault flow by setting the flow option to 'vault':

// Be sure to have PayPal's checkout.js library loaded on your page.
// <script src="" data-version-4></script>

// Create a client.
}, function (clientErr, clientInstance) {

  // Stop if there was a problem creating the client.
  // This could happen if there is a network error or if the authorization
  // is invalid.
  if (clientErr) {
    console.error('Error creating client:', clientErr);

  // Create a PayPal Checkout component.
    client: clientInstance
  }, function (paypalCheckoutErr, paypalCheckoutInstance) {

    // Stop if there was a problem creating PayPal Checkout.
    // This could happen if there was a network error or if it's incorrectly
    // configured.
    if (paypalCheckoutErr) {
      console.error('Error creating PayPal Checkout:', paypalCheckoutErr);

    // Set up PayPal with the checkout.js library
      env: 'production', // or 'sandbox'

      payment: function () {
        return paypalCheckoutInstance.createPayment({
          flow: 'vault',
          billingAgreementDescription: 'Your agreement description',
          enableShippingAddress: true,
          shippingAddressEditable: false,
          shippingAddressOverride: {
            recipientName: 'Scruff McGruff',
            line1: '1234 Main St.',
            line2: 'Unit 1',
            city: 'Chicago',
            countryCode: 'US',
            postalCode: '60652',
            state: 'IL',
            phone: '123.456.7890'

      onAuthorize: function (data, actions) {
        return paypalCheckoutInstance.tokenizePayment(data, function (err, payload) {
          // Submit `payload.nonce` to your server.

      onCancel: function (data) {
        console.log('checkout.js payment cancelled', JSON.stringify(data, 0, 2));

      onError: function (err) {
        console.error('checkout.js error', err);
    }, '#paypal-button').then(function () {
      // The PayPal button will be rendered in an html element with the id
      // `paypal-button`. This function will be called when the PayPal button
      // is set up and ready to be used.



Use the paypalCheckoutInstance in the onAuthorize function of the PayPal checkout.js setup method to tokenize the PayPal account. After the customer completes the consent flow and the PayPal pop-up closes, successful tokenization will return a nonce.

Send the nonce to your server and use a Braintree server SDK to call PaymentMethod.create, which creates a PayPal payment method in your Vault. Alternatively, use to create a transaction.

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.

To collect device data for PayPal, use the dataCollector component. If you're using script tags to load files, make sure to include:

<script src=""></script>

You must also pass the paypal: true option to braintree.dataCollector.create. This should be done in the callback of your client.create call:

var myDeviceData;

  authorization: 'TOKEN',
}, function (err, clientInstance) {
    client: clientInstance,
    paypal: true
  }, function (err, dataCollectorInstance) {
    if (err) {
      // Handle error
    // At this point, you should access the dataCollectorInstance.deviceData value and provide it
    // to your server, e.g. by injecting it into your form as a hidden input.
    myDeviceData = dataCollectorInstance.deviceData;

  // Initialize your PayPal Checkout component here.
  braintree.paypalCheckout.create(/* ... */);

To cleanly reset your integration, call teardown() on the data object.


If you're also using our Advanced Fraud Management Tools for credit cards, you can simultaneously collect that device data by adding a kount option to your dataCollector. See the Advanced Fraud Management Tools guide for details.

Country and language support

The Vault flow is available to merchants in all countries that we support. The language in the UI will automatically adjust based on the customer's country.

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.

PayPal Credit

US and UK merchants can add PayPal Credit to a Checkout flow integration with a few additional lines of code. For full info on the availability and benefits of offering PayPal Credit, see the support article. For integration details, see the developer guide.

Next Page: Server-side →