HTML Variables for PayPal Payments Standard

This appendix provides reference information for all HTML variables supported by any kind of PayPal Payments Standard payment button:

  • Buy Now buttons
  • Add to Cart buttons
  • Buy Gift Certificate buttons
  • Subscribe buttons
  • Automatic Billing buttons
  • Installment Plan buttons
  • Donate buttons

Reference information for HTML variables supported by the Cart Upload command are also provided.

Read the following topics to learn about the kinds of HTML variables that you can use:

Technical HTML Variables

Technical HTML variables control how PayPal responds technically when people click PayPal Payments Standard payment buttons or when third-party or custom carts initiate payment processing with the Cart Upload command. They also control how your buttons interact with special PayPal features.

Note Refer to the buttons reference page for a list of PayPal hosted buttons. Use the HTML IMG tag to display the button on your web page. For example, <img alt="buy now with PayPal" border="0" src="https://www.paypalobjects.com/webstatic/en_US/btn/btn_buynow_pp_142x27.png" />.

Table 1. Allowable Values for the cmd HTML Variable
Value of cmd Description
_xclick The button that the person clicked was a Buy Now button.
_cart For shopping cart purchases. The following variables specify the kind of shopping cart button that the person clicked:
  • add – Add to Cart buttons for the PayPal Shopping Cart
  • display – View Cart buttons for the PayPal Shopping Cart
  • upload – The Cart Upload command for third-party carts
_oe-gift-certificate The button that the person clicked was a Buy Gift Certificate button.
_xclick-subscriptions The button that the person clicked was a Subscribe button.
_xclick-auto-billing The button that the person clicked was an Automatic Billing button.
_xclick-payment-plan The button that the person clicked was an Installment Plan button.
_donations The button that the person clicked was a Donate button.
_s-xclick The button that the person clicked was protected from tampering by using encryption, or the button was saved in the merchant's PayPal account. PayPal determines which kind of button was clicked by decoding the encrypted code or by looking up the saved button in the merchant's account.
Table 2. HTML Variables for Special PayPal Features
Name Required or Optional Description Character Length
notify_url Optional The URL to which PayPal posts information about the payment, in the form of Instant Payment Notification messages. 255
hosted_button_id See description. Required for buttons that have been saved in PayPal accounts; otherwise, not allowed.
The identifier of a button that was saved in a merchant's PayPal account. PayPal assigns the value when payment buttons are first created and saved in merchants' PayPal accounts.
Note: A merchant's PayPal account can have a maximum of 1,000 saved payment buttons.
See description.
bn Optional An identifier of the source that built the code for the button that the buyer clicked, sometimes known as the build notation. Specify a value using the following format:
<Company>_<Service>_<Product>_<Country>

Substitute <Service> with an appropriate value from the following list:

  • BuyNow
  • AddToCart
  • Donate
  • Subscribe
  • AutomaticBilling
  • InstallmentPlan
  • BuyGiftCertifcate
  • ShoppingCart

Substitute <Product> with WPS always for PayPal Payments Standard payment buttons and for the PayPal Payments Standard Cart Upload command.

Substitute <Country> with an appropriate two-letter country code from codes defined by the ISO 3166-1 standard.

For example, a Buy Now button on your website that you coded yourself might have the following line of code:

bn="DesignerFotos_BuyNow_WPS_US"

Note: HTML button code that you create on the PayPal website includes bn variables with valid values generated by PayPal.

HTML Variables for Individual Items

HTML variables for individual items specify information about a product or service for Buy Now and Add to Cart buttons, or they specify information about a contribution for Donate buttons.

Table 3. HTML Variables for Individual Items
Name Required or Optional Description Character Length
amount See description. The price or amount of the product, service, or contribution, not including shipping, handling, or tax. If this variable is omitted from Buy Now or Donate buttons, buyers enter their own amount at the time of payment.
  • Required for Add to Cart buttons
  • Optional for Buy Now and Donate buttons
  • Not used with Subscribe or Buy Gift Certificate buttons
