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 to you in your onPaymentMethodNonceCreated. 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™
  • 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

First, make sure you have defined your URL scheme. Next, use PayPal#requestBillingAgreement. An example integration might look like this:

Java
public void startBillingAgreement() {
  PayPalRequest request = new PayPalRequest()
    .localeCode("US")
    .billingAgreementDescription("Your agreement description");

  PayPal.requestBillingAgreement(mBraintreeFragment, request);
}

When you receive a callback to onPaymentMethodNonceCreated, you can query the PayPalAccountNonce object you get back for specific customer information.

Java
public void onPaymentMethodNonceCreated(PaymentMethodNonce paymentMethodNonce) {
  // Send nonce to server
  String nonce = paymentMethodNonce.getNonce();
  if (paymentMethodNonce instanceof PayPalAccountNonce) {
    PayPalAccountNonce paypalAccountNonce = (PayPalAccountNonce) paymentMethodNonce;

    // Access additional information
    String email = paypalAccountNonce.getEmail();
    String firstName = paypalAccountNonce.getFirstName();
    String lastName = paypalAccountNonce.getLastName();
    String phone = paypalAccountNonce.getPhone();

    // See PostalAddress.java for details
    PostalAddress billingAddress = paypalAccountNonce.getBillingAddress();
    PostalAddress shippingAddress = paypalAccountNonce.getShippingAddress();
  }
}

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.

DataCollector enables you to collect data about a customer's device and correlate it with a session identifier on your server.

Initializing

Drop-in

  1. Create a DropInRequest with a tokenization key or client token from your server.

    Java
    DropInRequest dropInRequest = new DropInRequest()
     .clientToken(clientToken);
  2. Specify true for the device data collection option.

    Java
    dropInRequest.collectDeviceData(true);
  3. Start the Drop-in activity.

    Java
    startActivityForResult(dropInRequest.getIntent(this), REQUEST_CODE);
  4. Send the device data string response from Drop-in to your server to be included in verification or transaction requests.

    Java
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
     if (requestCode == REQUEST_CODE) {
       if (resultCode == RESULT_OK) {
         DropInResult result = data.getParcelableExtra(DropInResult.EXTRA_DROP_IN_RESULT);
         String deviceData = result.getDeviceData();
       }
     }
    }

Custom

  1. Initialize a BraintreeFragment with a tokenization key or a client token from your server.

  2. When verifying a card or creating a transaction call DataCollector#collectDeviceData.

    Java
    DataCollector.collectDeviceData(braintreeFragment, new BraintreeResponseListener<String> {
     @Override
     public onResponse(String deviceData) {
       // send deviceData to your server
     }
    });
  3. Send the string response from DataCollector#collectDeviceData to your server to be included in verification or transaction requests.

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.

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 →