Adding PayPal Checkout to Your third-party Shopping Cart

Some web developers may wish to integrate PayPal payment processing with their own third party shopping cart instead of the standard PayPal Shopping Cart. Please use the instructions below to allow your buyers to pay with PayPal when they are ready to check out after adding all of their items to your third party shopping cart.

There are now two ways to integrate your third-party shopping cart into the PayPal payment flow. The first is to pass in the aggregate amount of the cart payment, rather than of the individual items. The second is to pass details of the items that have been selected to PayPal, instead of an aggregated amount for the entire cart. Note: Posting the necessary variables to PayPal as described below will probably require you to implement some scripting on your website.

Method 1. Passing the Aggregate Cart Amount to PayPal
Method 2. Passing Individual Items to PayPal

Method 1. Passing the Aggregate Cart Amount to PayPal

If you wish, you may aggregate your entire shopping cart and pass the total amount into PayPal's Buy Now Button code (that is, you will need to post a single name for the entire cart and the total price of the cart's contents as though it were a purchase of a single item).

One drawback of this method is that your buyers will not be able to see the individual items appearing in their carts. In addition, you cannot change our variable names, nor can you add your own variable names.

If you have additional technical questions after reviewing the information below, please visit our Developer Support area. For additional information about Buy Now Buttons code or the variables below, please see the Website Payments Standard Integration Guide.

Required Variables

The code for your PayPal post requires the following four hidden variables and an image as the form submit:

Required Variables
Name	Value
business	Email address on your PayPal account
item_name	Name of the item (or a name for the shopping cart)
currency_code	Defines the currency in which the monetary variables (amount, postage, postage2, handling, tax) are denoted. Possible values are "USD", "EUR", "GBP", "CAD", "JPY".
amount	Price of the item (the total price of all items in the shopping cart)
image	The image for the button your buyer will press to initiate the PayPal payment process. You can substitute your own image by replacing the src with the URL of your image

This means that the minimum required code for your post to PayPal will look like this:

PayPal offers additional variables to customize your form post. All of the available variables are listed below (variable names must be in lower case):

Available Variables
Name	Value
business	Email address on your PayPal account
quantity	Number of items. This will multiply the amount if greater than one
item_name	Name of the item (or a name for the shopping cart). Must be alpha-numeric, with a 127character limit
item_number	Optional pass-through variable for you to track payments. Must be alpha-numeric, with a 127 character limit
amount	Price of the item (the total price of all items in the shopping cart)
shipping	The cost of postage for the item
shipping2	The cost of postage for each additional item
handling	The cost of packing
tax	Transaction-based tax value. If present, the value passed here will override any profile GST settings you may have (regardless of the buyer's location).
no_shipping	Shipping address. If set to '1', your customer will not be asked for a mailing address. This is optional; if omitted or set to "0," your customer will be prompted to include a mailing address.
cn	Optional label that will appear above the note field (maximum 40 characters)
no_note	Including a note with payment. If set to '1', your customer will not be prompted to include a note. This is optional; if omitted or set to '0', your customer will be prompted to include a note.
on0	First option field name. 64 character limit
os0	First set of option value(s). 200 character limit. "on0" must be defined for "os0" to be recognized.
on1	Second option field name. 64 character limit
os1	Second set of option value(s). 200 character limit. "on1" must be defined for "os1" to be recognized.
custom	Optional pass-through variable that will never be presented to your customer. Can be used to track inventory
invoice	Optional pass-through variable that will never be presented to your customer. Can be used to track invoice numbers
notify_url	Only used with IPN. An internet URL where IPN form posts will be sent
return	An internet URL where your customer will be returned after completing payment
cancel_return	An internet URL where your customer will be returned after cancelling payment
image_url	The internet URL of the 150 X 50 pixel image you would like to use as your logo
cs	Sets the background colour of your payment pages. If set to '1', the background colour will be black. This is optional; if omitted or set to '0', the background colour will be white.

Extended Variables

PayPal allows you to post extended variables if you change this "cmd" input:

to:

By making the above change to the 'cmd' input, you can also use the variables below:

Extended Variables
Name	Value
email	Customer's email address
first_name	Customer's first name. Must be alpha-numeric, with a 32 character limit
last_name	Customer's last name. Must be alpha-numeric, with a 64 character limit
address1	First line of customer's address. Must be alpha-numeric, with a 100 character limit
address2	Second line of customer's address. Must be alpha-numeric, with a 100 character limit
city	City of customer's address. Must be alpha-numeric, with a 100 character limit
state	County of customer's address. Must be official two letter abbreviation
zip	Postcode of customer's address
night_phone_a	Area code of customer's night telephone number
night_phone_b	First three digits of customer's night telephone number

day_phone_a	Area code of customer's daytime telephone number
day_phone_b	First three digits of customer's daytime telephone number

Note:To specify shipping & handling amounts that differ from the default postal amounts set in your Profile, please go to your Profile, edit your Postal Calculations, and click the 'allow transaction-based postal override' checkbox.

Method 2. Passing Individual Items to PayPal

If your third-party shopping cart can be configured to pass individual items to PayPal, information about the items will be included in the buyers' and sellers' History logs and notifications. To include information about the items, you will post HTML form elements to a new version of PayPal's Shopping Cart flow. This process is much like the one described in Section Number 1, 'Passing Aggregate Cart Amount to PayPal' with the following exceptions:

Set the "cmd" variable to "_cart"
Replace this required HTML line

<input type="hidden" name="cmd" value="_xclick">

with

<input type="hidden" name="cmd" value="_cart">
Add a new variable called "upload"

Add the following line between the <form> and </form> tags:

<input type="hidden" name="upload" value="1">

Define item details
For each of the following item-specific parameters, define a new set of values that correspond to each item that was purchased via your third-party cart. Append "_x" to the variable name, where x is the item number, starting with 1 and increasing by one for each item that is added.

Name	Value
item_name_x	(Required for item #x) Name of item #x in the cart. Must be alpha-numeric, with a 127 character limit
item_number_x	Optional pass-through variable associated with item #x in the cart. Must be alpha-numeric, with a 127 character limit
amount_x	(Required for item #x) Price of the item #x
shipping_x	The cost of shipping the first piece (quantity of 1) of item #x
shipping2_x	The cost of shipping each additional piece (quantity of 2 or above) of item #x
handling_x	The cost of handling for item #x
on0_x	First option field name for item #x. 64 character limit
os0_x	First set of option value(s) for item #x. 200 character limit. "on0_x" must be defined in order for "os0_x" to be recognized.
on1_x	Second option field name for item #x. 64 character limit
os1_x	Second set of option value(s) for item #x. 200 character limit. "on1_x" must be defined in order for "os1_x" to be recognized.

Repeat for each item included in cart
Include a set of required variables and any optional variables from the table above for each item included in your buyers' cart. The first item included in the cart should be defined with parameters ending in "_1", such as "item_name_1", "amount_1", etc. Similarly the second item should be denoted with variables like "item_name_2", "amount_2", etc. Note: the "_x" values must increment by one continuously in order to be recognized. If you skip from item #1 to item #3 without defining an item #2, the third item will be ignored.

To specify currency: All monetary variables (amount, postage, postage2, packing, GST) will be interpreted in the currency designated by the "currency_code" variable that is posted with the payment. Since it is not item-specific, there is no need to append a "_x" to the variable name. If no "currency_code" variable is posted, we will assume that all monetary values are in US Dollars.

If you have additional technical questions after reviewing the information above, please visit our Developer Support area. For additional information about Shopping Cart code or the variables below, please see the Website Payments Standard Integration Guide.