JavaScript SDK script configuration

SDKCurrentLast updated: November 25th 2024, @ 4:06:17 pm

The JavaScript SDK displays relevant, PayPal-supported payment methods on your page, giving your buyers a personalized and streamlined checkout experience.

Add the SDK

You can integrate the SDK in a script tag or as a module:

Script tag

You can add the SDK in a script tag. This loads the main object PayPal to the global window scope of the browser. Replace YOUR_CLIENT_ID with your client ID.

Note: Load the JavaScript SDK directly from https://sandbox.paypal.com/sdk/js. Don't include it in a bundle or host it yourself. For more information, see Load the JavaScript SDK from the PayPal server.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID"></script>

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.

1import { loadScript } from "@paypal/paypal-js";
2loadScript({ "client-id": YOUR_CLIENT_ID })
3.then((paypal) => {
4    // start to use the PayPal JS SDK script
5})
6.catch((err) => {
7    console.error("failed to load the PayPal JS SDK script", err);
8});

Use the react-paypal-js npm package within the React.js framework.

1import { PayPalScriptProvider } from "@paypal/react-paypal-js";
2export default function App() {
3    return (
4        <PayPalScriptProvider options={{ "client-id": YOUR_CLIENT_ID }}/>
5    );
6}

Configure and customize your integration

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:

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:

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=card-fields"></script>

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:

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-client-token="abc123xyz=="></script>

Query parameters

Use test parameters to see JavaScript SDK results. If you don't pass a parameter, the default value is used.

Query Parameters

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.

Example value	Default	Description
`test`	none	Your PayPal REST client ID. This identifies your PayPal account, and determines where any transactions are paid to. While you're testing in sandbox, you can use `client-id=sb` as a shortcut.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID">
2        </script>

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.

Note: The buyer country is only used in the sandbox. Don't pass this query parameter in production.

Example value	Default	Description
`US`, `CA`, `GB`, `DE`, `FR`	automatic	The buyer country. Available in the sandbox for testing.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&buyer-country=US">
2</script>

commit

The commit status of the transaction. Determines whether to show a Pay Now or Continue button in the Checkout flow. We recommend a Pay Now button for the fewest steps to complete a transaction.

Use the Pay Now button for the the buyer to complete payment on the PayPal review page.
Use the Continue button for the buyer to confirm payment details on the PayPal review page and complete payment on the merchant site.

Important: When you integrate with a PayPal API, make sure the commit value you pass in the API call matches the value you pass in the JavaScript call.

Example value Default Description

Example value	Default	Description
`true`, `false`	`true`	Set to `true` if the transaction is completed on the PayPal review page or `false` if the amount captured changes after the buyer returns to your site. Not applicable for subscriptions. `true` shows a Pay Now button in the PayPal Checkout flow. The final amount doesn't change after the buyer returns from PayPal to your site. `false` shows a Continue button in the PayPal Checkout flow. The final amount might change after the buyer returns from PayPal to your site due to shipping, taxes, or other fees, the final amount.

true, false

true

Set to true if the transaction is completed on the PayPal review page or false if the amount captured changes after the buyer returns to your site. Not applicable for subscriptions.

true shows a Pay Now button in the PayPal Checkout flow. The final amount doesn't change after the buyer returns from PayPal to your site.
false shows a Continue button in the PayPal Checkout flow. The final amount might change after the buyer returns from PayPal to your site due to shipping, taxes, or other fees, the final amount.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&commit=false">
2</script>

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.

Option	Description
`buttons`	Places all of the eligible checkout buttons on your page.
`marks`	Presents other funding sources on your page alongside PayPal using radio buttons.
`messages`	Displays messaging for the most relevant Pay Later offer for every purchase.
`funding-eligibility`	Allows you to choose the individual payment buttons (methods) you want to display on your web page.
`hosted-fields`	Shows your own hosted credit and debit card fields.
`applepay`	Displays the Apple Pay button

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

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,marks,messages=">
2</script>

currency

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

Example value	Default	Description
`USD`, `CAD`, `EUR`	`USD`	The currency of the transaction or subscription plan.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=EUR">
2</script>

Search table

Currency	Code
Australian Dollar	`AUD`
Brazilian real	`BRL`
Canadian dollar	`CAD`
Czech koruna	`CZK`
Danish krone	`DKK`

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.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&debug=true"></script>

Option	Description
`true`	Enable debug mode.
`false`	Disable debug mode.

disable-card

Deprecated

This parameter is deprecated.

In previous versions of the JavaScript SDK that displayed individual card icons, this parameter disabled specific cards for the transaction. Any cards passed were not displayed in the checkout buttons.

Example value	Default	Description
`visa`	none	Deprecated. Cards to disable from showing in the checkout buttons.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&disable-card=amex,jcb"></script>

Search table

Option	Description
`visa`	Visa
`mastercard`	Mastercard
`amex`	American Express
`discover`	Discover
`jcb`	JCB

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.

Example value	Default	Description
`card`, `credit`, `bancontact`	none	Funding sources to disallow from showing in the checkout buttons. Don't use this query parameter to disable advanced credit and debit card payments.

