PayPal Checkout

Customize the PayPal JavaScript SDK Script

You can customize the integration by passing different query parameters to https://paypal.com/sdk/js. These parameters help PayPal decide the optimal funding sources and buttons to show to your buyers.

Option Example value Default Description
client-id sb required 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.
merchant-id ABC123 automatic The merchant for who you are facilitating a transaction.
currency USD, CAD, EUR USD The currency of the transaction. For subscriptions, this is the plan's currency.
intent capture, authorize capture The intent of the PayPal order. Determines whether the funds are captured after the buyer checks out, or if the buyer authorizes the funds to be captured later. Not applicable for subscriptions.
commit true, false true Set to true if the transaction is Pay Now, or false if the amount captured changes after the buyer returns to your site. Not applicable for subscriptions.
vault true, false false Set to true if the transaction sets up a billing agreement, subscriptions, or uses a vault.
components buttons buttons A comma-separated list of components to enable. Defaults to allow Smart Payment Buttons. Other components are optional.
disable-funding card,credit none Funding sources to disallow from showing in the Smart Payment Buttons.
disable-card visa,mastercard,amex none Cards to disable from showing in the Smart Payment Buttons.
integration-date 2018-11-30 automatic The date of integration. Used to ensure backwards compatibility.
locale en_US, fr_FR, de_DE automatic The locale used to localize any components. PayPal recommends not setting this parameter, as the buyer's locale is automatically set by PayPal.
buyer-country US, CA, GB, DE, FR automatic The buyer country. For testing purposes only.
debug true, false false Enable debug mode for ease of debugging. Do not enable for production traffic.

Client ID

The client ID identifies the PayPal account which sets up and finalizes transactions. By default, funds from any transactions are settled into this account.

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

If you are facilitating transactions on behalf of other merchants, and capturing funds into their accounts, see merchant ID.

Merchant ID

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

Use the this parameter only for partner, marketplaces, and cart solutions, when you are acting on behalf of another merchant to facilitate their PayPal transactions. This parameter is essential to guarantee the merchant sees the best possible combination of PayPal buttons.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=XXX"></script>
Integration Use case client ID merchant ID Other
Standalone Integration I am capturing funds directly into my PayPal account. Pass a client ID associated with your account. Do not pass merchant ID.
Partner or Marketplace Integration I am facilitating payments on behalf of other merchants. Pass a client ID associated with your partner or marketplace account. Pass the merchant ID of the merchant for whom you are facilitating payments. If you do not have the merchant ID, see Unknown Merchant ID.
Cart Integration I am facilitating payments on behalf of other merchants and I have the client IDs for those merchants. Pass the client ID of the merchant for whom you are facilitating payments. Do not pass a merchant ID. Pass the integration date parameter to ensure your integration does not break as new client IDs onboard to your site.

Unknown merchant ID

If you are facilitating a transaction on behalf of a merchant, but do not have their merchant ID, pass a value of unknown and swap it for the merchant ID when you obtain it.

Use one of the following options to backfill merchant IDs to pass to the PayPal script:

  • Follow one of the Seller Onboarding paths for the Partner integration.
  • Get the merchant ID from the response of the GetExpressCheckoutDetails API response, if you integrate with NVP or SOAP.
  • Get the merchant ID from the response of the /v1/payments/payment/PAYID-XXXX API response, if you integrate with /v1/payments.
  • Listen for completed payments using the PAYMENT.CAPTURE.COMPLETED webhook.

Currency

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

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=EUR"></script>
Currency Code
Australian dollar AUD
Brazilian real BRL
Canadian dollar CAD
Czech koruna CZK
Danish krone DKK
Euro EUR
Hong Kong dollar HKD
Hungarian forint HUF
Indian rupee INR
Israeli new shekel ILS
Japanese yen JPY
Malaysian ringgit MYR
Mexican peso MXN
New Taiwan dollar TWD
New Zealand dollar NZD
Norwegian krone NOK
Philippine peso PHP
Polish złoty PLN
Pound sterling GBP
Russian ruble RUB
Singapore dollar SGD
Swedish krona SEK
Swiss franc CHF
Thai baht THB
United States dollar USD

Intent

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

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&intent=authorize"></script>
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.
order (Legacy) The funds are authorized immediately, and then reauthorized or captured later.

