PayPal

Checkout with Vaultanchor

Checkout with Vault is a one-time PayPal Checkout experience, but with vaulting capability. It automatically creates a PayPal Billing Agreement and stores a customer's PayPal account in the Braintree Vault, allowing you to charge the account in the future without requiring your customer to re-authenticate with PayPal and choose a payment method within their wallet.

note

If you are integrating Pay Later offers, you must render the Pay Later button in addition to the PayPal button.

Checkout with Vault supports the following features:

  • 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)
  • Allow authorization from the customer to store the PayPal wallet in the Vault

XO-w-PP-flow

Typical use cases for the Checkout with Vault flow are similar to those of Checkout with PayPal, but with the added benefit of being able to store the PayPal Wallet to reduce friction when the customer comes back for a repeat purchase. Common use cases include:

  • Checkout from Cart/Product pages
  • Checkout page replacement
  • As a payment source

Invoking the Checkout with Vault flowanchor

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

Additional options to include:

  • billingAgreementDetails.description: description of the billing agreement to display to the customer

Use a createOrder function to create the payment resource:

Use the onShippingChange function from the PayPal JS SDK setup method to listen for shipping changes that occur within the PayPal pop-up; then, use the updatePayment function , part of the Braintree JS SDK's paypalCheckoutInstance, to update the PayPal checkout flow with modified order line items or shipping options. Note that updatePayment replaces use of 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 will return a payment method nonce.

Send the nonce to your server and use a Braintree server SDK to call Transaction.sale to create a transaction. When creating a Transaction.sale using a nonce from the Checkout with Vault flow, the result will contain a PayPal details object with an implicitlyVaultedPaymentMethodToken property. You can then associate this payment method token with your customer for future transactions.

Returning customer experienceanchor

note

If you are integrating Pay Later offers, this step is mandatory as it allows returning consumers to choose a Pay Later offer should they see PayPal Pay Later Messaging in their shopping experience. It is also mandatory to render the Pay Later button in addition to the PayPal button for the Returning customer experience.

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

Enabling this option gives a returning customer, who has previously stored the PayPal Wallet within the Vault, the flexibility to change the payment method that they had previously selected within the PayPal Wallet.

Customers can choose to change the payment method by clicking on the PayPal button as seen below and clicking the link Change payment method. If they do not wish to do so they can click the PayPal button and continue with the transaction.

The PayPal button can be rendered as a Change payment method button for vaulted customers.

  1. Be sure to use the Checkout flow instead of the Checkout with Vault flow
  2. Use a client token generated with a customer ID that has a vaulted PayPal Billing Agreement when initializing the Braintree client instance
  3. Set autoSetDataUserIdToken: true when initializing the Braintree PayPal Checkout instance
  4. Optionally set additional dataAttributes, such as data-page-type, when using the Braintree PayPal Checkout instance to load the PayPal SDK. For details, see the PayPal docs.

Country 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

The currency of the transaction is presented to the customer in the Checkout with Vault flow. We support all currencies that PayPal REST APIs support.

See the server-side section for details on charging a transaction in a specific currency.


Next Page: Server-side →