discount_amount Optional Discount amount associated with an item.
It must be less than the selling price of the item. If you specify discount_amount and discount_amount2 is not defined, then this flat amount is applied regardless of the quantity of items purchased.
Valid only for Buy Now and Add to Cart buttons.
discount_amount2 Optional Discount amount associated with each additional quantity of the item.
It must be equal to or less than the selling price of the item. A discount_amount must also be specified as greater than or equal to 0 for discount_amount2 to take effect.
Valid only for Buy Now and Add to Cart buttons.
discount_rate Optional Discount rate (percentage) associated with an item.
It must be set to a value less than 100. If you do not set discount_rate2, the value in discount_rate applies only to the first item regardless of the quantity of items purchased.
Valid only for Buy Now and Add to Cart buttons.
discount_rate2 Optional Discount rate (percentage) associated with each additional quantity of the item.
It must be equal to or less 100. A discount_rate must also be specified as greater than or equal to 0 for discount_rate2 to take effect.
Valid only for Buy Now and Add to Cart buttons.
discount_num Optional Number of additional quantities of the item to which the discount applies.
Applicable when you use discount_amount2 or discount_rate2. Use this variable to specify an upper limit on the number of discounted items. Valid only for Buy Now and Add to Cart buttons.
item_name See description. Description of item. If this variable is omitted, buyers enter their own name during checkout.
  • Optional for Buy Now, Donate, Subscribe, Automatic Billing, Installment Plan, and Add to Cart buttons
  • Not used with Buy Gift Certificate buttons
127
item_number See description. Pass-through variable for you to track product or service purchased or the contribution made. The value you specify is passed back to you upon payment completion. This variable is required if you want PayPal to track inventory or track profit and loss for the item the button sells. 127
quantity Optional Number of items. If profile-based shipping rates are configured with a basis of quantity, the sum of quantity values is used to calculate the shipping charges for the payment. PayPal appends a sequence number to identify uniquely the item in the PayPal Shopping Cart, for example, quantity1, quantity2, and so on.
Note: The value for quantity must be a positive integer. Null, zero, or negative numbers are not allowed.
shipping Optional The cost of shipping this item. If you specify shipping and shipping2 is not defined, this flat amount is charged regardless of the quantity of items purchased.
This shipping variable is valid only for Buy Now and Add to Cart buttons.
Default – If profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose.
shipping2 Optional The cost of shipping each additional unit of this item. If this variable is omitted and profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose.
This shipping variable is valid only for Buy Now and Add to Cart buttons.
tax Optional Transaction-based tax override variable. Set this variable to a flat tax amount to apply to the payment regardless of the buyer's location. This value overrides any tax settings set in your account profile. Valid only for Buy Now and Add to Cart buttons. Default – Profile tax settings, if any, apply.
tax_rate Optional Transaction-based tax override variable. Set this variable to a percentage that applies to the amount multiplied by the quantity selected during checkout. This value overrides any tax settings set in your account profile. Allowable values are numbers 0.001 through 100. Valid only for Buy Now and Add to Cart buttons. Default – Profile tax settings, if any, apply. 6
undefined_ quantity Optional 1 – allows buyers to specify the quantity.
  • Optional for Buy Now buttons
  • Not used with other buttons
1
weight Optional Weight of items. If profile-based shipping rates are configured with a basis of weight, the sum of weight values is used to calculate the shipping charges for the payment.
Allowable values are decimals numbers, with 2 significant digits to the right of the decimal point.
weight_unit Optional The unit of measure if weight is specified.
Allowable values are:
  • lbs
  • kgs
The default is lbs.
on0 Optional First option field name and label. The os0 variable contains the corresponding value for this option field. For example, if on0 is size, os0 could be large.
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64
on1 Optional Second option field name and label. The os1 variable contains the corresponding value for this option field. For example, if on1 is color then os1 could be blue.
You can specify a maximum of 7 option field names (6 with Subscribe buttons) by incrementing the option name index (on0 through on6).
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64
os0 Optional Option selection of the buyer for the first option field, on0. If the option field is a dropdown menu or a set of radio buttons, each allowable value should be no more than 64 characters. If buyers enter this value in a text field, there is a 200-character limit.
Note: The option field on0 must also be defined. For example, it could be size.
For priced options, include the price and currency symbol in the text of the option selections, as the following sample code shows:
<option value="small">small - $10.00</option>

Add a corresponding option_select0 and option_amount0 variable for each priced option. Priced options are supported only for Buy Now and Add to Cart buttons. Only one dropdown menu option selection can have priced options.

  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
