Dynamic Image Integration
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.
Dynamic images enable PayPal to tailor the Express Checkout button for a campaign or event. This feature is not supported for Mobile Express Checkout.
When you participate in a PayPal campaign or event, 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. These activities are all handled for you when you set up the dynamic image.
PayPal hosts the PayPal buttons and logo images that you use on your website. Using only hosted buttons and images standardizes their appearance on websites that use PayPal as a payment option, which is convenient for you and gives your buyers confidence that their transaction will be safe and secure.
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 available option.
- Set Up the Default Image
- Set Up Image for Dynamic Use
- Change the Locale
- Provide Incentive Eligibility Feedback to Buyer
- Choose the Image
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 test in the sandbox environment, send the image to the following Sandbox URL:
https://fpdbs.sandbox.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.
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
(See NVP/SOAP API References - Express Checkout - GetPalDetails).
This is an example call to GetPalDetails
request.
Request Parameters
[requiredSecurityParameters] &METHOD=GetPalDetails
This GetPalDetails
response returns the value of PAL
and your language and country code (LOCALE
).
Response Parameters
[successResponseFields] &PAL=SFJCXFDLNFR5U &LOCALE=en_US
- 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
- You can optionally change the value of
LOCALE
. See Change the Locale for details. - 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 thePAL
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. When the campaign is over, PayPal returns the default image associated with the locale.
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. If, for example, you are participating in a campaign in which buyers are 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 his/her 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: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period ( |
locale |
(Optional) The five-character locale code. See Locale Codes and Priorities. Any other values default to Note: The merchant can participate in one campaign per country. |
buttontype |
(Optional) Indicates a dynamic image. The values are:
|
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 | Country name | Language priority | Locale |
---|---|---|---|
AT | AUSTRIA | language_0 | de_DE |
AT | AUSTRIA | language_1 | en_US |
AU | AUSTRALIA | language_0 | en_AU |
BE | BELGIUM | language_0 | en_US |
BE | BELGIUM | language_1 | nl_NL |
BE | BELGIUM | language_2 | fr_FR |
C2 | CHINA | language_0 | en_US |
C2 | CHINA | language_1 | zh_XC |
C2 | CHINA | language_2 | fr_XC |
C2 | CHINA | language_3 | es_XC |
CH | SWITZERLAND | language_0 | de_DE |
CH | SWITZERLAND | language_1 | fr_FR |
CH | SWITZERLAND | language_2 | en_US |
CN | CHINA | 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 | GERMANY | language_0 | de_DE |
DE | GERMANY | language_1 | en_US |
ES | SPAIN | language_0 | es_ES |
ES | SPAIN | language_1 | en_US |
FR | FRANCE | language_0 | fr_FR |
FR | FRANCE | language_1 | en_US |
GB | UNITED KINGDOM | language_0 | en_GB |
GF | FRENCH GUIANA | language_0 | fr_FR |
GF | FRENCH GUIANA | language_1 | en_US |
GI | GIBRALTAR | language_0 | en_US |
GP | GUADELOUPE | language_0 | fr_FR |
GP | GUADELOUPE | language_1 | en_US |
IE | IRELAND | language_0 | en_US |
IT | ITALY | language_0 | it_IT |
IT | ITALY | language_1 | en_US |
JP | JAPAN | language_0 | ja_JP |
JP | JAPAN | language_1 | en_US |
MQ | MARTINIQUE | language_0 | fr_FR |
MQ | MARTINIQUE | language_1 | en_US |
NL | NETHERLANDS | language_0 | nl_NL |
NL | NETHERLANDS | language_1 | en_US |
PL | POLAND | language_0 | pl_PL |
PL | POLAND | language_1 | en_US |
RE | REUNION | language_0 | fr_FR |
RE | REUNION | language_1 | en_US |
US | UNITED STATES | language_0 | en_US |
US | UNITED STATES | language_1 | fr_XC |
US | UNITED STATES | language_2 | es_XC |
US | UNITED STATES | language_3 | zh_XC |