Help Article

How do I add PayPal checkout to my custom shopping cart?

There are two ways to integrate PayPal payment processing with your own third-party shopping cart:
  • Pass the aggregate cart amount instead of the price of each individual item.
  • Pass details of each individual item.

Note: Posting the necessary variables to PayPal as described will probably require you to implement some scripting on your website.
 
Method 1: Passing the aggregate cart amount to PayPal You can pass the total amount of your shopping cart into PayPal's Buy Now Button code as though it were a single-item purchase. Start by incorporating the required variables and image, and then customize your form with any of the additional and extended variables listed on this page.

Required variables and image
The following table describes the four hidden variables and the form submit image that the code for your PayPal post requires.
 
Name Description
amount The total price of all the items in the shopping cart.
business Your PayPal account's email address.
currency_code Defines the currency type (such as "USD" and "EUR") that the monetary variables (amount, shipping, shipping2, handling, tax) are using.
image Indicates the image for the button that your buyer will press to initiate the PayPal payment process. You can substitute your own image by replacing the src attribute with the URL of that image.
item_name The name of the item or the shopping cart.

Thus, the minimum required code for your post to PayPal should look like the following example:
   
<input type="hidden" name="cmd" value="_ext-enter">
<form action="https://www.paypal.com/us/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>

Additional variables
The following table describes the variables you can use to customize your form post (variable names must be in lowercase).
 
Name Description
amount The total price of all the items in the shopping cart.
business Your PayPal account's email address.
cancel_return The URL where your customer will go after the payment is cancelled.
cn An optional label (40-character limit) that appears above the note field.
custom An optional pass-through variable, hidden to the customer, that you can use to track inventory.
handling The handling cost

Note: To specify handling amounts that differ from the default amounts set in your profile, go to your profile, edit your handling calculations, and check Allow transaction-based shipping override.
image_url The URL of the 150 x 50 pixel image that you want to use as your logo.
invoice An optional pass-through variable, hidden to the customer, that you can use to track invoice numbers.
item_name The name (127-alphanumeric character limit) of the item or shopping cart.
item_number An optional pass-through variable (127-alphanumeric character limit) that you can use to track payments.
no_note Indicates whether the payment can include a note.

"0" - Your customer has the option to include a note when prompted.
"1" - No prompting occurs. 
no_shipping Indicates whether there is a request to include the customer's shipping address.

"0" - Your customer has the option to include a shipping address when prompted.
"1" - No prompting occurs.  
notify_url Indicates the URL where the IPN form posts are sent (used with IPN only).
on0 The first option field name (64-character limit).
on1 The second option field name (64-character limit).
os0 The first set of option values (200-character limit).

Note: This variable is recognized only after you first define on0.
os1 The second set of option values (200-character limit).

Note: This variable is recognized only after you first define on1.
quantity Indicates the number of items. The amount value multiplies when this value is greater than one.
return The URL where your customer will go after the payment is completed.
shipping The item's shipping cost

Note: To specify shipping amounts that differ from the default shipping amounts set in your profile, go to your profile, edit your shipping calculations, and check Allow transaction-based shipping override.
shipping2 The shipping cost of each additional item

Note: To specify shipping amounts that differ from the default shipping amounts set in your profile, go to your profile, edit your shipping calculations, and check Allow transaction-based shipping override.
tax Indicates the transaction-based tax value that, if present, overrides any profile tax settings you may have (regardless of the buyer's location).

Extended variables
You can post extended variables if you change the "cmd" input from:
 
<input type="hidden" name="cmd" value="_xclick">

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

The following table describes the variables you can also use after making the change above (variable names must be in lowercase).
 
Name Description
address1 The first line of the customer's address (100-alphanumeric character limit).
city The city noted in the customer's address (100-alphanumeric character limit).
day_phone_a The area code of the customer's daytime telephone number.
day_phone_b The first three digits of the customer's daytime telephone number.
email The customer's email address.
first_name The customer's first name (32-alphanumeric character limit).
last_name The customer's last name (64-alphanumeric character limit).
night_phone_a The area code of the customer's evening telephone number.
night_phone_b The first three digits of the customer's evening telephone number.
state The state noted in the customer's address (the official two-letter abbreviation).
zip The postal code noted in the customer's address.
 
 
Method 2: Passing individual items to PayPal If you can configure your third-party shopping cart to pass individual items to PayPal, the buyers' and sellers' history logs and notifications include information about those items. To include information about the items, post the HTML form elements to a new version of PayPal's shopping cart flow. This process is similar to the one described in Method 1, with the following exceptions:

First, change the "cmd" input from:
   
<input type="hidden" name="cmd" value="_xclick">

to:
   
<input type="hidden" name="cmd" value="_cart">

Item-specific variables
For each of the item-specific variables, do the following:
  • Define a new set of values that correspond to each item purchased via your third-party cart.
  • Append "_x" to the variable name, where "x" is the item number.
  • Set the quantity at 1 and increment each time to reflect the increase of quantity of that specific item.
  • Include a set of required variables and any optional variables from the table below for each item included in your buyers' cart.
  • Define the first item included in the cart with parameters that end with "_1" (such as item_name_1 and amount_1), the second item with "_2" (such as item_name_2 and amount_2), and so on.

Note: The "_x" values must increment by one continuously in order for PayPal to recognize it. If you skip from item #1 to item #3 without defining item #2, item #3 is ignored.

All monetary variables (amount, shipping, shipping2, handling, tax) reflect the currency designated by the currency_code variable posted with the payment. This is not item-specific, so you don't need to append a "_x" to the variable name. If no currency_code variable is posted, the default is US Dollars.

The following table describes the item-specific variables.
 
Name Description
amount_x The price of that specific item (required for each specific item).
handling_x The handling cost for that specific item.
item_name_x The name (127-alphanumeric character limit) of that specific item (required for each specific item).
item_number_x An optional pass-through variable (127-alphanumeric character limit) associated with that specific item that you can use to track payments.
on0_x The first option field name of that specific item (64-character limit).
on1_x The second option field name of that specific item (64-character limit).
os0_x The first set of option values (200-character limit) for that specific item.

Note: This variable is recognized only after you first define on0_x.
os1_x The second set of option values (200-character limit) for that specific item.

Note: This variable is recognized only after you first define on1_x.
shipping_x The cost of shipping that specific item.
shipping2_x The cost of shipping each additional piece, when ordering two or more of that specific item.
 
If you have more technical questions after reviewing this information, visit the Development & Integration Guides page.
We’re sorry. The page you’re looking for is no longer available. To search again or contact us, please visit our Help Centre.