Vault with the JavaScript SDK

Vaulting securely saves your buyers' payment information and streamlines their checkout experience.

Know before you code

• This procedure modifies an existing standard payments or advanced credit and debit card payments integration.
• Your payments integration must have a server-side capture call or a server-side authorization and capture call.
• To vault payment methods, you must be able to uniquely identify your buyers. For example, buyers create an account and log in to your site.
• Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
  • Your sandbox account login information
  • Your access token

How it works

When a buyer on your website saves their payment method, PayPal creates a customer record. PayPal then encrypts the payment method information and stores it in a digital wallet for that customer which is accessible only by you.

1. Your buyer chooses to save their payment method.
2. You identify the buyer by a unique customer ID.
3. When the buyer returns to your website and is ready to checkout, you pass their customer ID to the PayPal JavaScript SDK to indicate you want to save or reuse a previously-saved payment method.
4. If paying with PayPal, your buyer completes a billing agreement. There is no billing agreement required for card payments.
5. The PayPal JavaScript SDK populates the checkout page with each saved payment method. Each payment method displays as one-click payment buttons alongside other ways to pay.

The checkout process is now shorter because it uses the saved payment information.

Use cases

• Merchants who want to eliminate the payment entry step of the checkout flow.
• Business that let customers pay after consumption. For example, the sharing economy and food delivery.

Vault a PayPal account

To vault a PayPal account, buyers need to log in to your site to check out and remain present on your site when transactions take place.

Step 1. Enable your sandbox business account to vault payment methods

Before you can vault payment methods, your sandbox business account has to be enabled by PayPal for this capability.

Sign into www.sandbox.paypal.com/bizsignup/entry/product/ppcp with your sandbox business account that you obtained from the Dashboard. Sandbox requests are automatically approved so you can build and test your integration. Before you test and go live, you'll repeat this process for your merchant account in the production environment.

• Only your sandbox business account is enabled for vaulting payment methods, and your developer account remains unaffected.

• You'll complete production onboarding when you're ready to go live.

  Tip: When prompted for required data like a phone number for the sandbox business request, enter any number that fits the required format. Since this is a sandbox request, the data doesn't have to be factual.

Step 2: Generate a client token for your buyer

Pass the customer ID to PayPal to generate a client token. The customer ID is a unique ID for a customer in your system of records and the client token uniquely identifies each buyer. You use the client token in Step 3.

Copy the following code and modify it.

Sample client token request

1curl -v POST https://api-m.sandbox.paypal.com/v1/identity/generate-token \
2   -H 'Accept: application/json' \
3   -H 'Accept-Language: en_US' \
4   -H 'Authorization: Bearer <ACCESS-TOKEN>' \
5   -H 'Content-Type: application/json' \
6   -d '{
7      "customer_id": "customer_1234"
8      }'

Modify the code

1. Copy the sample request code.
2. Change Access-Token to your sandbox access token.
3. Replace customer_1234 with a unique customer ID for each buyer who logs into your site. Make sure the customer ID:
   • Is an alphanumeric value that is unique for each buyer.
   • Never changes when the same buyer logs in to your website at a later time.

Step result

A successful request results in a client token and the number of seconds the token is valid. You can generate a new client token if the current token expires.

Sample client token response

1{
2  "client_token": "eyJicmFpbnRyZWUiOnsiYXV0aG9yaXphdGlvbkZpbmdlcnByaW50IjoiYjA0MWE2M2JlMTM4M2NlZGUxZTI3OWFlNDlhMWIyNzZlY2FjOTYzOWU2NjlhMGIzODQyYTdkMTY3NzcwYmY0OHxtZXJjaGFudF9pZD1yd3dua3FnMnhnNTZobTJuJnB1YmxpY19rZXk9czlic3BuaGtxMmYzaDk0NCZjcmVhdGVkX2F0PTIwMTgtMTEtMTRUMTE6MTg6MDAuMTU3WiIsInZlcnNpb24iOiIzLXBheXBhbCJ9LCJwYXlwYWwiOnsiYWNjZXNzVG9rZW4iOiJBMjFBQUhNVExyMmctVDlhSTJacUZHUmlFZ0ZFZGRHTGwxTzRlX0lvdk9ESVg2Q3pSdW5BVy02TzI2MjdiWUJ2cDNjQ0FNWi1lTFBNc2NDWnN0bDUyNHJyUGhUQklJNlBBIn19",
3  "expires_in": 3600
4}

