Best Practices Guide

PayPal recommends these best practices for Express Checkout integrations:

Buyer checkout experience and flow

Buyer experience best practices improve checkout speed, and reduce checkout friction and the drop-off rate:

Implement JavaScript-based checkout

To increase conversions and personalize the buyer's checkout experience, implement PayPal's JavaScript-based checkout flow in all your PayPal checkout integrations. The checkout.js script keeps the buyer on your site during the entire checkout and provides smart button capabilities. As PayPal's flagship integration experience grows, your integration scales with all future innovations and improvements delivered by PayPal. To start your integration, see Add the PayPal Button.

Note: Integrations using static buttons and full-page redirects are deprecated, however PayPal supports existing integrations.

Implement "Pay Now"

This checkout flow displays a Pay Now button immediately after the customer finishes interacting with the PayPal window. This reduces both the number of steps in the checkout process and the drop-off rate. Always implement the Pay Now experience when:

  • You know the final amount of the order before PayPal checkout begins.
  • Your website collects shipping and billing information before PayPal checkout begins.

To experience the Pay Now checkout flow, try it in the PayPal Demo Store.

Choose the optimal button location

To increase conversion rates, choose the best location for the PayPal button on your site:

Add the PayPal Checkout button to your product page or shopping cart

Tip: Place the PayPal button upstream on your product page or shopping cart page to create a faster checkout flow and reduce friction for the buyer.

You can place the PayPal button upstream on your product page or on your shopping cart page so that it's visible before your customer starts the checkout flow.

When a customer is ready to make a purchase, they simply click the conveniently located PayPal Checkout button. The billing and shipping information is automatically provided from the customer's PayPal account. This saves the customer the time of manually entering this information. The customer only needs to review the information and then confirm the purchase.

If necessary, the customer can change the billing or shipping information before they confirm. Because the information can be modified, the sales and shipping amounts are not shown as part of this flow.

See an example of shopping cart placement in the PayPal Demo Store.

Add PayPal alongside other funding instruments on a shopping cart page

On a shopping cart page where you offer multiple funding options, use a radio button to display the PayPal acceptance mark alongside other funding instruments. In this scenario, the PayPal acceptance mark and button appear at the end of the checkout flow.

The customer enters their billing and shipping information on your shopping cart page and then clicks the radio button to choose PayPal to complete their purchase. A confirmation page displays the total amount of the purchase, including shipping and tax information. Because the shipping information is provided from your shopping cart page and not by PayPal, this information cannot be changed. The customer confirms the information and clicks the PayPal Pay Now button.

See a PayPal acceptance mark in the PayPal Demo Store. In demo, click Proceed to Checkout.

Get the code example to add a PayPal acceptance mark to your site.

Enable Guest customers to checkout with PayPal

Allow customers to check out as a guest and choose PayPal as their payment option. Using the data provided by PayPal, the customer can optionally create an account as the final step of the checkout process.

To experience a guest checkout, try it in the PayPal Demo Store.

Enable Guest credit card payments

Allow customers to make guest credit card payments by simply redirecting your buyers to PayPal. The web flow automatically provides this feature by default. To pay with a credit card, customers click the slider on the bottom-right side of the screen.

Merchant benefits

  • PayPal-provided PCI compliance because credit card information is collected on
  • PayPal security for your credit-card paying customers.
  • Global acceptance as guest payments are available internationally.

For details, see Buyers Can Checkout Without a PayPal Account.

Pass line item details in API calls

PayPal recommends that you pass line item details such as item name, quantity, cost, shipping cost, discounts, taxes, and so on, in the createPayment and executePayment (REST), setEC, and doEC (NVP). This has three benefits:

  • Buyers are not confused by the price because they can see the line item details.
  • Buyers can see the line item details in the email PayPal sends when a transaction completes.
  • As a merchant, you also see the line item details in your PayPal transaction history. This helps you track and reconcile with your own systems.

Note: If you provide PayPal a user's itemized shopping cart list and a mismatch occurs between the sum of those items and the transaction total, PayPal processes the transaction using the sum of the cart items only when the difference is within $0.50.

