How do I add PayPal Checkout to my custom 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. |
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. |