Adding PayPal Checkout to Your 3rd-party Shopping Cart


Some web developers may wish to integrate PayPal payment processing with their own 3rd 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 3rd party shopping cart.

There are now two ways to integrate your 3rd party shopping cart with 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



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 4 hidden variables and an image as the form submit:

Required Variables
NameValue
businessEmail address on your PayPal account
item_nameName of the item (or a name for the shopping cart)
currency_codeDefines the currency in which the monetary variables (amount, shipping, shipping2, handling, tax) are denoted. Possible values are "USD", "EUR", "GBP", "CAD", "JPY".
amountPrice of the item (the total price of all items in the shopping cart)
imageThe 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:

<form action="https://www.paypal.com/il/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="you@youremail.com">
<input type="hidden" name="item_name" value="Item Name">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="amount" value="0.00">
<input type="image" src="http://www.paypal.com/en_US/i/btn/x-click-but01.gif" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
</form>

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
NameValue
businessEmail address on your PayPal account
quantityNumber of items. This will multiply the amount if greater than one
item_nameName of the item (or a name for the shopping cart). Must be alpha-numeric, with a 127character limit
item_numberOptional pass-through variable for you to track payments. Must be alpha-numeric, with a 127 character limit
amountPrice of the item (the total price of all items in the shopping cart)
shippingThe cost of shipping the item
shipping2The cost of shipping each additional item
handlingThe cost of handling
taxTransaction-based tax value. If present, the value passed here will override any profile tax settings you may have (regardless of the buyer's location).
no_shippingShipping address. If set to "1," your customer will not be asked for a shipping address. This is optional; if omitted or set to "0," your customer will be prompted to include a shipping address
cnOptional label that will appear above the note field (maximum 40 characters)
no_noteIncluding 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.
on0First option field name. 64 character limit
os0First set of option value(s). 200 character limit. "on0" must be defined for "os0" to be recognized.
on1Second option field name. 64 character limit
os1Second set of option value(s). 200 character limit. "on1" must be defined for "os1" to be recognized.
customOptional pass-through variable that will never be presented to your customer. Can be used to track inventory
invoiceOptional pass-through variable that will never be presented to your customer. Can be used to track invoice numbers
notify_urlOnly used with IPN. An internet URL where IPN form posts will be sent
returnAn internet URL where your customer will be returned after completing payment
cancel_returnAn internet URL where your customer will be returned after cancelling payment
image_urlThe internet URL of the 150 X 50 pixel image you would like to use as your logo
csSets the background color of your payment pages. If set to "1," the background color will be black. This is optional; if omitted or set to "0," the background color will be white

Extended Variables

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

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

to:

<input type="hidden" name="cmd" value="_ext-enter">
<input type="hidden" name="redirect_cmd" value="_xclick">

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

Extended Variables
NameValue
emailCustomer's email address
first_nameCustomer's first name. Must be alpha-numeric, with a 32 character limit
last_nameCustomer's last name. Must be alpha-numeric, with a 64 character limit
address1First line of customer's address. Must be alpha-numeric, with a 100 character limit
address2Second line of customer's address. Must be alpha-numeric, with a 100 character limit
cityCity of customer's address. Must be alpha-numeric, with a 100 character limit
stateState of customer's address. Must be official 2 letter abbreviation
zipZip code of customer's address
night_phone_aArea code of customer's night telephone number
night_phone_bFirst three digits of customer's night telephone number
day_phone_aArea code of customer's daytime telephone number
day_phone_bFirst three digits of customer's daytime telephone number

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

Method 2. Passing Individual Items to PayPal



If your 3rd 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 #1 "Passing Aggregate Cart Amount to PayPal" with the following exceptions:

  1. 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">

  2. Add a new variable called "upload"

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

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

  3. 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 3rd 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.

    NameValue
    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_xOptional 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_xThe cost of shipping the first piece (quantity of 1) of item #x
    shipping2_xThe cost of shipping each additional piece (quantity of 2 or above) of item #x
    handling_xThe cost of handling for item #x
    on0_xFirst option field name for item #x. 64 character limit
    os0_xFirst 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_xSecond option field name for item #x. 64 character limit
    os1_xSecond set of option value(s) for item #x. 200 character limit. "on1_x" must be defined in order for "os1_x" to be recognized.

  4. 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, shipping, shipping2, handling, tax) 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 U.S. 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.