Handle insufficient funds error

If the buyer’s selected funding source fails with an instrument declined error (REST) or with an error code 10486 (NVP/SOAP), implement the recovery process in the onAuthorize function of the checkout.js JavaScript. The recovery process lets the buyer choose another funding source instantly while staying on the same webpage.

For more information, see Redirect for alternate funding source.

Improve the mobile experience with the viewport tag

Using the viewport meta tag enables the browser to render the width of the web page to the width of the physical screen. This is useful for mobile screens where mobile browsers usually render the web page wider than the actual screen. For example usage, see the HTML head element in the add the script to your client section.

Account configuration

Account configuration best practices improve global conversions, avoid declined transactions, and help you manage your account more effectively:

Review payment receiving preferences

PayPal helps you accept payments globally and provide a native checkout experience to global buyers. This increases conversions and cross-border sales.

Review and configure these settings from your PayPal account:

  • Invoice ID: If your systems pass an invoice ID to PayPal, review the setting, because PayPal, by default, will block payments if you pass a duplicate invoice ID. For further details, see Block accidental payments.
  • Credit card statement name: PayPal recommends that you review the business name that will appear on the buyer’s statement. If you have multiple businesses or websites, use our dynamic descriptors to post the business name that appears on the buyer’s statement. See Add your credit card statement name for more information.
  • International payments: If your business has an international presence, review the settings that affect how you get paid. By default, PayPal allows you to receive payments from international PayPal customers and maintain non-USD currency balances. For details, see Block payments from payers with non-U.S. PayPal accounts.

Check the accuracy of the business category and subcategory of your PayPal account

To avoid transaction declines, review the category and sub-category under the business information section on your production account to ensure these values are accurate. This setting dictates your Merchant Category Code (MCC), which is then relayed to the processor. The processor uses this information, along with other transaction data, to accept or reject the transaction.

For more information, go to the business profile page for your account.

Define a generic email address or distribution list for a PayPal account

To effectively manage your account, use a generic email address, such as This prevents disruption of service or confusion if an individual whose email address is associated with the account leaves your company, or their email ID becomes inactive.

To manage your account's email address, or add an address, go to the email page in your PayPal profile.

Payment capture

Payment capture best practices help you secure payment from buyers:

Provide graceful handling for "Internal Server" or "PayPal Unavailable" errors

If your API request returns an internal server error code (REST - 500 or NVP - 10001), attempt the request three more times. Make sure you pass the same request ID (REST) or the msgsubid (NVP), on the retries to enforce idempotency. If communication still doesn’t work, provide a graceful exit to your buyer with an appropriate error message.

Capture funds before shipping

PayPal honors funds for three days after an authorization. To ensure payment, capture funds within the three-day honor period. If you try to capture funds after the honor period and the authorization fails, your request to capture funds may be declined. Therefore, always ship the product after funds are successfully captured.

Authorize before the customer leaves the website

If you use the Order payment type, note that the buyer consents to the purchase, but the funds are not placed on hold. Because the funds are held, PayPal recommends that you secure the buyer's authorization before they leave your website. This lets you confirm the buyer has adequate funds to pay for the items in their cart.

Performance and analytics

Performance and analytics best practices enable you to track button clicks and improve button rendering performance.

Add click tracking

Customize this code to send clicks to your preferred tracking platform:

    PayPal Button - Click Tracking

    1. Pass an `onClick` callback to the PayPal Button, which will be called for any clicks
    2. From there, call your preferred analytics service


    payment: function(data, actions) {

    onAuthorize: function(data, actions) {

    onClick: function() {

        // This handler will be called for every click on the PayPal button
        // Fire off any analytics beacons from here

        // Google analytics example (taken from

        ga('send', {
            hitType: 'event',
            eventCategory: 'Checkout',
            eventAction: 'button_click'
}, '#paypal-button-container');

Improve performance

Improve checkout.js and button rendering performance as described in the Performance Best Practices PayPal Checkout GitHub repo.


Customize the Express Checkout button.