HTML Variables for Website Payments Standard 5

HTML Variables for Prepopulating PayPal Checkout Pages

Your Ad Here

HTML variables for prepopulating PayPal checkout pages let you specify information about the payer. It is recommended that you include prepopulation variables with all of your payment buttons to ensure consistency of address handling in your buyers's checkout experiences.

To determine how the experience varies if you do not consistently pass in prepopulation variables, see Address Handling (U.S. Merchants Only).

Note: If you prepopulate address_override=1 or prepopulate tax or shipping variables, the passed-in values will display in the transaction widget and the calculation widget will be hidden, regardless of whether you have setup shipping and tax rates in your account profile.

Table 8. HTML Variables for Prepopulating Checkout Pages With Payer Information

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	64
lc	Optional	Sets the payer's 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 encoding for the billing information/log-in page, for the information you send to PayPal in your HTML button code, and for the information that PayPal returns to you as a result of checkout processes initiated by the payment button. The default is based on the character encoding settings in your account profile. For allowable values, see Setting the Character Set – charset.	21
night_ phone_a	Optional	The area code for U.S. phone numbers, or the country code for phone numbers outside the U.S. This will prepopulate the payer's home phone number.	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. This will prepopulate the payer's home phone number.	See description.
night_ phone_c	Optional	The four-digit phone number for U.S. phone numbers. This will prepopulate the payer's home phone number.	See description.
state	Optional	State; use Official U.S. Postal Service Abbreviations.	2
zip	Optional	Postal code	32

 

HTML Variables for Website Payments Standard 4

HTML Variables for Displaying PayPal Checkout Pages

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

Table 7. 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: 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 Business account, or your email address, if you have Premier or Personal account.	1,024
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.	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.	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.	6
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.	6
cs	Optional	The background color of the checkout page. Allowable values: 0 – background color is white 1 – background color is black The default is 0.	1
lc	Optional	The language of the login or sign-up page that subscribers see when they click the Subscribe button. If unspecified, the language is determined by a PayPal cookie in the subscriber's browser. If there is no PayPal cookie, the default language is U.S. English. For allowable values, see .	2
no_note	Optional	Do not prompt payers to include a note with their payments. Allowable values: 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 will not appear in any of your notifications. If 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".	90
no_shipping	Optional	Do not prompt payers for shipping address. Allowable values: 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 the payer's browser is redirected after completing the payment; for example, a URL on your site that displays a "Thank you for your payment" page. Default – The browser is redirected to a PayPal web page.	1,024
rm	Optional	Return method. The FORM METHOD used to send data to the URL specified by the return variable after payment completion. Allowable values: 0 – all shopping cart transactions use the GET method 1 – the payer's browser is redirected to the return URL by the GET method, and no transaction variables are sent 2 – the payer's browser is redirected to the return URL by the POST method, and all transaction variables are also posted The default is 0. Note: The rm variable takes effect only if the return variable is also 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 return variable must also be set.	60
cancel_ return	Optional	A URL to which the payer's browser is redirected if payment is cancelled; for example, a URL on your website that displays a "Payment Canceled" page. Default – The browser is redirected to a PayPal web page.	1,024

H

HTML Variables for Website Payments Standard 3

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. HTMLVariables 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	Required	Price of the item or the total price of all items in the shopping cart.
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 to be 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 with 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 to be 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	Required	Name of the item or a name for the entire Shopping Cart
paymentaction	Optional	Indicates whether the transaction is payment on a final sale or an authorization for a final sale, to be captured later. Allowable values: 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 transaction without placing a hold on the PayPal account. Important: If you set paymentaction to order, you must use the Authorization & Capture API to authorize and capture the transaction payments. The merchant tools on the PayPal websitel let you capture payments only for authorizations, not for orders.
shopping_url	Optional	The URL of the page on the merchant website that buyers return 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" variable, which are used with the PayPal Shopping Cart.	1

HTML Variables for Subscribe Buttons

HTML variables for Subscribe buttons set the terms of subscriptions and their recurring payments.

Table 6. HTML Variables for Subscribe Buttons

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 (maximum 127 characters). If you are collecting aggregate payments, this can include a summary of all items purchased, tracking numbers, or generic terms such as "subscription." If omitted, customer will see a field in which they have the option of entering an Item Name
currency_code	Optional	The currency of prices for trial periods and the subscription. The default is USD. For allowable values, see Currency Codes.	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: D – for days; allowable range for p1 is 1 to 90 W – for weeks; allowable range for p1 is 1 to 52 M – for months; allowable range for p1 is 1 to 24 Y – for years; allowable range for p1 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: 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: 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: 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 above 1. 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: 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 payers to include a note with their payments. Allowable values for Subscribe buttons: 1 – hide the text box and the prompt For Subscribe buttons, always include no_note and set it to 1.	1
custom	Optional	User-defined field which will be passed through the system and returned in your merchant payment notification email. This field will not be shown to your subscribers.	255
invoice	Optional	User-defined field which must be unique with each subscription. The invoice number will be shown to subscribers with the other details of their transactions	127
modify	Optional	Modification behavior. Allowable values: 0 – allows subscribers to only create new subscriptions 1 – allows subscribers to modify their current subscriptions or sign up for new ones 2 – allows subscribers to only modify 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

HTM

HTML Variables for Website Payments Standard 3

HTML Variables for Payment Transactions

 

HTML variables for payment transactions provide information about entire transactions, 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 in prepopulation variables overrides the PayPal member's stored address. The payer is shown the passed-in address but cannot edit it. No address is shown if the address is not valid, such as missing required fields like country, or is not included at all. For more information, see the HTML Variables for Prepopulating PayPal Checkout Pages table.	1
currency_ code	Optional	The currency of the payment. The default is USD. For allowable values, see Currency Codes.	3
custom	Optional	Passthrough variable never presented to the payer. Default – No variable is passed back to you.	256
handling	Optional	Handling charges. This 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	Passthrough variable you can use to identify your invoice number for this purchase. Default – No variable is passed back to you.	127
shipping	Optional	The cost of shipping the entire order contained in third-party shopping carts. This use of the shipping variable is valid only for the Cart Upload command. Default – If profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose.
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 transaction. This value overrides the weight values of individual items.
weight_unit	Optional	The unit of measure if weight_cart is specified. Allowable values: lbs kgs The default value is lbs.