Integrating Express Checkout Buttons and Logos

PayPal hosts the PayPal button and logo images that you use on your website. Using PayPal's Express Checkout buttons and logos is convenient and helps standardize the appearance of pages that use PayPal as a payment option.

PayPal Button and Logo Images

To inform buyers that PayPal is accepted on your website, you must place PayPal button and logo images in your checkout flow. PayPal recommends that you use dynamic images.

PayPal requires that you use Check out with PayPal buttons and PayPal mark images hosted on secure PayPal servers. When the images are updated, the changes appear automatically in your application. Do not host copies of the PayPal images locally on your servers. Outdated PayPal buttons and images reduce buyer confidence in your site.

Express Checkout Image Flavors

The Check out with PayPal button and the PayPal mark image are available in two flavors:

  • Dynamic image
  • Static image

The dynamic images enable PayPal to change their appearance dynamically. If, for example, you have signed up to participate in a PayPal campaign, PayPal can change the appearance of the image dynamically for the duration of that campaign based on parameter information you append to the image URL.

The static images cannot be changed dynamically. To participate in a PayPal campaign, you would have to manually update the image code to change the image displayed and restore the default image when the campaign is over. The only way you can have image management taken care of for you is to replace static images in your implementation with dynamic images.

Express Checkout Images

The Check out with PayPal button is the image you place on your shopping cart page. The US version of the image looks like this.


To create an Express Checkout button, see https://www.paypal.com/us/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal also provides buttons for other countries. To locate a page for another country, replace the country abbreviation in the link with another country abbreviation. For example, replace us with uk for United Kingdom, as follows: https://www.paypal.com/uk/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal hosts images for the countries:

Table 1. Country-specific buttons and images
Country URL Change Country URL Change Country URL Change Country URL Change
Australia au Austria at Belgium be Canada ca
China cn France fr Germany de Italy it
Japan j1 Netherlands nl Poland pl Spain es
Switzerland ch United Kingdom uk United States us    

Note: URL changes are case sensitive. The abbreviation in the URL may not be a country code.

Payment Mark

The PayPal mark is the image you place on your payment methods page. It looks like this:


To implement PayPal as a payment option, which is part of the Express Checkout experience, associate the PayPal mark image with your payment options. PayPal recommends using radio buttons for payment options:


To create a PayPal mark, see https://www.paypal.com/cgi-bin/webscr?cmd=xpt/Marketing/general/OnlineLogoCenter-outside.

Dynamic Images

To use dynamic images, you must pass information to PayPal as parameters appended to the image URL. Your unique ID tells PayPal whether or not you are participating in events that require image changes. Other information you pass instructs PayPal on the types of images to return.

If, for example, you are participating in a PayPal campaign that you have signed up for with PayPal and you have passed the appropriate parameter information to PayPal, PayPal automatically updates the image to reflect the campaign information. When the campaign is over, PayPal restores the default image. You are not responsible for scheduling or making changes to your website application code before, during, or after the campaign. Because you set up the dynamic image, PayPal handles these activities for you.

If you require localized campaign images, you can have the localized button image display for each country in which you participate. Simply assign the correct code for the country to the locale parameter you append to the dynamic image URL. PayPal returns to the default button image associated with each locale when the campaign is not available.

Configuring the Dynamic Image

To set up the dynamic image, provide the name-value pair parameter information in the image URL. You can pass information in the image URL for each option.

Set Up the Default Image

The following URL points to the default Check out with PayPal image:

https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image

To make the image dynamic, you need only add parameters to this URL to specify the changes you want displayed.

To test in the Sandbox environment, send the image to the following Sandbox URL:

https://fpdbs.sandbox.paypal.com/dynamicimageweb?cmd=_dynamic-image

Set Up Image for Dynamic Use

To set up the image URL for dynamic use, associate the URL with your PayPal Secure Merchant Account ID, or pal. Use the Secure Merchant Account ID in your Profile or call GetPalDetails.

This is an example call to GetPalDetails request.

Request Parameters

[requiredSecurityParameters]
&METHOD=GetPalDetails

Response Parameters

This GetPalDetails response returns the value of PAL and your country code (LOCALE).

[successResponseFields]
&PAL=SFJCXFDLNFR5U
&LOCALE=en_US
  1. Append the pal parameter to the image URL, and set the parameter to the value of your encrypted PayPal merchant account number.

    https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image&pal=SFJCXFDLNFR5U

  2. You can optionally change the value of LOCALE. See Change the Locale for details.
  3. Place the URL with parameter information at the appropriate image locations in your web application.

    The pal alerts PayPal to campaigns in which you are participating. PayPal obtains this information from your account and replaces the default image with the appropriate campaign image during the relevant campaign.

Note: If you pass in a pal value for a merchant account that is not yours, PayPal displays the image for that account. Be sure to pass the pal value for your account.

Change the Locale

To specify the locale of the image, append the locale parameter set to the code for the appropriate country to the image URL. If a country does not have a localized image or if you do not pass a locale value, the default US image displays. This example displays the image for the Spanish locale:

