JavaScript SDK script configuration

Module

You can use the SDK as a module. Loading the SDK as a module brings certain advantages, especially when working with a JavaScript framework. For example, you can optimize performance because the module lets you control loading behavior in JavaScript instead of HTML. It can also help reduce bugs by encapsulating data.

• Use the paypal-js npm package to integrate with front-end tools.
• Use the react-paypal-js npm package within the React.js framework.

You can configure and customize your integration by passing query parameters and script parameters in the JavaScript SDK script tag. These parameters personalize your setup and help PayPal decide the optimal funding sources and buttons to show to your buyers.

Query parameters

Query parameters help define specific content or actions based on the data being passed. Each piece of data you send contains the following:

• A key-value pair. Keys define the piece of information needed, and the value provides that information. The key is separated from the value by an equal sign (=).
• A question mark (?) to signify the beginning of the key-value pairs in the query string.
• Ampersands (&) if you need to provide more than 1 set of values at a time.
• Information that PayPal needs to handle your request.

In this example, you send your authorization and components as query parameters:

Script parameters

Script parameters are additional key value pairs you can add to the script tag to provide information you need for your site to work, a single-use token, or information you'd like to capture on a page for analytics reasons.

For example, a token that identifies your buyer:

client-ID

The client-ID identifies the PayPal account that sets up and finalizes transactions. By default, funds from any transactions are settled into this account. If you are facilitating transactions on behalf of other merchants and capturing funds into their accounts, see merchant-ID.

buyer-country

The buyer country determines which funding sources are eligible for a given buyer. Defaults to the buyer's IP geolocation. Any country that you can pass as a locale is a valid buyer country.

commit

The commit status of the transaction. Determines whether to show a Pay Now or Continue button in the Checkout flow.

• Use the Pay Now button when the buyer completes payment on the PayPal review page. For example, digitally-delivered items without shipping costs.
• Use the Continue button when the buyer completes payment on your site to account for shipping, tax, and other items before submitting the order.

components

The PayPal components you intend to render on your page. Each component you use must be separated by a comma (,). If you don't pass any components, the default payment buttons component automatically renders all eligible buttons in a single location on your page.

For example, you want to offer your buyers Pay Later options when they choose PayPal along with other payment options:

currency

The currency for the transaction. Funds are captured into your account in the specified currency. Defaults to USD.

debug

Set to true to enable debug mode. Debug mode is recommended only for testing and debugging, because it increases the size of the script and negatively impacts performance. Defaults to false.

disable-card

disable-funding

The disabled funding sources for the transaction. Any funding sources that you pass aren't displayed as buttons at checkout. By default, funding source eligibility is determined based on a variety of factors. Don't use this query parameter to disable advanced credit and debit card payments.

enable-funding

The enabled funding sources for the transaction. By default, funding source eligibility is determined based on a variety of factors. Enable funding can be used to ensure a funding source is rendered, if eligible.

integration-date

The integration date of the script, passed as a YYYY-MM-DD value. Defaults to the date when your client ID was created, which reflects the date that you added the PayPal integration to your site. This parameter ensures backwards compatibility.

• Your site automatically gets any backward-compatible changes made to the PayPal script.
• These changes include:
  • New funding sources
  • Buttons
  • Updated user interfaces
  • Bug fixes
  • Security fixes
  • Performance optimizations
• You don't need to change the integration-date to enable new features.
• Your site doesn't get any backward incompatible updates made to the PayPal script after the specified integration-date, or after the date your client-id was created, if you don't pass the integration-date parameter.
• If your client-id doesn't change, you can omit the integration-date parameter and the script will maintain backward compatibility.
• If your client-id changes dynamically, you must pass an integration date, which ensures that no breaking changes are made to your integration. This could be the case if you build a cart app, which enables merchants to dynamically set a client ID to add PayPal to their store.

intent

The intent for the transaction. This determines whether the funds are captured immediately while the buyer is present on the page. Defaults to capture.

locale

The locale renders components. By default PayPal detects the correct locale for the buyer based on their geolocation and browser preferences. It is recommended to pass this parameter only if you need the PayPal buttons to render in the same language as the rest of your site.

merchant-id

The merchant ID of a merchant for whom you are facilitating a transaction.

Use this parameter only for partner, marketplaces, and cart solutions when you are acting on behalf of another merchant to facilitate their PayPal transactions.

vault

Whether the payment information in the transaction will be saved. Save your customers' payment information for billing agreements, subscriptions, or recurring payments.

Set to true if the payment sets up a billing agreement, reference transaction, subscription, or recurring payment. Defaults to false.

data-csp-nonce

Pass a Content Security Policy single-use token if you use them on your site. See Content Security Policy for details.

data-client-token

Client token used to identify your buyers.

data-page-type

Pass a page type to log any interactions with the components you use and the type of page where the JavaScript SDK loads. This attribute accepts the following page types: product-listing,search-results, product-details, mini-cart, cart or checkout.

data-partner-attribution-id

Pass your partner attribution ID, or build notation (BN) code, to receive revenue attribution. Your BN code is issued to you as part of the partner onboarding process and provides tracking on all your transactions. To find your BN code:

1. Log in to the Developer Dashboard with your PayPal account.
2. In the left-hand navigation menu, select My Apps & Credentials.
3. Select your app.
4. Under App Settings, find your BN code.

data-user-id-token

Attribute to pass the id_token from your server into the JavaScript SDK.