Note: Pass credit in disable-funding for merchants that fall into these categories:

Real money gaming merchants
Non-US merchants who don't have the correct licenses and approvals to display the Credit button

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&disable-funding=credit,card">
2</script>

Search table

Option	Description
`card`	Credit or debit cards
`credit`	PayPal Credit (US, UK)
`paylater`	Pay Later (US, UK), Pay in 4 (AU), 4X PayPal (France), Später Bezahlen (Germany)
`bancontact`	Bancontact
`blik`	BLIK

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.

Example value	Default	Description
`venmo`, `paylater`	none	Funding sources to display as buttons at checkout.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&enable-funding=venmo">
2</script>

Search table

Option	Description
`card`	Credit or debit cards
`credit`	PayPal Credit (US, UK)
`paylater`	Pay Later (US, UK), Pay in 4 (AU), 4X PayPal (France), Später Bezahlen (Germany)
`bancontact`	Bancontact
`blik`	BLIK

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.

Example value	Default	Description
`2018-11-30`	automatic	The date of integration. Used to ensure backwards compatibility.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&integration-date=2018-11-07"></script>

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.

Important: When you integrate with a PayPal API, make sure the intent value you pass in the API call matches the value you pass in the JavaScript call.

Option	Description
`capture`	The funds are captured immediately while the buyer is present on your site.
`authorize`	The funds are authorized immediately and then reauthorized or captured later.
`subscription`	Used along with `vault=true` to specify this is a subscription transaction.
`tokenize`	Used along with `vault=true` and `createBillingAgreement` to specify this is a billing (without purchase) transaction.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&intent=authorize"></script>

Intent options when integrating with older APIs

When you integrate the JavaScript SDK with an older API like the Orders V1 REST API or one of our NVP/SOAP solutions, you can use the following options:

Option	Description
`capture` or `sale`	The funds are captured immediately while the buyer is present on your site. The value you use should match the `intent` value in the API call.
`authorize`	The funds are authorized immediately and then reauthorized or captured later.
`order`	The funds are validated without an authorization and you can reauthorize or capture later.

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.

Example value	Default	Description
`en_US`, `fr_FR`, `de_DO`	automatic	The locale used to localize any components. PayPal recommends not setting this parameter, as the buyer's locale is automatically set by PayPal.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&locale=fr_FR"></script>

Search table

Country	Code	Locale
ALBANIA	`AL`	`en_AL`
ALGERIA	`DZ`	`ar_DZen_DZfr_DZes_DZzh_DZ`
ANDORRA	`AD`	`en_ADfr_ADes_ADzh_AD`
ANGOLA	`AO`	`en_AOfr_AOes_AOzh_AO`
ANGUILLA	`AI`	`en_AIfr_AIes_AIzh_AI`

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.

Example value	Default	Description
`ABC123`	automatic	The merchant for whom you are facilitating a transaction.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=XXX"></script>

Integration	Use Case	Client ID	Merchant ID	Additional parameters
Standalone integration	Capturing funds directly into my PayPal account.	Pass a client ID associated with your account.	Don't pass a merchant ID, because it is automatically derived.
Partner or Marketplace integration	Facilitating payments on behalf of other merchants.	Pass a client ID associated with your partner or marketplace account.	You must pass the merchant ID of the merchant for whom you are facilitating payments.
Cart integration	Facilitating payments on behalf of other merchants for whom I have client IDs.	Pass the client ID of the merchant for whom you are facilitating payments.	Don't pass a merchant ID.	Pass the `integration-date` parameter to ensure your integration doesn't break as new client IDs onboard to your site.

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.

Note: Not all payment methods can be saved.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&vault=true"></script>

Option	Description
`true`	Show only funding sources that you can save or use to create a billing agreement, reference transaction, subscription, or recurring payment.
`false`	Show all funding sources.

Script parameters

Script parameters are additional key value pairs you can add to the script tag to provide information you need.

Script Parameters

data-csp-nonce

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

Option	Description
`data-csp-nonce`	CSP single-use token used to render the button.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-csp-nonce="MY_CSP_NONCE">

data-client-token

Client token used to identify your buyers.

Option	Description
`data-client-token`	Client token used for identifying your buyers.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-client-token="abc123xyz=="></script>

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.

Option	Description
`data-page-type`	Log page type and interactions for the JavaScript SDK.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-page-type="product-details"></script>

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:

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

Option	Description
`data-partner-attribution-id`	Partner attribution ID used for revenue attribution.

1<script src="https://sandbox.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID" data-partner-attribution-id="MY_PARTNER_ATTRIBUTION_ID"></script>

data-user-id-token

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

Option	Description
`data-user-id-token`	Attribute to pass the `id_token` from your server into the JavaScript SDK. The OAuth 2.0 API to retrieve an `access_token` has an additional parameter, `response_type`, that can be set to `id_token`.

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

Next steps & customizations

Get started testing, add security to your checkout experience or create customizations for your audience.

Optional

JSSDK Complete Reference

Dynamically exposes objects and methods.

Optional

Performance Optimization

Optimize loading the JavaScript SDK.