Step 3. Pass the client token to the PayPal JavaScript SDK

Pass the client token from your server into the PayPal JavaScript SDK using data-client-token.

1<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-client-token="YOUR-CLIENT-TOKEN"></script>

Step 4. Modify the width of your button

Set the width of your button to be 350 px or greater to allow for button content. Otherwise your button behavior reverts to a standard button and won't offer the option to pay with a saved payment method. See the button style options for more information.

Step 5. Test your integration

Run the following tests in the PayPal sandbox to ensure vaulting the payment method is set up correctly.

1. Save a payment method

1. On your checkout page, click the PayPal button.
2. Log in to your buyer account and approve the payment and billing agreement.
3. Capture the transaction.
4. Log in to sandbox with your merchant account and verify the transaction.
5. Refresh the page that contains the PayPal button.
6. Ensure that the payment method you just saved is visible with the other buttons.

2. Pay with a saved payment method

1. On your checkout page, click the button for the saved payment method you want to test.
2. Capture the transaction.
3. Log in to sandbox with your merchant account and verify the transaction.

You've completed the steps to vault a PayPal account.

Vault cards for advanced credit and debit card payments

These steps modify your advanced credit and debit card payments integration. Your eligibility for advanced credit and debit card payments enables you to save cards.

Step 1. Add a checkbox element for buyers to save their card

Add a checkbox element grouped with your card collection fields to allow buyers the option to save their card.

1<div>
2  <input type="checkbox" id="vault" name="vault">
3  <label for="vault">Save your card</label>
4</div>

Step 2. Update your code to pass the value of the checkbox

Pass vault: document.querySelector('#vault').checked with the value of the checkbox when submitting the advanced credit and debit card payments instance.

1// Check eligibility for advanced credit and debit card payments
2if (paypal.HostedFields.isEligible()) {
3    // render hosted fields
4    paypal.HostedFields.render({
5
6         //This sample function returns the order ID
7        createOrder: () => {
8            // logic to return an order ID from your server
9        },
10        fields: {
11            number: {
12                selector: '#card-number',
13                placeholder: 'card number'
14            },
15            cvv: {
16                selector: '#cvv',
17                placeholder: 'CVV',
18            },
19            expirationDate: {
20                selector: '#expiration-date',
21                placeholder: 'mm/yyyy'
22            }
23        }
24    }).then(function (hf) {
25
26        document.querySelector('#my-sample-form').addEventListener('submit', (event) => {
27            event.preventDefault();
28            hf.submit({
29
30                  // pass the value of the checkbox when submitting the advanced credit and debit card payments instance
31                  vault: document.querySelector('#vault').checked
32
33            }).then(function (payload) {
34              // Make a call to capture the order (payload.orderId) here
35            });
36        });
37    });
38}
39else {
40    /*
41     * Handle experience when advanced credit and debit cards is not eligible
42     */
43}

Acceptable input values for vault:

Step 3. (Optional) Create transactions when your buyer isn't present

When your buyer isn't present to checkout, you can get their payment tokens to create transactions using the payment methods that are saved by your buyers.

Step 4. Test your integration

Test in the PayPal sandbox to ensure vaulting is set up correctly.

1. Save a payment method

1. On your checkout page, enter card information and check the option to save your card. You can use test card numbers for testing.
2. Capture the transaction.
3. Log in to sandbox with your merchant account and verify the transaction.
4. Refresh your checkout page to confirm the payment method you used is present with the other buttons.

2. Pay with a saved payment method

1. On your checkout page, click the button for the saved payment method you want to test.
2. Capture the transaction.
3. Log in to sandbox with your merchant account and verify the transaction.

You've complete the steps to vault cards for advanced credit and debit card payments.

Test cards

To test your card fields integration in your sandbox environment, please choose cards from this list of positive test card numbers.

Next steps

• Test and go live with this integration.
  • Complete production onboarding to be eligible to process cards with your live PayPal account.
  • Remember to swap the credentials and API URL from sandbox to production when going live with your integration.

See also

• Set up standard payments
• Advanced credit and debit cards payments