PayPal buttons have many different options you can add to them. There are
more variables listed, however, I have only listed the most common. If you
are interested in finding more please take a look at our Integration Guide.
All options should be put between the tags listed below.
All PayPal buttons should start and end with these tags (The top tag being on
the top and the lower tag ending of the button). If the tags are not in
place correctly it can cause you to experience difficulty with your
buttons. Everything that makes the button work properly needs to go
between the two tags above.
One of the things to remember is that all of the variables generally go in
tags like the one I have given as an example below:
a working example of this using the item_name variable for a Plush Penguin would be:
In almost all of our options you simply need to alter the name value and the
value value. Item names should always be typed in lower case.
These can all, also, be found in our Integration Guide. You can also edit the type with another acceptable type such as text, radio, etc.
|
Variable Name |
|
Description |
Char
Limit |
| Item
Information (O = Optional, R = Required) |
| item_number |
O |
Pass-through variable for you to track purchases
or donations. it will get passed back to you at the completion of
the payment. If omitted, no variable will be passed back to you. |
127 |
item_name |
O |
This is a required field for Shopping Cart purchases. If left blank on any other type of button the user will be prompted to enter the name of item or service they are purchasing |
127 |
add |
R |
This is a required variable for the shopping cart. This is not needed for any other type of payment. The value must be set as 1. This is a flag variable that allows the shopping cart to function properly. |
|
amount |
|
The value of this variable reflects the amount of the item or service in question. This should be put in the format x.xx. This is a required
field for Shopping Cart and Subscription payments. For Buy now and Donation if the field is left blank the customer will be prompted to enter an amount. At this time the smallest amount that can be processed is $0.01. The largest that can be processed at one time is $10,000. |
|
| on0 |
O |
First option field name. If omitted, no
variable will be passed back to you (the option values are required to be
entered in the correct order. on0, os0, on1, os1) |
64 |
| os0 |
O |
Second option field name. If omitted, no
variable will be passed back to you. If this option is selected
through a text box or radio button, each value should be no more than 64
characters. If this value is entered by the customer through a text
box, there is a 200-character limit. (The option values are required
to be entered in the correct order. on0, os0, on1, os1) |
64/200 |
| on1 |
O |
Third option field. If omitted, no variable
will be passed back to you. (the option values are required to be
entered in the correct order. on0, os0, on1, os1) |
64 |
| os1 |
O |
Fourth option field. If omitted, no
variable will be passed back to you. If this option is selected
through a text box or radio button, each value should be no more than 64
characters. If this value is entered by the customer through a text
box, there is a 200-character limit. (the option values are required
to be entered in the correct order. on0, os0, on1, os1) |
64/200 |
| quantity |
O |
Number of items. The amount, shipping and
tax will be multiplied by the quantity to get the total payment
amount. If this is a shopping cart transaction, we will append the
number of the item (e.g. quantity1, quantity2) |
|
| undefined_quantity |
O |
If included and the value set to 1, enables
buyer to modify the quantity. This is specific for Buy Now buttons.
(Please note that this does not work for Shopping Cart buttons) |
|
|
Display
Information |
| cn |
O |
Label that will appear above the note
field. This value is not saved and will not appear in any of your
notifications. If omitted, no variable will be passed. |
40 |
| cs |
O |
Set the background color of your payment
pages. If the value is set to 1, the background color will be
black. If omitted or set to 0, the background color will be white. |
|
| image_url |
O |
The internet URL of the 150 x 52-pixel image you
would like to use as your logo. if omitted, the customer will see
your business name if you have a business account, or your email address
if you have a premier account. |
|
| no_note |
O |
Including a note with payment. If the
value is set to 1, your customer will not be prompted to include a note.
If omitted or set to 0, your customer will be able to provide additional
information or a note.. |
|
| no_shipping |
O |
If the value
is set to 1, your customer will not be asked for a shopping address. If
omitted or set to 0 your customer will be prompted to include a shipping
address, but they will have the option of not including a shipping address. If the value is set to 2 then your customer will be required to include a shipping address. |
|
| cancel_return |
O |
An internet URL where the user will be returned
if payment is cancelled - for example, a URL on your site which hosts a
"Payment Cancelled" page. If omitted, users will be
taken to the PayPal website. (Example: http://www.yourdomain.com/cancelled.html) |
|
| return |
O |
An internet URL where the user will be returned
if payment is successful - for example, a URL on your site which hosts a
"Thank You" page. If omitted, users will be taken to the
PayPal website. (Example: http://www.yourdomain.com/thankyou.html) |
|
| rm |
O |
Return URL behavior. If the value is set
to 1 and if return is set, upon completion of the payment the buyer will
be sent back to the return URL using a GET method, and no transaction
variables will be submitted. If set to 2 and if return is set, the
buyer will be sent back to the return URL using a Post method, to which
all available transaction variables will also be posted. If omitted
or set to 0, GET methods will be used for all Shopping Cart transactions
in which IPN is not enabled. Post methods with variables will be
used for the rest. |
|
| page_style |
O |
Sets the Custom Payment Page Style for payment
pages associated with this button/link. the value of page_style is
the same as the Page Name you choose when adding or editing the page
style. You can add and edit Custom Payment Page Styles from the
Profile sub tab of the My Account tab. If you would like the
button/link to always reference the style you make Primary, set this
variable equal to "primary." If you would like this
button/link to reference the default PayPal page style, set this variable
equal to "paypal." If you would like this button/link to
reference the default PayPal page style, set this variable equal to
"paypal." The page_style variable has a maximum
length of 30 characters. Valid character set is alphanumeric ASCII
lower 7-bit characters only, plus underscore. It cannot include space. |
|
| cbt |
O |
Sets the text for the Continue button on the
PayPal Payment Complete page. Requires Return URL to be set. |
|
| Transaction
Information |
| currency_code |
O |
The currency of the payment. Defines the
currency in which the monetary variables (amount, shipping,
shipping2, handling, tax) are denoted. Possible values are "USD"
(U.S. Dollar), "EUR" (Euro), "GBP" (Pound Sterling),
"CAD" (Canadian Dollar), "JPY" (Yen), and "AUD" (Australian Dollars). If
omitted, all monetary fields will be interpreted as U.S. Dollars. |
|
| custom |
O |
Pass-through variable that will never be
presented to your customer. If omitted, no variable will be passed
back to you. |
256 |
| handling |
O |
The cost of handling. This is not quantity-specific.
The same handling will be charged regardless of the number of items
purchased. If omitted, no handling charges will be assessed. |
|
| handling_cart |
O |
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 will be used. This variable is
for the PayPal Shopping Cart. |
|
| invoice |
O |
Pass-through variable you can use to identify
your Invoice Number for this purchase. If omitted, no variable will
be passed back to you. |
256 |
| shipping |
O |
The cost of shipping this item if you have
enabled item-specific shipping costs. If shipping is used and
shipping2 is not defined, this flat amount will be charged regardless of
the quantity of items purchased. If you are using item-based shipping,
make sure the override check box is checked in your Profile. If omitted,
and your Profile-based shipping is enabled, your customer will be charged
the amount or percentage defined in your Profile. |
|
| shipping2 |
O |
The cost of shipping each additional item.
IF omitted, and your Profile-based shipping is enabled, your customer will
be charged the amount or percentage defined in your Profile. |
|
| tax |
O |
Transaction-based tax override variable.
Set this to a flat tax amount you would like to apply to the transaction
regardless of your buyer's location. If present, this value
overrides any tax settings that may be set in your Profile. If omitted,
Profile tax settings (if any) will apply. |
|
| Subscription Specific Variables |
| a1 |
O |
Trial amount 1. This is the price
of the first trial period. For a free trial, use a value of 0.00 |
|
| a2 |
O |
Trial amount 2. This is the price
for the second trial period. For a free trial, use a value of 0.00 |
|
| a3 |
R |
Regular rate. This is the price of the
subscription and should be in the format x.xx. |
|
| p1 |
O |
Trial period 1. This is the
length of the first trial period. The number is modified by the trial
period 1 units. (example value=12) |
|
| p2 |
O |
Trial period 2. This is the
length of the second trial period. The number is modified by the trial
period 1 units. (example value=12) |
|
| p3 |
R |
Regular rate. This is the length
of the regular subscription period. The number is modified by the
trial period 1 units. (example value=12) |
|
| t1 |
O |
Trial period 1 units. This is the
units of trail period 1. Acceptable values are: D (days), W (weeks), M
(months), Y (years). |
|
| t2 |
O |
Trial period 2 units. This is the
units of trail period 2. Acceptable values are: D (days), W (weeks), M
(months), Y (years). |
|
| t3 |
R |
Regular rate. This is the units
of the regular subscription. Acceptable values are: D (days), W
(weeks), M (months), Y (years). |
|
| src |
O |
Recurring payments. If set to 1,
the payment will recur unless your customer cancels the subscription before
the end of the billing cycle. If omitted, the subscription payment
will not recur at the end of the billing cycle. |
|
| sra |
O |
Reattempt on failure. If set to
1, and the payment fails, the payment will be reattempted two more times.
After the third failure, the subscription will be cancelled. if
omitted and the payment fails, payment will not be reattempted and the
subscription will be immediately cancelled. |
|
| srt |
O |
Recurring Times. This is the
number of payments which will occur at the regular rate. IF omitted,
payment will continue to recur at the regular rate until the subscription is
cancelled. |
|
| usr_manage |
O |
username password generation field.
If set to 1, PayPal will generate usernames and passwords for your
subscribers. For use with Password Management. If omitted, no
passwords will be generated. Do NOT use unless you are using password
management. |
|
| modify |
O |
Modification behavior. If set to
zero or omitted, the button will only allow buyers to create new
subscriptions. If set to 1, the button will only allow buyers to
modify existing subscriptions according to the other parameters specified by
the button. If set to 2, the button will allow buyers to modify current
subscriptions if they have any, and to sign up for new subscriptions if they
do not. |
|
