Save PayPal with the JavaScript SDK

After customers save their PayPal Wallet, they can select it for faster checkout. Customers won't have to enter payment details for future transactions.

To vault PayPal Wallets, payers need to log in to your site, make a purchase, and remain on your site when transactions take place.

Customers with a PayPal Wallet can:

Know before you code

How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

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

Return payer experience

The following is an example of what a payer sees after they save their PayPal Wallet on your site. Returning payers can select their saved payment method at checkout to pay faster.

The payer uses a credit card in their PayPal Wallet in the following example:

Use cases

Businesses save payment methods if they want customers to:

1. Get vetted to save PayPal Wallets

To go live, you'll need to be vetted for PayPal Wallet. You can start the vetting process from the Merchant Servicing Dashboard.

2. Generate user ID token for payer

The OAuth 2.0 API to retrieve an access_token has an additional parameter, response_type, that can be set to id_token. Include the id_token and access_token in the response.

First-time payer

A payer wants to save a payment method for the first time. Modify the POST request to generate id_token for the payer.

Returning payer

A payer wants to use a saved payment method.

Use the saved PayPal-generated customer ID in the POST body parameter target_customer_id. The target_customer_id is a unique ID for a customer generated when the payment_source is saved to the vault. The target_customer_id is available when capturing the order or retrieving saved payment information.

Sample server-side user ID token request

curl -s -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
 -u CLIENT_ID:CLIENT_SECRET \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=client_credentials" \
 -d "response_type=id_token"

Modify the code

Copy the code sample and modify it as follows:

A successful request returns fields including an access_token, id_token, and the number of seconds the access_token token is valid.

The id_token:

Sample response

{
     "access_token" : "A21AAJ--LVQmYlaxd_TDFOqVs4C3Xa7kPfa0Es7O35_9TEWaWRCMw7-NBJuBWqXZhb3eOolNnMtxwhoMP3NqHOJm1rvPDehfQ",
     "app_id" : "APP-80W284485P519543T",
     "expires_in" : 32400,
     "id_token" : "eyJraWQiOiJjMmVjMmZiYjIzMGU0ZDkzOTNhMGFmZjEzZTY4MjFjMSIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJpc3MiOiJodHRwczovL2FwaS5zYW5kYm94LnBheXBhbC5jb20iLCJzdWIiOiJQQ0haQ1RMMjVSNllXIiwiYWNyIjpbImNsaWVudCJdLCJzY29wZSI6WyJCcmFpbnRyZWU6VmF1bHQiXSwib3B0aW9ucyI6eyJjdXN0b21lcl9pZCI6IjIxMzM3NTk5MiJ9LCJheiI6ImdjcC5zbGMiLCJleHRlcm5hbF9pZCI6WyJQYXlQYWw6UENIWkNUTDI1UjZZVyIsIkJyYWludHJlZTo2ZDNtY3pqN2h3cHE4Y2cyIl0sImV4cCI6MTY2NDIzOTA1MCwiaWF0IjoxNjY0MjM4MTUwLCJqdGkiOiJVMkFBSVNTRkozbVlJUE8wdGYwTF93NFVmTHpfeGFCNHhYRndkTnRibTNXOVhtQ2xoU2NuWGZtMmRxbjU5QjY2akRVbzNhd1Y0ODlsbFpZOVBuV2RFTVN4ZlpZVDZKTS1mUi1rdEotcV9pdkZKMHlCWXdpdU1HaldPR2psZWktUSJ9.PSDUMcZxsEEUlKNqKHgFhrmAcKeCeJMIMhzMrVV5PpTftlB_Xmgzwl1Fir0H0OYSjmopcVPNfXyXl55jxaqJdQ",
     "nonce" : "2022-09-27T00:22:30ZxsLQJVSYoAx7jqj1JJgr3onjVSPVL5juzZbId-Z-bwQ",
     "scope" : "https://uri.paypal.com/services/invoicing https://uri.paypal.com/services/vault/payment-tokens/read https://uri.paypal.com/services/disputes/read-buyer https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/disputes/update-seller https://uri.paypal.com/services/paypalhere openid https://uri.paypal.com/services/payments/payment/authcapture https://uri.paypal.com/services/disputes/read-seller Braintree:Vault https://uri.paypal.com/services/payments/refund https://uri.paypal.com/services/identity/activities https://api-m.sandbox.paypal.com/v1/vault/credit-card https://api-m.sandbox.paypal.com/v1/payments/.* https://uri.paypal.com/services/reporting/search/read https://uri.paypal.com/payments/payouts https://uri.paypal.com/services/vault/payment-tokens/readwrite https://api-m.sandbox.paypal.com/v1/vault/credit-card/.* https://uri.paypal.com/services/shipping/trackers/readwrite https://uri.paypal.com/services/subscriptions https://uri.paypal.com/services/applications/webhooks https://api-m.sandbox.paypal.com/v1/payments/refund https://api-m.sandbox.paypal.com/v1/payments/sale/.*/refund",
     "token_type" : "Bearer"
  }

3. Pass user ID token to JavaScript SDK

Pass the id_token from your server into the JavaScript SDK using the data-user-id-token.

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

