Integrate PayPal shopper insights with the JavaScript SDK

Improve conversion rates, increase sales, and increase user retention by prioritizing the customer’s preferred payment methods. Determine if a customer has a PayPal account and what is their recommended payment button.

Know before you code

• If you are a new merchant, sign up for a PayPal business account.
• Complete Get started to set up your PayPal account, client ID, and sandbox emails for testing.
• Get consent from your customer to share this information with PayPal services.

How it works

Initialize the SDK with the data attributes provided later in this guide. A function on the global paypal namespace enables you to pass in a customer's email, phone number, or both to determine the following:

• If the customer has an account within PayPal services.
• Based on internal data, which payment button is recommend for this customer (PayPal or Venmo).

The following is a sequence diagram showing how to obtain the sdk_token that you pass into your data-sdk-client-token attribute.

1. Generate client SDK token

Before initializing the SDK, you must generate a token that can be passed in to the SDK's data-sdk-client-token attribute.

To fetch this token, use the following OAuth 2.0 API and pass your base64-encoded CLIENT_ID:CLIENT_SECRET. This token must be generated on your server to better protect your client secret.

To base64 encode your client ID and secret using node.js:

1const BASE64_ENCODED_CLIENT_ID_AND_SECRET = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')

Option 1: Request the token to initialize the SDK (direct merchant integration)

1curl -s -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \
2  -u BASE64_ENCODED_CLIENT_ID_AND_SECRET \
3 -H "Content-Type: application/x-www-form-urlencoded" \
4 -d "grant_type=client_credentials" \
5 -d "response_type=id_token" \
6 -d "intent=sdk_init"

Option 2: Request the token to initialize the SDK (partner integration)

If you’re a partner that has integrated with PayPal, make sure to fetch your token using the following information. Generate an AUTH-ASSERTION-TOKEN to initialize the SDK.

Generate the Auth-Assertion token

1const header = Buffer.from(JSON.stringify({ alg: "none" })).toString("base64");
2 const payload = Buffer.from(JSON.stringify({
3   payer_id: MERCHANT_ID,
4   ss: PARTNER_CLIENT_ID,
5 })).toString("base64");
6
7 const AUTH_ASSERTION_HEADER = `${header}.${payload}.`;

Generate the SDK token using the Auth-Assertion token

1curl -s -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \
2  -u CLIENT_ID:CLIENT_SECRET \
3 -H "Content-Type: application/x-www-form-urlencoded" \
4 -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-TOKEN' \
5 -d "grant_type=client_credentials" \
6 -d "response_type=id_token" \
7 -d "intent=sdk_init"

Sample response

1{
2 "access_token" : "A21AAJ--LVQmY...",
3 "app_id" : "APP-80W284485P519543T",
4 "expires_in" : 32400,
5 "id_token" : "eyJraWQiOiJj...",
6 "nonce" : "2022-09-27T00:22:30Zxs...",
7 "scope" : "...",
8 "token_type" : "Bearer"
9}

2. Integrate the client SDK

Step 1: Initialize the JavaScript SDK

1<script
2  src="<https://www.paypal.com/sdk/js?client-id=CLIENT_ID&components=buttons,shopper-insights>"
3  data-sdk-client-token="CLIENT_SDK_TOKEN"
4  data-page-type="product-details"
5></script>

1. Set the client-id parameter as your client ID.
2. The sdk_token in the server-side API seen in the previous section is passed to data-sdk-client-token.
3. The attribute data-page-type is required to indicate which page the buttons will be presented. Valid values are documented here.
4. If the SDK is initialized without a data-sdk-client-token or a data-page-type, and the getRecommendedPayments function is used, an integration error shows up.

1<script
2  src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&merchant-id=MERCHANT_ID&components=buttons,shopper-insights">
3</script>

Step 2: Call the Shopper Insights API

1const result = await paypal
2  .ShopperInsights
3  .getRecommendedPaymentMethods({
4    customer: {
5      email: "customer12345@gmail.com",
6      phone: {
7        countryCode: "1",
8        nationalNumber: "1234567890",
9      },
10    },
11  });

Step result

1{
2  isPayPalRecommended: boolean,
3  isVenmoRecommended: boolean,
4}

Use case 1: Display a single button for upstream presentment

1const { isPayPalRecommended } = result;
2
3if (isPayPalRecommended) {
4  const button = paypal.Buttons({
5    fundingSource: window.paypal.FUNDING.PAYPAL
6  })
7
8  button.isEligible() && button.render("#paypal-button-container");
9} else {
10  // Merchant renders a different payment option
11}

Use case 2: Display multiple buttons for upstream presentment

1const { isPayPalRecommended, isVenmoRecommended } = result;
2
3if (isPayPalRecommended) {
4  const button = paypal.Buttons({
5    fundingSource: window.paypal.FUNDING.PAYPAL
6  })
7
8  button.isEligible() && button.render("#paypal-button-container");
9}
10
11if (isVenmoRecommended) {
12    const button = paypal.Buttons({
13      fundingSource: window.paypal.FUNDING.VENMO
14    })
15
16    button.isEligible() && button.render("#paypal-button-container");   
17}

Next steps

Test your integration in the PayPal sandbox.