Checkout with Vault

Checkout with Vault is a one-time PayPal Checkout experience that includes vaulting capabilities. It automatically creates a PayPal Billing Agreement and stores a customer's PayPal account in the Braintree Vault. You can then charge the account in the future without requiring your customer to re-authenticate with PayPal or choose a payment method again within their wallet.

Note

If you're integrating Pay Later offers, you'll need to render the Pay Later button in addition to the PayPal button.

Checkout with Vault supports the following features:

Select or add shipping addresses to the PayPal account
Select or add funding instruments to the PayPal account
Support two-factor authentication, currently available only in the US, UK, CA, DE, AT, and AU
Get the customer's authorization to store the PayPal wallet in the Vault

Typical use cases for the Checkout with Vault flow are similar to those of One-time Payments, with the added benefit of storing the PayPal wallet to reduce friction when the customer returns for a repeat purchase. Common use cases include:

Checkout from cart or product pages
Checkout page replacement
As a payment source

Invoke the Checkout with Vault flow

To request a Checkout with Vault payment, set flow to checkout, set requestBillingAgreement to true, and include the amount and currency options in your createPayment call. The value of currency must match the value passed into loadPayPalSDK. If you use intent, the value must match in both loadPayPalSDK and createPayment.

Include these additional options:

billingAgreementDetails.description: a description of the billing agreement to show the customer
Use a createOrder function to create the payment resource
Use the onShippingChange function from the PayPal JavaScript SDK setup method to listen for shipping changes that occur within the PayPal pop-up. Use the updatePayment function, part of the Braintree JavaScript SDK's paypalCheckoutInstance, to update the PayPal checkout flow with modified order line items or shipping options. The updatePayment function replaces actions.order.patch.
Use the paypalCheckoutInstance in the onApprove function of the PayPal JS SDK setup method to tokenize the PayPal account. After the customer completes the consent flow and the PayPal pop-up closes, successful tokenization returns a payment method single-use token.
Send the single-use token to your server and use a Braintree server SDK to call Transaction.sale to create a transaction. When you create a Transaction.sale using a single-use token from the Checkout with Vault flow, the result contains a PayPal details object with an implicitlyVaultedPaymentMethodToken property. You can then associate this payment method token with your customer for future transactions.

Returning customer

Note

If you're integrating Pay Later offers, this step is mandatory. Returning customers can choose a Pay Later offer if they see PayPal Pay Later messaging in their shopping experience. Be sure to also render the Pay Later button in addition to the PayPal button for the returning customer experience.

To activate Pay Later offers in your Checkout with Vault integration, reach out to your PayPal account manager or contact us.

Returning customers who have already stored the PayPal wallet in the Vault can change the payment method they previously selected within the PayPal wallet.

Customers can change their payment method by selecting the PayPal button, then selecting Change payment method. If they don't want to change it, they can select the PayPal button and continue with the transaction.

You can render the PayPal button as a Change payment method button for vaulted customers.

Use the One-time Payments flow instead of the Checkout with Vault flow.
Use a client token generated with a customer ID that has a vaulted PayPal Billing Agreement when you initialize the Braintree client instance.
Set autoSetDataUserIdToken: true when you initialize the Braintree PayPal Checkout instance.
Optional: set additional dataAttributes, such as data-page-type, when you use the Braintree PayPal Checkout instance to load the PayPal SDK. For details, see Customize the PayPal JS SDK.

Country support

PayPal is available to merchants in all supported countries and to customers in more than 140 countries. Make sure you use a locale code as described in the JavaScript PayPal client reference.

Currency presentment

Checkout with Vault shows the transaction currency to the customer. Braintree supports all currencies that the PayPal REST APIs support.

For details on charging a transaction in a specific currency, see the Currency support section of the server-side guide.

Next Page: Pay Later Offers →