HTML Variables for Website Payments Standard 5

HTML Variables for Prepopulating PayPal Checkout Pages





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.

 

Search This Blog

Link Within Related Posts Plugin for WordPress, Blogger...