See description.
os1 Optional Option selection of the buyer for the second option field, on1. If the option field is a dropdown menu or a set of radio buttons, each allowable value should be no more than 64 characters. If buyers enter this value in a text field, there is a 200-character limit.

You can specify a maximum of 7 option selections (6 with Subscribe buttons) by incrementing the option selection index (os0 through os6). You can implement up to 5 option selections as dropdown menus and up to 2 option selections as test boxes.

Note: A corresponding option field (on0 through on6) must be defined.
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64 or 200
See description.
option_index See description. The cardinal number of the option field, on0 through on9, that has product options with different prices for each option. Include option_index if the option field with prices is not on0.
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
Default – 0
option_select0 Optional For priced options, the value of the first option selection of the on0 dropdown menu. The values must match exactly, as the following sample code shows:
<option value="small">small - $10.00</option>
...
<input type="hidden" name="option_select0" value="small">
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64
option_amount0 Optional For priced options, the amount that you want to charge for the first option selection of the on0 dropdown menu. Use only numeric values; the currency is taken from the currency_code variable. For example:
<option value="small">small - $10.00...
<input type="hidden" name="option_amount0"</option> value="10.00">
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64
option_select1 Optional For priced options, the value of the second option selection of the on0 dropdown menu. For example:
...
<option value="medium">small - $10.00</option>
...
<input type="hidden" name="option_select" value="medium">
You can specify a maximum of 10 option selections by incrementing the option selection index (option_select0 through option_select9).
Note: A corresponding option selection in os0 must also be set.
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64
option_amount1 Optional For priced options, the amount that you want to charge for the second option selection of the on0 dropdown menu. For example:
...
<option value="small">medium - $15.00</option>
...
<input type="hidden" name="option_amount1" value="15.00">
You can specify a maximum of 10 option amounts by incrementing the option amount index (option_amount0 through option_amount9).
Note: A corresponding option selection in os0 must also be set.
  • Optional for Buy Now, Add to Cart, Subscribe, Automatic Billing, and Installment Plan buttons
  • Not used with Donate or Buy Gift Certificate buttons
64

HTML Variables for Payment Transactions

HTML variables for payment transactions provide information about entire payments, regardless of the individual items involved with the payment. You can use these variables with Add to Cart buttons and the Cart Upload command.

Table 4. HTML Variables for Payment Transactions
Name Required or Optional Description Character Length
address_ override Optional 1 – The address specified with automatic fill-in variables overrides the PayPal member's stored address. Buyers see the addresses that you pass in, but they cannot edit them. PayPal does not show addresses if they are invalid or omitted.
For more information, see the HTML Variables for Filling Out PayPal Checkout Pages Automatically.
1
currency_code Optional The currency of the payment. The default is USD.
For allowable values, see Currencies Supported by PayPal.
3
custom Optional Pass-through variable for your own tracking purposes, which buyers do not see.
Default – No variable is passed back to you.
256
handling Optional Handling charges. This variable is not quantity-specific. The same handling cost applies, regardless of the number of items on the order.
Default – No handling charges are included.
invoice Optional Pass-through variable you can use to identify your invoice number for this purchase.
Default – No variable is passed back to you.
127
tax_cart Optional Cart-wide tax, overriding any individual item tax_x value

weight_cart Optional If profile-based shipping rates are configured with a basis of weight, PayPal uses this value to calculate the shipping charges for the payment. This value overrides the weight values of individual items.
Allowable values are decimals numbers, with 2 significant digits to the right of the decimal point.

weight_unit Optional The unit of measure if weight_cart is specified. Allowable values are:
  • lbs
  • kgs

The default value is lbs.

HTML Variables for Shopping Carts

HTML variables for shopping carts can be used with Add to Cart buttons, as well as with third-party shopping carts or custom carts that initiate payment processing with the Cart Upload command.

Table 5. HTML Variables for Shopping Carts
Name Required or Optional Description Character Length
add See description. Add an item to the PayPal Shopping Cart.

This variable must be set as follows:

add="1"

The alternative is the display="1" variable, which displays the contents of the PayPal Shopping Cart to the buyer.
If both add and display are specified, display takes precedence.