If you are processing PayPal transactions on behalf of another merchant, include the merchant_id parameter as described in the JavaScript SDK script configuration.

4. Add PayPal button

<!-- Set up a container element for the button -->
<div id="paypal-button-container"></div>

5. Create order

Include client-side callbacks to:

<script>
  paypal.Buttons({
      // Call your server to set up the transaction
      createOrder: function(data, actions) {
        return fetch('/yourserver.com/createOrder', {
          method: 'post',
          body: JSON.stringify({
            source: data.paymentSource, // PayPal, Venmo, and so on
          }),
        }).then(function(res) {
          return res.json();
        }).then(function(orderData) {
          return orderData.id;
        });
      },
      // Authorize or capture the transaction after payer approves
      onApprove: (data, actions) => {
        return fetch('/yourserver.com/order/' + data.orderID + '/capture/', {
          method: 'post'
        });
      },
      onCancel(data, actions) {
        console.log(`Order Canceled - ID: ${data.orderID}`);
      },
      onError(err) {
        console.error(err);
      }
  }).render('#paypal-button-container');
</script>

Server-side code snippet

Set up your server to call the Create Order API. The button that the payer selects determines payment_source sent in the sample.

This SDK uses the Orders v2 API to save payment methods in the background. Use the server-side sample request to add attributes needed to save a PayPal Wallet.

Request

In the sample request, payment_source.paypal.attributes.vault.store_in_vault with the value ON_SUCCESS means the PayPal button is saved with a successful authorization or capture.

Pass payment_source.paypal.experience_context and include return_url and cancel_url to redirect the payer after they approve or cancel the order.

To allow a payer to save payment tokens for both PayPal and Venmo, pass permit_multiple_payment_tokens value as true in payment_source.paypal.attributes.vault.

To save payments at the platform level, set usage_type to PLATFORM under the vault attribute.

To save payments at the merchant level:

For returning payers, also pass shipping_preference.

Platform Response

Return the id to your client to call the payer approval flow if payment_source needs payer approval.

6. Payer approval

If payer approval is required, the client SDK calls the payer approval flow. The approval flow takes the payer through PayPal Checkout.

7. Authorize or capture order

After the payer approves, the onApprove function is called in the JavaScript SDK. Depending on the intent passed, the server calls the following APIs:

If authorization or capture is successful, a vault.id is also created.

curl -v -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
 -d '{}'

Capture order response

The HTTP response codes HTTP 2xx or HTTP 200 are returned for a successful request.

The capture is successful if the purchase_units[0].payments.captures.status is COMPLETED. You can confirm with the payer that the payment has been captured.

In the response from the authorize or capture request, the Orders v2 API interacts with the Payment Method Tokens v3 API. The Payment Method Tokens v3 API allows a Venmo account to be saved. The response from the Orders v2 API contains the:

On a successful response, the payment_source.venmo.attribute.vault.status is set to VAULTED along with the vault ID at payment_source.venmo.attribute.vault.id.

Save approved payment source

If the payment has been authorized or captured, the payer does not need to be present to save a payment_source. To keep checkout times as short as possible, the Orders API responds as soon as payment is captured.

If the attributes.vault.status returned after payment is APPROVED, you won't have a vault.id yet. An example of the attributes object from this scenario is in the following sample:

"attributes": {
        "vault": {
          "status": "APPROVED",
          "links": [
            {
              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
              "rel": "up",
              "method": "GET"
            }
          ]
        }
      }

The Payment Method Tokens API still saves the payment source even after the Orders API returns its response and sends a webhook after the payment source is saved.

In order to retrieve a vault_id when an APPROVED status is returned, you'll need to subscribe to the VAULT.PAYMENT-TOKEN.CREATED webhook.

The Payment Method Tokens API sends a webhook after the payment source is saved. An example of the VAULT.PAYMENT-TOKEN.CREATED webhook payload is shown in the following sample:

{
  "id": "WH-72S4353495632143A-68K769747M133873M",
  "event_version": "1.0",
  "create_time": "2022-08-27T01:25:57.462Z",
  "resource_type": "payment_token",
  "resource_version": "3.0",
  "event_type": "VAULT.PAYMENT-TOKEN.CREATED",
  "summary": "A payment token has been created.",
  "resource": {
    "time_created": "2022-08-26T18:25:57.449PDT",
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/7vrxmrw",
        "rel": "self",
        "method": "GET",
        "encType": "application/json"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/7vrxmrw",
        "rel": "delete",
        "method": "DELETE",
        "encType": "application/json"
      }
    ],
    "id": "3nqvjt3n",
    "payment_source": {
      "paypal": {
        "permit_multiple_payment_tokens": false,
        "usage_type": "MERCHANT",
        "customer_type": "CONSUMER",
        "email_address": "buyer@example.com",
        "payer_id": "VTR4JYK7STE7J"
      }
    },
    "customer": {
      "id": "208743798"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-72S4353495632143A-68K769747M133873M",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-72S4353495632143A-68K769747M133873M/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

In the previous example, the resource.id field is the vault ID. The resource.customer.id is the PayPal-generated customer ID.

8. Test your integration

Run the following tests in the PayPal sandbox to ensure you can save PayPal Wallets.

Next steps

See also