PayPal

Vaulted Paymentsanchor

Vaulted payments with PayPal account will allow you to charge the account in the future without requiring your customer to be present during the transaction or re-authenticate with PayPal when they are present during the transaction.

The Vault is used to process payments with our recurring billing feature, and is also used for non-recurring transactions so that your customers don't need to re-enter their information each time they make a purchase from you.

Vaulted payments with PayPal account allows you to charge the account in the future without requiring your customer’s presence during the transaction.

The vaulted payment flow lets the user:

  • 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)

vault-flow

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 flowanchor

Enable the Vault flow by leaving out the singleUse client option or setting it to false, as seen below.

An integration with our Vault would typically be used in conjunction with your PayPal Checkout flow. An example checkout page for the Vault flow might look like this:

  1. HTML
<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <form id="merchant-form" action="/create-transaction" method="post">
      <div id="paypal-container"></div>
      <input type="submit" value="Submit" />
    </form>
    <script src="https://js.braintreegateway.com/js/braintree-3.111.0.min.js"></script>
    <script type="text/javascript">
     braintree.setup("CLIENT-TOKEN-FROM-SERVER", "custom", {
        paypal: {
          container: "paypal-container",
          singleUse: false,
          billingAgreementDescription: 'Your agreement description',
          locale: 'en_US',
          enableShippingAddress: true,
          shippingAddressOverride: {
            recipientName: 'Scruff McGruff',
            streetAddress: '1234 Main St.',
            extendedAddress: 'Unit 1',
            locality: 'Chicago',
            countryCodeAlpha2: 'US',
            postalCode: '60652',
            region: 'IL',
            phone: '123.456.7890',
            editable: false
          }
        },
        dataCollector: true,
        onPaymentMethodReceived: function (obj) {
          doSomethingWithTheNonce(obj.nonce);
        }
      });
      </script>
    </body>
  </html>

Once the customer completes the consent flow and the PayPal pop-up closes, the onPaymentMethodReceived, callback is returned with the tokenization result. This includes a nonce which can then be used in your Transaction.Sale call to Braintree.

availability

This feature requires version 2.16.0 or higher of the JavaScript SDK. We recommend using the latest release (v2.32.1).

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, you will need to pass some additional dataCollector options to your braintree.setup call.

  1. HTML
<script type="text/javascript">
  braintree.setup('TOKEN', 'custom', {
    paypal: {
      container: 'paypal-container',
      singleUse: false,
    },
    dataCollector: true,
    onPaymentMethodReceived: function (obj) {
      doSomethingWithTheNonce(obj.nonce);
    }
  });
</script>

The braintreeInstance returned by onReady will have an additional deviceData string value. It is up to you to provide this value as the device_data option to your server. The most common mechanism for this is to inject the device_data value into your form as a hidden input inside of your onReady callback.

  1. JavaScript
braintree.setup(TOKEN, 'custom', {
  dataCollector: true,
  onReady: function (braintreeInstance) {
    var form = document.getElementById('my-form-id');
    var deviceDataInput = form['device_data'];

    if (deviceDataInput == null) {
      deviceDataInput = document.createElement('input');
      deviceDataInput.name = 'device_data';
      deviceDataInput.type = 'hidden';
      form.appendChild(deviceDataInput);
    }

    deviceDataInput.value = braintreeInstance.deviceData;
  }
  /* ... */
});

Shipping addressanchor

Shipping addresses 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 supportanchor

PayPal is available to merchants in all countries that we support and to customers in 140+ countries. Ensure you are using a desired locale code as outlined in our JavaScript PayPal client reference.

Currency presentmentanchor

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.