1
amount_x Required The amount associated with item x. To pass an aggregate amount for the entire cart, use amount_1.
Applies only to the Cart Upload command.

business Required Your PayPal ID or an email address associated with your PayPal account. Email addresses must be confirmed.

discount_amount_cart Optional Single discount amount charged cart-wide.
It must be less than the selling price of all items combined in the cart. This variable overrides any individual item discount_amount_x values, if present.
Applies only to the Cart Upload command.

discount_amount_x Optional The discount amount associated with item x.
It must be less than the selling price of the associated item. This amount is added to any other item discounts in the cart.
Applies only to the Cart Upload command.

discount_rate_cart Optional Single discount rate (percentage) to be charged cart-wide.
It must be set to a value less than 100. The variable overrides any individual item discount_rate_x values, if present.
Applies only to the Cart Upload command.

discount_rate_x Optional The discount rate associated with item x.
It must be set to a value less than 100. The variable takes into account all quantities of item x.
Applies only to the Cart Upload command.

display See description. Display the contents of the PayPal Shopping Cart to the buyer. This variable must be set as follows:
display="1"

The alternative is the add="1" variable, which adds an item to the PayPal Shopping Cart.
If both add and display are specified, display takes precedence.

1
handling_ cart Optional Single handling fee charged cart-wide. If handling_cart is used in multiple Add to Cart buttons, the handling_cart value of the first item is used.

item_name_x Required The name associated with item x. To pass an aggregate name for the entire cart, use item_name_1.
Applies only to the Cart Upload command.

paymentaction Optional Indicates whether the payment is a final sale or an authorization for a final sale, to be captured later.

Allowable values are:

  • sale
  • authorization
  • order

The default value is sale. Set the value to authorization to place a hold on the PayPal account for the authorized amount. Set the value to order to authorize the payment without placing a hold on the PayPal account.

TipImportant: If you set paymentaction to order, use the Authorization & Capture API to authorize and capture the payment payments. The Merchant Services on the PayPal website let you capture payments only for authorizations, not for orders.

shopping_url Optional The URL of the page on the merchant website that buyers go to when they click the Continue Shopping button on the PayPal Shopping Cart page.
For more information, see Sample HTML Code for Add to Cart Buttons that Continue Shopping on the Current Merchant Webpage.

upload See description Upload the contents of a third-party shopping cart or a custom shopping cart.

This variable must be set as follows:

upload="1"

The alternatives are the add="1" variable and the display="1" variables, which are used with the PayPal Shopping Cart.

1

HTML Variables for Recurring Payments Buttons

Recurring Payments buttons are:

  • Subscribe buttons
  • Automatic Billing buttons
  • Installment Plan buttons

HTML variables for recurring payments buttons set terms for different kinds of PayPal automatic payment plans.

Table 6. Subscribe Button HTML Variables
Name Required or Optional Description Character Length
business Required Your PayPal ID or an email address associated with your PayPal account. Email addresses must be confirmed.

item_name Optional Description of item being sold. If you are collecting aggregate payments, the value can be a summary of all items purchased, a tracking number, or a generic term such as "subscription." If this variable is omitted, buyers see a field in which they can enter the item name. 127
currency_code Optional The currency of prices for trial periods and the subscription. The default is USD.
For allowable values, see Currencies Supported by PayPal.
3
a1 Optional Trial period 1 price. For a free trial period, specify 0.

p1 See description. Trial period 1 duration. Required if you specify a1. Specify an integer value in the allowable range for the units of duration that you specify with t1. 2
t1 See description. Trial period 1 units of duration. Required if you specify a1.

Allowable values are:

  • D – for days; allowable range for p2 is 1 to 90
  • W – for weeks; allowable range for p2 is 1 to 52
  • M – for months; allowable range for p2 is 1 to 24
  • Y – for years; allowable range for p2 is 1 to 5
1
a2 Optional Trial period 2 price. Can be specified only if you also specify a1.

p2 See description. Trial period 2 duration. Required if you specify a2. Specify an integer value in the allowable range for the units of duration that you specify with t2. 2
t2 See description. Trial period 2 units of duration.