Commit

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

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&commit=false"></script>
Option Description
true Show a Pay Now button in the PayPal Checkout flow. The final amount will not change after the buyer returns from PayPal to your site.
false Show a Continue button in the PayPal Checkout flow. The final amount might change after the buyer returns from PayPal to your site, due to extra shipping, tax, or other fees.

Vault

The vault status of the transaction. If set to true, shows only funding sources that you can add to the vault, or use to set up a billing agreement, reference transaction, or subscription. Defaults to false.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&vault=true"></script>
Option Description
true Show only funding sources that you can vault or use to create a billing agreement, subscription, or recurring payment.
false Show all funding sources.

Components

The PayPal components that you intend to render on your page. Must be a comma-separated list and defaults to buttons for the Smart Payment Buttons component.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons"></script>
Option Description
buttons Load the Smart Payment Buttons component in the script. }

Disable funding

The disabled funding sources for the transaction. Any funding sources passed are not displayed in the Smart Payment Buttons. By default, funding source eligibility is smartly decided based on a variety of factors.

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

  • Real money gaming merchants
  • Non-US merchants who do not have the correct licenses and approvals to display the Credit button
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&disable-funding=credit,card"></script>
Option Description
card Credit or debit cards
credit PayPal Credit
sepa SEPA-Lastschrift

Disable card

The disabled cards for the transaction. Any cards passed do not display in the Smart Payment Buttons. By default, card eligibility is smartly decided based on a variety of factors.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&disable-card=amex,jcb"></script>
Option Description
visa Visa
mastercard Mastercard
amex American Express
discover Discover
jcb JCB
elo Elo
hiper Hiper

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, and if passed, reflects the date that you added the PayPal integration to your site. This parameter ensures backwards compatibility.

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

How this works:

  • 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 do not need to change integration-date to enable new features.

  • Your site does not get any updates made to the PayPal script after the specified integration-date, or after the date your client-id was created, if you do not pass the integration-date parameter.

  • If your client-id does not change, you can safely omit the integration-date parameter and the PayPal script guarantees 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.

Debug

Set to true to enable debug mode. Debug mode is recommended only for testing and debugging, and causes a significant increase in the size of the script, and significant performance decrease. Defaults to false.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&debug=true"></script>
Option Description
true Enable debug mode.
false Disable debug mode.

Buyer country

The buyer country determines which funding sources are eligible for a given buyer. Defaults to the buyer's IP geolocation.

Note: Buyer country is valid only in sandbox and you should not pass it in production.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&buyer-country=DE"></script>

Any country that you can pass as a locale is a valid buyer country.

Locale

