Skip to content

Troubleshoot your Integration


Learn how to optimize loading the script and rendering the buttons for the best performance.

Script tag

Load the Payment Widget script from only. Reasons include:

  • The script is dynamically bundled, based on your client ID and on the current buyer. It includes only the specific code, images, localization, and other resources needed and does not slow down your page with unnecessary code. This approach is not possible with a statically distributed script.

  • The script also loads inside the button iframe and Checkout popup window to communicate with the parent window. Loading from means your users' browsers cache the script and there is no need to download the script again inside the iframe or popup.

  • Security updates and bug fixes are instantly available to your users.

  • Conversion updates to drive extra sales and revenue through are instantly available.

  • Backwards compatibility with previous versions of the script is guaranteed.

Minified script

The script is minified by default. To disable this for development purposes only, add debug=true to the script URL.

Instant render

If you are rendering the button immediately on the page after it loads, you should:

  1. Load the script prior to the element you want to render into:

    <script src=""></script>
  2. Call paypal.Buttons().render('#container') as soon as possible when the container element is ready:

    <div id="paypal-button-container"></div>
  3. For a bonus performance boost, load the script asynchronously on a page that precedes the Checkout page. This approach pre-caches the script, making future loads/renders instantaneous:

    <!-- Place on one of your landing pages or pre-checkout pages -->
        src="" async>

Delayed render

If your app renders on the client-side, or there is a user action on the page that triggers displaying the button (like opening a cart or selecting a radio button), you should:

  1. Load the script asynchronously in your page:

      <script src=""></script>

    Alternatively, use JavaScript to asynchronously load the script:

      var PAYPAL_SCRIPT = '';
      var script = document.createElement('script');
      script.setAttribute('src', PAYPAL_SCRIPT);
  2. Call paypal.Buttons().render('#container') on the client-side render, route-change, or user action that you want to trigger displaying the button:

    <div id="paypal-button-container"></div>
         .addEventListener('click', function() {

    Alternatively, to ensure the button completely loads by the time it displays, render the button in advance in a hidden container, and display it on the page-change or user action:

    <div id="paypal-button-container"></div>
         .style.display = 'none';
         .addEventListener('click', function() {
             .style.display = 'block';

Browser Support

Supported browsers

Support is guaranteed for the following browsers. For any browsers not on this list, the buttons could continue work, but compatibility is not guaranteed.


  • Chrome version 41 and later
  • Firefox version 43 and later
  • Safari version 8 and later
  • Opera version 12 and later
  • Edge version 14 and later
  • Internet Explorer version 11 and later


  • Chrome version 41 and later
  • Firefox version 15 and later
  • Safari version 9 and later
  • Samsung Browser 8.2 and later
  • Silk Browser 72 and later

Browser features and polyfills

The JavaScript SDK works as a standalone script, with no strict requirement for installing polyfills. However, if you use features such as fetch or Promise in your integration to call your server or run asynchronous tasks, you might need to install a polyfill to allow your app to work in older browsers.

Content security policy rules

The Smart Payment Buttons rely on rendering style and script tags on the page inside the button iframe. These tags might be blocked by your Content Security Policy rules. To avoid this:

  1. Send a nonce for both script-src and style-src directives:

    Content-Security-Policy: script-src 'nonce-xyz123'; style-src 'nonce-xyz123';

  2. Pass the nonce to the script tag:

    <script src="" data-csp-nonce="xyz-123">

Web views

  • If your site loads in a third-party web view, for example, if a buyer views your store after clicking a link on a social media mobile app, the Smart Payment Buttons continue to work.
  • recommends against loading your own site in a web view. This integration style is unsupported.

Smart Payment Buttons continue to work if popup blockers are active. However, recommends that you do not use popup blockers with this integration.