Allowable values are:

  • D – for days; allowable range for p2 is 1 to 90
  • W – for weeks; allowable range for p2 is 1 to 52
  • M – for months; allowable range for p2 is 1 to 24
  • Y – for years; allowable range for p2 is 1 to 5
1
a3 Required Regular subscription price.

p3 Required Subscription duration. Specify an integer value in the allowable range for the units of duration that you specify with t3. 2
t3 Required Regular subscription units of duration.

Allowable values are:

  • D – for days; allowable range for p3 is 1 to 90
  • W – for weeks; allowable range for p3 is 1 to 52
  • M – for months; allowable range for p3 is 1 to 24
  • Y – for years; allowable range for p3 is 1 to 5
1
src Optional Recurring payments. Subscription payments recur unless subscribers cancel their subscriptions before the end of the current billing cycle or you limit the number of times that payments recur with the value that you specify for srt.

Allowable values are:

  • 0 – subscription payments do not recur
  • 1 – subscription payments recur

The default is 0.

1
srt Optional Recurring times. Number of times that subscription payments recur. Specify an integer with a minimum value of 1 and a maximum value of 52. Valid only if you specify src="1". 1
sra Optional Reattempt on failure. If a recurring payment fails, PayPal attempts to collect the payment two more times before canceling the subscription.

Allowable values are:

  • 0 – do not reattempt failed recurring payments
  • 1 – reattempt failed recurring payments before canceling

The default is 1.

For more information, see Reattempting Failed Recurring Payments with Subscribe Buttons.

1
no_note Required Do not prompt buyers to include a note with their payments. Allowable values for Subscribe buttons:
  • 1 – hide the text box and the prompt

For Subscribe buttons, always set no_note to 1.

1
custom Optional User-defined field which PayPal passes through the system and returns to you in your merchant payment notification email. Subscribers do not see this field. 255
invoice Optional User-defined field which must be unique with each subscription. The invoice number is shown to subscribers with the other details of their payments 127
modify Optional Modification behavior.

Allowable values are:

  • 0 – allows subscribers only to sign up for new subscriptions
  • 1 – allows subscribers to sign up for new subscriptions and modify their current subscriptions
  • 2 – allows subscribers to modify only their current subscriptions

The default value is 0.
For more information, see Working with Modify Subscription Buttons.

1
usr_manage Optional Set to 1 to have PayPal generate usernames and initial passwords for subscribers.
For more information, see Generating Usernames and Passwords with Subscribe Buttons.
1
Table 7. Automatic Billing Button HTML Variables
Name Required or Optional Description Character Length
max_text Optional A description of the automatic billing plan. The button creation tool uses the same value that you enter in the Description field. Your button passes the description to PayPal to augment the item name in authorization notices and transaction details. If you write the HTML code for your button manually, the value of max_text and the text above the button can differ.

set_customer_limit Required Specify whether to let buyers enter maximum billing limits in a text box or choose from a list of maximum billing limits that you specify.

Allowable values are:

  • max_limit_own – your button displays a text box for buyers to enter their own maximums above a minimum billing limit that you set with the min_amount variable.
  • max_limit_defined – your button displays a dropdown menu of product options with prices to let buyers choose their maximum billing limits.
 
min_amount Optional The minimum monthly billing limit, if you have one. Valid only if set_customer_limit = max_limit_own.

Table 8. Installment Plan Buttons HTML Variables
Name Required or Optional Description Character Length
disp_tot Optional Display the total payment amount to buyers during checkout

Allowable values are:

  • Y – display the total
  • N – do not display the total

The default is N.

1
option_index Required
  • If the button offers a single plan, use 0, or use a number not used for option fields without prices, such as size and color.
  • If the button offers plan options, the cardinal number of the option field, on0 through on9, with plan payment options.

Include option_index if the number for the single plan or options field is not 0.

1
option_selectn Required
  • If the button offers a single plan, the value attribute of a hidden input field named osn. The value attributes of both elements must match, as the following sample code shows
    <input type="hidden" name="osn" value="pay-in-4"> ...
    <input type="hidden" name="option_selectn" value="pay-in-4">
    
  • If the button offers plan options, the value attribute of the radio button for plan option n. The value attributes of both elements must match, as the following sample code shows:
    <input type="radio" name="osn" value="pay-in-4">Pay in 4 installments ...
    <input type="hidden" name="option_selectn" value="pay-in-4">
    
8
option_selectn_name Required
  • If the button offers plan options, text next to the radio button for plan option n
  • If the button offers a single plan, text that describes the plan features

For example, you might use the text "Pay in 4 installments."

option_selectn_type Required Whether the single plan or plan option n offered by the button is paid in full, in equal periods, or in variable periods

Allowable values are:

  • F – pay in full, at checkout
  • E – pay in equal periods, beginning at checkout or sometime later
  • V – pay in variable periods, beginning at checkout
1
option_selectn_am Required Amount of payment m.

If the value of option_selectn_type is E, the value of this variable applies to all payments in the plan.

option_selectn_pm Required Duration of payment period m. Specify the number of time units with option_selectn_tm.

If the value of option_selectn_type is E, the value of this variable applies to all payments in the plan.

option_selectn_tm Required Units of time for payment period m.

Allowable values are:

  • D – for days; allowable range for p3 is 1 to 90
  • W – for weeks; allowable range for p3 is 1 to 52
  • M – for months; allowable range for p3 is 1 to 24
  • Y – for years; allowable range for p3 is 1 to 5
1
option_selectn_nm Required. Number of payments that are the same, in amount and duration, as this one.
  • If the value of option_selectn_type is F, set the value to 1.
  • If the value of option_selectn_type is E, set the value to the number of payments in the plan.
  • If the value of option_selectn_type is F and no subsequent payments are the same as this one, set the value to 1.
1

HTML Variables for Displaying PayPal Checkout Pages

HTML variables for displaying PayPal checkout pages control how the pages appear and function.

Table 9. HTML Variables for Displaying PayPal Checkout Pages
Name Required or Optional Description Character Length
page_style Optional The custom payment page style for checkout pages. Allowable values are:
  • paypal – use the PayPal page style
  • primary – use the page style that you marked as primary in your account profile
  • page_style_name – use the custom payment page style from your account profile that has the specified name

The default is primary if you added a custom payment page style to your account profile. Otherwise, the default is paypal.

30
image_url Optional The URL of the 150x50-pixel image displayed as your logo in the upper left corner of the PayPal checkout pages.
Default – Your business name, if you have a PayPal Business account, or your email address, if you have PayPal Premier or Personal account.
1,024
cpp_cart_border_color Optional

The HTML hex code for your principal identifying color. PayPal blends your color to white in a gradient fill that borders the cart review area of the PayPal checkout user interface.

Valid value is 6 single-byte hexadecimal characters that represent an HTML hex code for a color.

  • Valid only for Buy Now and Add to Cart buttons and the Cart Upload command.
  • Not used with Subscribe, Donate, or Buy Gift Certificate buttons.
6
cpp_header_image Optional The image at the top left of the checkout page. The image's maximum size is 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored only on a secure (https) server.
For more information, see Co-Branding the PayPal Checkout Pages.
Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command.
No limit
cpp_headerback_color Optional The background color for the header of the checkout page.
Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII.
Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command.
6
cpp_headerborder_color Optional The border color around the header of the checkout page. The border is a 2-pixel perimeter around the header space, which has a maximum size of 750 pixels wide by 90 pixels high.
Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII.
Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command.
6
cpp_logo_image Optional A URL to your logo image. Use a valid graphics format, such as .gif, .jpg, or .png. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area.
Note: PayPal recommends that you store the image on a secure (https) server. Otherwise, web browsers display a message that checkout pages contain non-secure items.

Valid value is 127 single-byte alphanumeric characters

  • Valid only for Buy Now and Add to Cart buttons and the Cart Upload command.
  • Not used with Subscribe, Donate, or Buy Gift Certificate buttons.
127
cpp_payflow_color Optional The background color for the checkout page below the header. Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII.
Note: Background colors that conflict with PayPal's error messages are not allowed; in these cases, the default color is white.

Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command.

6
lc Optional The locale of the login or sign-up page, which may have the specific country's language available, depending on localization. If unspecified, PayPal determines the locale by using a cookie in the subscriber's browser. If there is no PayPal cookie, the default locale is US.

The following two-character country codes are supported by PayPal:

  • AU – Australia
  • AT – Austria
  • BE – Belgium
  • BR – Brazil
  • CA – Canada
  • CH – Switzerland
  • CN – China
  • DE – Germany
  • ES – Spain
  • GB – United Kingdom
  • FR – France
  • IT – Italy
  • NL – Netherlands
  • PL – Poland
  • PT – Portugal
  • RU – Russia
  • US – United States
  • The following 5-character codes are also supported for languages in specific countries:
    • da_DK – Danish (for Denmark only)
    • he_IL – Hebrew (all)
    • id_ID – Indonesian (for Indonesia only)
    • ja_JP – Japanese (for Japan only)
    • no_NO – Norwegian (for Norway only)
    • pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
    • ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
    • sv_SE – Swedish (for Sweden only)
    • th_TH – Thai (for Thailand only)
    • tr_TR – Turkish (for Turkey only)
    • zh_CN – Simplified Chinese (for China only)
    • zh_HK – Traditional Chinese (for Hong Kong only)
    • zh_TW – Traditional Chinese (for Taiwan only)
2
no_note Optional Do not prompt buyers to include a note with their payments. Allowable values are:
  • 0 – provide a text box and prompt for the note
  • 1 – hide the text box and the prompt

The default is 0.

1
cn Optional Label that appears above the note field. This value is not saved and does not appear in any of your notifications. If this variable is omitted, the default label above the note field is "Add special instructions to merchant." The cn variable is not valid with Subscribe buttons or if you include no_note="1". 40
no_shipping Optional Do not prompt buyers for a shipping address. Allowable values are:
  • 0 – prompt for an address, but do not require one
  • 1 – do not prompt for an address
  • 2 – prompt for an address, and require one

The default is 0.

1
return Optional The URL to which PayPal redirects buyers' browser after they complete their payments. For example, specify a URL on your site that displays a "Thank you for your payment" page.
Default – PayPal redirects the browser to a PayPal webpage.
1,024
rm Optional Return method. The FORM METHOD used to send data to the URL specified by the return variable.

Allowable values are:

  • 0 – all shopping cart payments use the GET method
  • 1 – the buyer's browser is redirected to the return URL by using the GET method, but no payment variables are included
  • 2 – the buyer's browser is redirected to the return URL by using the POST method, and all payment variables are included

The default is 0.

Note: The rm variable takes effect only if the return variable is set.
1
cbt Optional Sets the text for the Return to Merchant button on the PayPal Payment Complete page. For Business accounts, the return button displays your business name in place of the word "Merchant" by default. For Donate buttons, the text reads "Return to donations coordinator" by default.
Note: The cbt variable takes effect only if the return variable is set.
60
cancel_return Optional A URL to which PayPal redirects the buyers' browsers if they cancel checkout before completing their payments. For example, specify a URL on your website that displays a "Payment Canceled" page.
Default – PayPal redirects the browser to a PayPal webpage.
1,024

HTML Variables for Filling Out PayPal Checkout Pages Automatically

HTML variables for filling out PayPal checkout pages automatically let you specify information about buyers. PayPal recommends that you include automatic fill-out variables with all of your payment buttons for consistent address handling in the checkout experience of your buyers.

To determine how the checkout experience varies if you do not pass in automatic fill-out variables, see Address Handling (U.S. Merchants Only)."

Note: When you pass in address_override=1 or tax or shipping variables, PayPal displays the values in the payment widget. Also, PayPal hides the calculation widget, regardless of setting up shipping and tax rates in your Account Profile.
Table 10. HTML Variables for Filling Out PayPal Checkout Pages Automatically for Buyers
Name Required or Optional Description Character Length
address1 Optional Street (1 of 2 fields) 100
address2 Optional Street (2 of 2 fields) 100
city Optional City 40
country Optional Sets shipping and billing country.
For allowable values, see Countries and Regions Supported by PayPal.
2
email Optional Email address 127
first_name Optional First name 32
last_name Optional Last name 32
lc Optional Sets the language for the billing information/log-in page only. The default is US.
For allowable values, see Countries and Regions Supported by PayPal.
2
charset Optional Sets the character set and character encoding for the billing information/log-in page on the PayPal website. In addition, this variable sets the same values for information that you send to PayPal in your HTML button code. The default is based on the language encoding settings in your Account Profile.
For allowable values, see Setting the Character Set – charset.
 