https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image&pal=SFJCXFDLNFR5U&locale=es_ES

If you are participating in a campaign across multiple countries, you can set the image locale for each country in which you participate. PayPal returns the default image associated with the locale when the campaign is over.

Provide Incentive Eligibility Feedback to Buyer

Pass the order total amount in the ordertotal parameter so PayPal can determine if the buyer is eligible for an incentive. Say, for example, that you are participating in a campaign in which the buyer is eligible for a 20% discount when their order meets a minimum of $50.00. You can pass that value to PayPal in the ordertotal parameter, as shown here:

https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image&pal=SFJCXFDLNFR5U&ordertotal=50.00

When a buyer's order meets or exceeds $50.00, PayPal displays the incentive image informing the buyer of their eligibility for the discount. When a buyer's order is less than $50.00, PayPal displays the default image.

Note: If ordertotal is not passed, PayPal does not display the incentive image even if the buyer is eligible for the incentive.

Choose the Image

To specify the image that you want to display, set the value of buttontype. This example sets buttontype to the PayPal mark image:

https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image&pal=SFJCXFDLNFR5U&buttontype=ecmark

The default value for buttontype is ecshortcut.

Dynamic Image Command Reference

To set up the information that enables dynamic images, add parameters to the dynamic image URL.

Dynamic Image Parameters

pal (Optional) The encrypted PayPal account number. When merchants sign up for a PayPal business account, PayPal assigns them an account number. The pal value represents the pay-to merchant account, not a third party making the API request on behalf of this merchant. By default, PayPal displays the default Check out with PayPal button.
ordertotal (Optional) The total cost of the order to the buyer. If shipping and sales tax are known, include them in this value. If not, this value should be the current subtotal of the order. By default, PayPal does not display the incentive image even if the buyer is eligible for the incentive.

Character length and limitations: Must not exceed $10,000.00 USD in any currency. Do not specify the currency symbol.You must include two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma(,).

locale (Optional) The five-character locale code. See Locale Codes and Priorities. Any other values default to US.
Note:

The merchant can participate in one campaign per country.

buttontype (Optional) Indicates a dynamic image. The values are:
  • Check out with PayPal button image: ecshortcut (default)
  • PayPal mark image: ecmark

Locale Codes and Priorities

A country code is the two-letter code for the country. Language priority is the language associated with the country code, where language_0 is the default priority.

Country code

Language priority Locale
AT language_0 de_DE
AT language_1 en_US
AU language_0 en_AU
BE language_0 en_US
BE language_1 nl_NL
BE language_2 fr_FR
C2 language_0 en_US
C2 language_1 zh_XC
C2 language_2 fr_XC
C2 language_3 es_XC
CH language_0 de_DE
CH language_1 fr_FR
CH language_2 en_US
CN language_0 zh_CN
default language_0 en_US
default language_1 fr_XC
default language_2 es_XC
default language_3 zh_XC
DE language_0 de_DE
DE language_1 en_US
ES language_0 es_ES
ES language_1 en_US
FR language_0 fr_FR
FR language_1 en_US
GB language_0 en_GB
GF language_0 fr_FR
GF language_1 en_US
GI language_0 en_US
GP language_0 fr_FR
GP language_1 en_US
IE language_0 en_US
IT language_0 it_IT
IT language_1 en_US
JP language_0 ja_JP
JP language_1 en_US
MQ language_0 fr_FR
MQ language_1 en_US
NL language_0 nl_NL
NL language_1 en_US
PL language_0 pl_PL
PL language_1 en_US
RE language_0 fr_FR
RE language_1 en_US
US language_0 en_US
US language_1 fr_XC
US language_2 es_XC
US language_3 zh_XC

Static PayPal Button and Mark Images

Using the static image code on the PayPal servers eliminates the need for you to maintain them yourself. PayPal recommends that you use dynamic images, an advanced feature, instead of static images.

You can use static images initially for testing and later switch to dynamic images. PayPal requires that you use the Check out with PayPal and the PayPal mark images hosted on secure PayPal servers. When the images are updated, the changes appear automatically in your application.

Do not host copies of the PayPal images locally on your servers. Outdated PayPal images reduces buyer confidence in your site.

Follow the links in this table to obtain HTML code that displays the PayPal-hosted images.

Table 2. HTML Code for Displaying PayPal-Hosted Button and Mark Images
Country Links to HTML Code for Displaying PayPal-Hosted Images
Australia https://www.paypal.com/au/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Austria https://www.paypal.com/at/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Belgium https://www.paypal.com/be/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Canada https://www.paypal.com/ca/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
China https://www.paypal.com/cn/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
France https://www.paypal.com/fr/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Germany https://www.paypal.com/de/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Italy https://www.paypal.com/it/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Japan https://www.paypal.com/j1/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Netherlands https://www.paypal.com/nl/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Poland https://www.paypal.com/pl/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Spain https://www.paypal.com/es/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Switzerland https://www.paypal.com/ch/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
United Kingdom https://www.paypal.com/uk/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
United States https://www.paypal.com/us/cgi-bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside