Advanced In-Context JavaScript settings

Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.

Configure advanced settings for manual, AJAX, conditional, or Mark integrations.

Manual or AJAX integrations

If you call In-Context API functions with AJAX from the browser or from a Flash application, you may want to manually initiate the checkout experience. Use the click setting, and call paypal.checkout.initXO, paypal.checkout.startFlow, and paypal.checkout.closeFlow:

paypal.checkout.setup('<Your-Merchant-ID>', {
  environment: 'sandbox',
  container: 'myContainer',
  click: function () {

    var action = $.post('/set-express-checkout');

    action.done(function (data) {
    }); () {

Important: Use the click function. Otherwise, browsers enforce the pop-up blocker.

Note: You must call paypal.checkout.initXO(); for asynchronous AJAX integrations only.

Try It! Asynchronous AJAX — The Express Checkout token is generated and passed back from the AJAX call.

Conditional or Mark integrations

If there is a pre-condition that must occur before the PayPal In-Context flow is initiated, such as Mark integrations, use the condition setting. For example, if you have a checkout page with a radio selection of payment methods, one of which is PayPal, you can use the following condition:

paypal.checkout.setup('<Your-Merchant-ID>', {
  environment: 'sandbox',
  buttons: 'myContainer',
    condition: function () {
      return !!document.getElementById('paypal-option').checked;

Try It! Regular Mark integration with no AJAX

Mark integration with synchronous AJAX

Mark integration with asynchronous AJAX

Debugging tips

Turn on console debugging logs:

  • Open the console panel in your browser developer tools.
  • Enter this commend in your console input:

    Note: The console setting is case-sensitive.

  • Refresh the page.

Browser support

In-Context Checkout is supported in most modern browsers. Older browser versions default to the full-page checkout experience. Smart phones and tablets display an optimized full-page experience.

Review the list of supported browsers.

Note: For Internet Explorer, PayPal recommends adding <!DOCTYPE html> and <meta http-equiv="X-UA-Compatible" content="IE=edge" /> to the page that initiates the flow. This disables Internet Explorer's Quirks Mode and Compatibility View.

API overview



paypal.checkout.setup('<Merchant-ID>', <{...}>);

The Merchant-ID is an alphanumeric string that is the PayPal Account Merchant ID as found in the PayPal Account Profile.

Note: A merchant ID is required for this integration. You can look up your merchant ID by logging into

Click your profile name in the top right corner of your account and then click Account Settings.

Click My business info on the left, and the Merchant account ID is displayed in the list of profile items on the right.

The second input parameter must be an object. Available properties are:

Parameter Values Type Description
locale Supported locales String OPTIONAL
The locale code of the country and language you would like displayed on the button. Defaults to en_US.
environment production String OPTIONAL
Defaults to the live production environment if omitted. Set it to sandbox for the testing environment. To go live after testing, remove this setting or change it from sandbox to production.
buttons Buttons Array Array OPTIONAL
An array of button objects. Each object represents a button on a page.
Event Type Description
click function OPTIONAL
A function that runs when the button is clicked. Commonly used with Manual or AJAX integrations.
condition function OPTIONAL
Indicates whether a condition is met. Valid value is true or false. Commonly used with Mark integrations.



Used to initiate the PayPal Window/Lightbox after the click event for Manual or AJAX integrations.



Used to start the PayPal session after the token is retrieved through AJAX integrations.

Parameter Type Description
url or token string REQUIRED
Either the URL or the token may be provided as input. If you specify a token, the script generates the URL for you.



If the click events function returns an error from the API instead of a token, the paypal.checkout.closeFlow(); function will gracefully close the PayPal Window.

Supported locales

For the locale setting, currently, the PayPal JavaScript button supports the following locales: en_US, en_AU, en_GB, fr_CA, es_ES, it_IT, fr_FR, de_DE, pt_BR, zh_CN, da_DK, zh_HK, id_ID, he_IL, ja_JP, nl_NL, no_NO, pl_PL, pt_PT, ru_RU, sv_SE, th_TH, zh_TW.

To display the button in a specified language, set locale to a supported locale. For example, set locale to en_US to display PayPal Check Out on the button and set locale to de_DE to display PayPal Zur Kasse on the button.

Buttons array

The buttons array of button objects displays one or more PayPal buttons on the page.

buttons: [
    container: 'id',
    type: 'checkout',
    color: 'gold',
    size: 'small',
    shape: 'pill'
Parameter Values Type Description
container See below String REQUIRED
HTML Element or ID of container elements in which the PayPal JavaScript button will be generated.
type checkout String OPTIONAL
Type of PayPal button to display. Defaults to checkout if omitted.
color Button color guidelines String OPTIONAL
Color of the PayPal button to display. Defaults to gold if omitted.
size Button size guidelines String OPTIONAL
Size of button to display. Defaults to small if omitted.
shape Button shape guidelines String OPTIONAL
Shape of button to be displayed. Defaults to pill if omitted.
click null function OPTIONAL
Overrides the behavior when the button is clicked. It is used for AJAX call use cases.
condition null function OPTIONAL
Function that returns a boolean value of True or False determining whether the PayPal in-context experience is invoked when the button is clicked. Used for Mark integrations.

The container parameter takes one of these values:

Value Type Example
ID of a HTML Element String '<ID>'
An HTML Element HTML Element document.getElementById('<ID>')
An array of IDs Array ['<ID1>', '<ID2>']
An array of HTML Elements Array [document.getElementById('<ID1>'), document.getElementById('<ID2>')]

PayPal Button Brand Guidelines


Set the color parameter to one of these values:

Value Description
gold Recommended
Gold is the color people around the world know us for and research confirms it. After extensive testing we found just the right shade and shape that help increase conversion. Use it on your website to take advantage of PayPal’s recognition and preference.
blue First alternate
If gold is not an option for your site, try the PayPal blue button. Research tells us people know it’s our brand color, which provides a halo of trust and security to your experience.
silver Second alternate
If gold or blue do not work for your site design or esthetic, try the silver button. We recommend this button as a second alternative, as the color is a bit recessive and less capable of drawing people’s attention.

Set the shape parameter to one of these values:

Value Description
pill Recommended
Whenever possible, use the pill-shaped button; it’s a unique and powerful shape that has grown to signify PayPal in people’s minds.
rect Use the rectangular button as an alternative for media such as mobile where pill-shaped buttons may pose some design challenges.

Set the size parameter to one of these values:

Value Dimensions Description
small 144 pixels by 39 pixels Recommended
The recommended size is small, which is the default if no value is set.
tiny 80 pixels by 20 pixels Displays PayPal on the button. For cases where a minimal button is required.
medium 226 pixels by 47 pixels Use when you need a larger PayPal button to match the sizes of similar buttons on the page.


After you configure your client, you initiate a payment.

Learn more