The locale renders components. By default PayPal smartly 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.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&locale=fr_FR"></script>
Country Locales
AD en_AD, fr_AD, es_AD, zh_AD
AE en_AE, fr_AE, es_AE, zh_AE, ar_AE
AG en_AG, fr_AG, es_AG, zh_AG
AI en_AI, fr_AI, es_AI, zh_AI
AL en_AL
AM en_AM, fr_AM, es_AM, zh_AM
AN en_AN, fr_AN, es_AN, zh_AN
AO en_AO, fr_AO, es_AO, zh_AO
AR es_AR, en_AR
AT de_AT, en_AT
AU en_AU
AW en_AW, fr_AW, es_AW, zh_AW
AZ en_AZ, fr_AZ, es_AZ, zh_AZ
BA en_BA
BB en_BB, fr_BB, es_BB, zh_BB
BE en_BE, nl_BE, fr_BE
BF fr_BF, en_BF, es_BF, zh_BF
BG en_BG
BH ar_BH, en_BH, fr_BH, es_BH, zh_BH
BI fr_BI, en_BI, es_BI, zh_BI
BJ fr_BJ, en_BJ, es_BJ, zh_BJ
BM en_BM, fr_BM, es_BM, zh_BM
BN en_BN
BO es_BO, en_BO, fr_BO, zh_BO
BR pt_BR, en_BR
BS en_BS, fr_BS, es_BS, zh_BS
BT en_BT
BW en_BW, fr_BW, es_BW, zh_BW
BY en_BY
BZ en_BZ, es_BZ, fr_BZ, zh_BZ
CA en_CA, fr_CA
CD fr_CD, en_CD, es_CD, zh_CD
CG en_CG, fr_CG, es_CG, zh_CG
CH de_CH, fr_CH, en_CH
CI fr_CI, en_CI
CK en_CK, fr_CK, es_CK, zh_CK
CL es_CL, en_CL, fr_CL, zh_CL
CM fr_CM, en_CM
CN zh_CN
CO es_CO, en_CO, fr_CO, zh_CO
CR es_CR, en_CR, fr_CR, zh_CR
CV en_CV, fr_CV, es_CV, zh_CV
CY en_CY
CZ cs_CZ, en_CZ, fr_CZ, es_CZ, zh_CZ
DE de_DE, en_DE
DJ fr_DJ, en_DJ, es_DJ, zh_DJ
DK da_DK, en_DK
DM en_DM, fr_DM, es_DM, zh_DM
DO es_DO, en_DO, fr_DO, zh_DO
DZ ar_DZ, en_DZ, fr_DZ, es_DZ, zh_DZ
EC es_EC, en_EC, fr_EC, zh_EC
EE en_EE, ru_EE, fr_EE, es_EE, zh_EE
EG ar_EG, en_EG, fr_EG, es_EG, zh_EG
ER en_ER, fr_ER, es_ER, zh_ER
ES es_ES, en_ES
ET en_ET, fr_ET, es_ET, zh_ET
FI fi_FI, en_FI, fr_FI, es_FI, zh_FI
FJ en_FJ, fr_FJ, es_FJ, zh_FJ
FK en_FK, fr_FK, es_FK, zh_FK
FM en_FM
FO da_FO, en_FO, fr_FO, es_FO, zh_FO
FR fr_FR, en_FR
GA fr_GA, en_GA, es_GA, zh_GA
GB en_GB
GD en_GD, fr_GD, es_GD, zh_GD
GE en_GE, fr_GE, es_GE, zh_GE
GF en_GF, fr_GF, es_GF, zh_GF
GI en_GI, fr_GI, es_GI, zh_GI
GL da_GL, en_GL, fr_GL, es_GL, zh_GL
GM en_GM, fr_GM, es_GM, zh_GM
GN fr_GN, en_GN, es_GN, zh_GN
GP en_GP, fr_GP, es_GP, zh_GP
GR el_GR, en_GR, fr_GR, es_GR, zh_GR
GT es_GT, en_GT, fr_GT, zh_GT
GW en_GW, fr_GW, es_GW, zh_GW
GY en_GY, fr_GY, es_GY, zh_GY
HK en_HK, zh_HK
HN es_HN, en_HN, fr_HN, zh_HN
HR en_HR
HU hu_HU, en_HU, fr_HU, es_HU, zh_HU
ID id_ID, en_ID
IE en_IE, fr_IE, es_IE, zh_IE
IL he_IL, en_IL
IN en_IN
IS en_IS
IT it_IT, en_IT
JM en_JM, es_JM, fr_JM, zh_JM
JO ar_JO, en_JO, fr_JO, es_JO, zh_JO
JP ja_JP, en_JP
KE en_KE, fr_KE, es_KE, zh_KE
KG en_KG, fr_KG, es_KG, zh_KG
KH en_KH
KI en_KI, fr_KI, es_KI, zh_KI
KM fr_KM, en_KM, es_KM, zh_KM
KN en_KN, fr_KN, es_KN, zh_KN
KR ko_KR, en_KR
KW ar_KW, en_KW, fr_KW, es_KW, zh_KW
KY en_KY, fr_KY, es_KY, zh_KY
KZ en_KZ, fr_KZ, es_KZ, zh_KZ
LA en_LA
LC en_LC, fr_LC, es_LC, zh_LC
LI en_LI, fr_LI, es_LI, zh_LI
LK en_LK
LS en_LS, fr_LS, es_LS, zh_LS
LT en_LT, ru_LT, fr_LT, es_LT, zh_LT
LU en_LU, de_LU, fr_LU, es_LU, zh_LU
LV en_LV, ru_LV, fr_LV, es_LV, zh_LV
MA ar_MA, en_MA, fr_MA, es_MA, zh_MA
MC fr_MC, en_MC
MD en_MD
ME en_ME
MG en_MG, fr_MG, es_MG, zh_MG
MH en_MH, fr_MH, es_MH, zh_MH
MK en_MK
ML fr_ML, en_ML, es_ML, zh_ML
MN en_MN
MQ en_MQ, fr_MQ, es_MQ, zh_MQ
MR en_MR, fr_MR, es_MR, zh_MR
MS en_MS, fr_MS, es_MS, zh_MS
MT en_MT
MU en_MU, fr_MU, es_MU, zh_MU
MV en_MV
MW en_MW, fr_MW, es_MW, zh_MW
MX es_MX, en_MX
MY en_MY
MZ en_MZ, fr_MZ, es_MZ, zh_MZ
NA en_NA, fr_NA, es_NA, zh_NA
NC en_NC, fr_NC, es_NC, zh_NC
NE fr_NE, en_NE, es_NE, zh_NE
NF en_NF, fr_NF, es_NF, zh_NF
NG en_NG
NI es_NI, en_NI, fr_NI, zh_NI
NL nl_NL, en_NL
NO no_NO, en_NO
NP en_NP
NR en_NR, fr_NR, es_NR, zh_NR
NU en_NU, fr_NU, es_NU, zh_NU
NZ en_NZ, fr_NZ, es_NZ, zh_NZ
OM ar_OM, en_OM, fr_OM, es_OM, zh_OM
PA es_PA, en_PA, fr_PA, zh_PA
PE es_PE, en_PE, fr_PE, zh_PE
PF en_PF, fr_PF, es_PF, zh_PF
PG en_PG, fr_PG, es_PG, zh_PG
PH en_PH
PL pl_PL, en_PL
PM en_PM, fr_PM, es_PM, zh_PM
PN en_PN, fr_PN, es_PN, zh_PN
PT pt_PT, en_PT
PW en_PW, fr_PW, es_PW, zh_PW
PY es_PY, en_PY
QA en_QA, fr_QA, es_QA, zh_QA, ar_QA
RE en_RE, fr_RE, es_RE, zh_RE
RO en_RO, fr_RO, es_RO, zh_RO
RS en_RS, fr_RS, es_RS, zh_RS
RU ru_RU, en_RU
RW fr_RW, en_RW, es_RW, zh_RW
SA ar_SA, en_SA, fr_SA, es_SA, zh_SA
SB en_SB, fr_SB, es_SB, zh_SB
SC fr_SC, en_SC, es_SC, zh_SC
SE sv_SE, en_SE
SG en_SG
SH en_SH, fr_SH, es_SH, zh_SH
SI en_SI, fr_SI, es_SI, zh_SI
SJ en_SJ, fr_SJ, es_SJ, zh_SJ
SK sk_SK, en_SK, fr_SK, es_SK, zh_SK
SL en_SL, fr_SL, es_SL, zh_SL
SM en_SM, fr_SM, es_SM, zh_SM
SN fr_SN, en_SN, es_SN, zh_SN
SO en_SO, fr_SO, es_SO, zh_SO
SR en_SR, fr_SR, es_SR, zh_SR
ST en_ST, fr_ST, es_ST, zh_ST
SV es_SV, en_SV, fr_SV, zh_SV
SZ en_SZ, fr_SZ, es_SZ, zh_SZ
TC en_TC, fr_TC, es_TC, zh_TC
TD fr_TD, en_TD, es_TD, zh_TD
TG fr_TG, en_TG, es_TG, zh_TG
TH th_TH, en_TH
TJ en_TJ, fr_TJ, es_TJ, zh_TJ
TM en_TM, fr_TM, es_TM, zh_TM
TN ar_TN, en_TN, fr_TN, es_TN, zh_TN
TO en_TO
TR tr_TR, en_TR
TT en_TT, fr_TT, es_TT, zh_TT
TV en_TV, fr_TV, es_TV, zh_TV
TW zh_TW, en_TW
TZ en_TZ, fr_TZ, es_TZ, zh_TZ
UA en_UA, ru_UA, fr_UA, es_UA, zh_UA
UG en_UG, fr_UG, es_UG, zh_UG
US en_US, fr_US, es_US, zh_US
UY es_UY, en_UY, fr_UY, zh_UY
VA en_VA, fr_VA, es_VA, zh_VA
VC en_VC, fr_VC, es_VC, zh_VC
VE es_VE, en_VE, fr_VE, zh_VE
VG en_VG, fr_VG, es_VG, zh_VG
VN en_VN
VU en_VU, fr_VU, es_VU, zh_VU
WF en_WF, fr_WF, es_WF, zh_WF
WS en_WS
YE ar_YE, en_YE, fr_YE, es_YE, zh_YE
YT en_YT, fr_YT, es_YT, zh_YT
ZA en_ZA, fr_ZA, es_ZA, zh_ZA
ZM en_ZM, fr_ZM, es_ZM, zh_ZM
ZW en_ZW

Feedback