Vault with the JavaScript SDK

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

Know before you code

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.

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

Use cases

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.

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

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

Modify the code

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

{
  "client_token": "eyJicmFpbnRyZWUiOnsiYXV0aG9yaXphdGlvbkZpbmdlcnByaW50IjoiYjA0MWE2M2JlMTM4M2NlZGUxZTI3OWFlNDlhMWIyNzZlY2FjOTYzOWU2NjlhMGIzODQyYTdkMTY3NzcwYmY0OHxtZXJjaGFudF9pZD1yd3dua3FnMnhnNTZobTJuJnB1YmxpY19rZXk9czlic3BuaGtxMmYzaDk0NCZjcmVhdGVkX2F0PTIwMTgtMTEtMTRUMTE6MTg6MDAuMTU3WiIsInZlcnNpb24iOiIzLXBheXBhbCJ9LCJwYXlwYWwiOnsiYWNjZXNzVG9rZW4iOiJBMjFBQUhNVExyMmctVDlhSTJacUZHUmlFZ0ZFZGRHTGwxTzRlX0lvdk9ESVg2Q3pSdW5BVy02TzI2MjdiWUJ2cDNjQ0FNWi1lTFBNc2NDWnN0bDUyNHJyUGhUQklJNlBBIn19",
  "expires_in": 3600
}

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.

<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

2. Pay with a saved payment method

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.

<div>
  <input type="checkbox" id="vault" name="vault">
  <label for="vault">Save your card</label>
</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.

// Check eligibility for advanced credit and debit card payments
if (paypal.HostedFields.isEligible()) {
    // render hosted fields
    paypal.HostedFields.render({

         //This sample function returns the order ID
        createOrder: () => {
            // logic to return an order ID from your server
        },
        fields: {
            number: {
                selector: '#card-number',
                placeholder: 'card number'
            },
            cvv: {
                selector: '#cvv',
                placeholder: 'CVV',
            },
            expirationDate: {
                selector: '#expiration-date',
                placeholder: 'mm/yyyy'
            }
        }
    }).then(function (hf) {

        document.querySelector('#my-sample-form').addEventListener('submit', (event) => {
            event.preventDefault();
            hf.submit({

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

            }).then(function (payload) {
              // Make a call to capture the order (payload.orderId) here
            });
        });
    });
}
else {
    /*
     * Handle experience when advanced credit and debit cards is not eligible
     */
}

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

2. Pay with a saved payment method

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

See also