night_phone_a Optional The area code for U.S. phone numbers, or the country code for phone numbers outside the U.S. PayPal fills in the buyer's home phone number automatically. See description.
night_phone_b Optional The three-digit prefix for U.S. phone numbers, or the entire phone number for phone numbers outside the U.S., excluding country code. PayPal fills in the buyer's home phone number automatically. See description.
night_phone_c Optional The four-digit phone number for U.S. phone numbers. PayPal fills in the buyer's home phone number automatically. See description.
state Optional U.S. state
For allowable values; use the Official U.S. Postal Service Abbreviations.
2
zip Optional Postal code 32

HTML Variables for the Instant Update API

HTML variables for the Instant Update API set up the Cart Upload command for the Instant Update API callback. Establish your own Instant Update callback server before you use these variables.

Instant Update Variables to Set Up a Payment for the Instant Update API

Some Instant Update variables set up the Cart Upload to use your callback server. Include the following required variables in the Cart Upload command to have PayPal send Instant Update requests to your callback server. Include the following optional variables when appropriate.

Table 11. HTML Variables to Set Up an Instant Update Payment
Name Required or Optional Description Character Length
callback_url Required The URL of your Instant Update callback server 1024
callback_timeout Required The timeout in seconds for callback responses from your Instant Update callback server. After exceeding the timeout, PayPal uses the fallback values on the Review Your Payment page for tax, shipping, and insurance.
Allowable values are 1-6. PayPal recommends the value 3.
TipImportant: Use values other than 3 only when instructed to do so by your PayPal representative.
1
callback_version Required The version of the Instant Update API that your callback server uses.

fallback_tax_amount Optional Tax amount to use as a fallback, if the callback response times out

fallback_shipping_option_name_x Required Name and label of shipping option x to use as a fallback, if the callback response times out. For example, "Express 2 days". You can include a maximum of 10 shipping options as fallbacks. Substitute x with ordinal numbers, starting with 0.
Include 1 instance of this variable, with its index (x) set to 0. If you include just 1 instance, include fallback_shipping_option_is_default_x with its index (x) set to 0 and its value set to 1.
Allowable values for x are 0-9.
50
fallback_shipping_option_amount_x Required Shipping amount for option x to use as a fallback, if the response times out.
Allowable values for x are 0-9.

fallback_shipping_option_is_default_x Required Indicates that shipping option x is the default and should be selected in the dropdown menu as a fallback, if the response times out.
Only one shipping option can be the default for buyers. Check that you set 1 instance only of fallback_shipping_option_is_default_x to the value 1.

Allowable values are:

  • 1 – shipping option x is the default shipping option
  • 0 – shipping option x is not the default shipping option

Allowable values for x are 0-9.

1
fallback_insurance_option_offered Optional Indicates that insurance is offered. PayPal ignores this HTML variable if fallback_insurance_amount is omitted or the value is 0 or less.

Allowable values are:

  • 1 – insurance is offered
  • 0 – insurance is not offered
1
fallback_insurance_amount Optional Insurance amount to use as a fallback, if the callback response times out. Include the fallback_insurance_option_offered HTML variable if you specify an insurance amount. The fallback insurance amount applies to all shipping options that you specify.

Instant Update Variables for Dimensions of Individual Items

Shipping charges are calculated sometimes by using the dimensions of individual items in the shopping cart. Include the following optional dimensional variables below in the Cart Upload command to provide the information to your callback server.

Table 12. HTML Variables to Set Up an Instant Update Payment for Dimension-Based Shipping Charges
Name Required or Optional Description Character Length
height_x Optional Height of item x in the shopping cart.
Allowable values are positive integers.

height_unit Optional Unit of measure for the values specified by the height_x values.
Allowable values are any values that you choose to provide. PayPal passes the value to your callback server in callback requests.

width_x Optional Width of item x in the shopping cart.
Allowable values are positive integers.

width_unit Optional Unit of measure for the value specified by width_x
Allowable values are any values that you choose to provide. PayPal passes the value to your callback server in callback requests.

length_x Optional Length of item x in the shopping cart.
Allowable values are positive integers.

length_unit Optional Unit of measure for the value specified by length_x
Allowable values are any values that you choose to provide. PayPal passes the value to your callback server in callback requests.