Hack 50 Integrate a Third-Party Shopping Cart with PayPal

Pass the contents of a non-PayPal shopping cart to PayPal using the Aggregate Cart and Upload Complete Cart features .

Shopping carts have proven to be effective online selling tools and have become a standard on many eCommerce web sites. PayPal makes it extremely easy to add a shopping cart to your web site, because PayPal hosts all the functionality. All you need to do is add the Add to Cart button code to your pages [Hack #45] .

In many cases, however, the PayPal Shopping Cart is insufficient for merchants who might need a more customized design, more sophisticated tax and shipping calculations, or other features that the PayPal Shopping Cart system doesn't offer. Fortunately, using a non-PayPal shopping cart system doesn't mean that you can't still accept PayPal as a payment option.

PayPal offers two ways to integrate your shopping cart: Aggregate Cart and Upload Complete Cart.

5.7.1 Aggregating Your Cart

Of the two systems, PayPal's Aggregate Cart has the advantage of being easier to integrate. Although your shopping cart system might save your customers' cart contents into a database, you don't need to send all this information to PayPal. All you need to do is send PayPal the order ID associated with your customer's shopping cart, along with the total dollar amount for your customer to pay in the amount field.

Since there is no dedicated order_ID parameter, pass the order ID to PayPal in the item_name field for the purpose of Aggregate Cart payments.

You can also add shipping, handling, and tax parameters. Here is the most basic code to do all this:

 <form action="https://www.paypal.com/cgi-bin/webscr" method="post"                 name="form1"> <input type="hidden" name="cmd" value="_xclick"> 1.  <input type="hidden" name="business" value="   [e-mail]   "> 2.  <input type="hidden" name="item_name" value="Order#   21874   "> 3.  <input type="hidden" name="amount" value="   151.80   "> <input type="image" src="http://images.paypal.com/images/x-click- but01.gif"                 name="submit" alt="Pay Now with PayPal"> </form> 

Specify the email address to which the payment should be sent on line 1, a reference to your order on line 2, and the total amount of the items in the customer's cart on line 3.

There are plenty of optional parameters you can include here, all of which are documented in [Hack #28] . Here are some of the most useful:

 <input type="hidden" name="shipping" value="   9.00   ">  <input type="hidden" name="handling" value="   3.00   ">  <input type="hidden" name="tax" value="   21.92   ">  <input type="hidden" name="invoice" value="   442   ">  <input type="hidden" name="custom" value="   paypalhacks   "> 

PayPal hides the invoice and custom fields from the buyer, so make sure not to use them to pass your order ID or any other information you want your customers to see during the checkout process. Instead, use item_name for this purpose. Also, don't use any parameters normally used to specify quantity with Aggregate Cart, because there will likely be multiple items in the cart and the quantity parameter would apply to only one of them.

You might have noticed that these parameters are the same as those used in a regular Buy Now button. The Aggregate Cart feature is essentially a glorified Buy Now button that processes the data for your entire Shopping Cart. It's not terribly sophisticated, but if that's all the functionality you need, this is all the code you need.

5.7.2 Uploading Shopping Cart Details to PayPal

Although Aggregate Cart is easy to implement, it sends only a total dollar amount to PayPal. By contrast, the Upload Complete Cart feature has the distinct ability to send a listing of all the items in the customer's shopping cart to PayPal. This means that PayPal will display a summary of the cart contents on the PayPal site (as shown in Figure 5-4) and record those details within the customer's payment history and in your seller history logs and notifications.

Figure 5-4. Displaying the contents of your customer's shopping cart during the checkout process

To create an Upload Complete Cart button, start with the same HTML code used earlier in this hack with the Aggregate Cart button. Then, for the cmd input value, replace _xclick with _cart , and add a new hidden field called upload and set its value to 1 . (You can remove the item_name and amount fields, because they aren't needed for Update Complete Cart.) You'll then end up with something like this:

 <form action="https://www.paypal.com/cgi-bin/webscr" method="post"                 name="form1">   <  i  nput type="hidden" name="cmd" value="_cart"> <input type="hidden" name="upload" value="1"> <input type="hidden" name="business" value="[e-mail]">   <input type="image" src="http://images.paypal.com/images/x-click-but01.gif"                  name="submit" alt="Pay Now with PayPal">  </form> 

Next , insert the details of the contents of the shopping cart. To add the first item, insert the following code somewhere inside the <form></form> structure:

 1.  <input type="hidden" name="item_name_1" value="PayPal Hacks Book"> 2.  <input type="hidden" name="item_number_1" value="Item#   PPHKS   "> 3.  <input type="hidden" name="quantity_1" value="   1   "> 4.  <input type="hidden" name="amount_1" value="24.95"> 5.  <input type="hidden" name="shipping_1" value="   3.00   "> 6.  <input type="hidden" name="shipping2_1" value="2.00"> 7.  <input type="hidden" name="handling_1" value="1.00"> 

The _1 suffix after each variable name gives every tag an item reference. So, these parameters describe the first item as a single copy of the PayPal Hacks book (line 1) with a product code set to PPHKS (line 2) and a per-item price of $24.95 (line 4).

The cost of shipping, $3.00, is specified on line 5. This is a per-quantity charge: if the quantity (line 3) is more than one, the same $3.00 shipping charge will be applied to each copy of the book ordered. The exception to this rule is when you specify a shipping2 amount (as line 6 does in this example), this shipping amount will be used only for the first item and the shipping2 amount will be charged for each additional book ordered (e.g., three books would cost $3.00 + $2.00 + $2.00, or $7.00, to ship).

The handling cost, $1.00, is specified on line 7 and is applied only once, regardless of the number of items ordered.

Notice that the form method is POST (as opposed to GET ). This allows you to post your data to PayPal without the size limit imposed by the fact that GET places all the form data in the URL.

5.7.3 Adding Additional Items

For every additional item you have in your shopping cart, add another set of parameters. For each parameter, append _n to the variable name, where n is the item number, starting with 1 . Here's a second book thrown into the shopping cart:

 <input type="hidden" name="item_name_2" value="eBay Hacks Book"> <input type="hidden" name="item_number_2" value="Item#   EBHKS   "> <input type="hidden" name="quantity_2" value="1"> <input type="hidden" name="amount_2" value="24.95"> <input type="hidden" name="shipping_2" value="3.00"> <input type="hidden" name="shipping2_2" value="2.00"> <input type="hidden" name="handling_2" value="1.00"> 

You should always verify that the amount paid matches the order total. You can automate this verification by using IPN [Hack #73] and by using the item_name and amount fields to verify that the amount paid to your PayPal account was the same as the total order amount.

5.7.4 Hacking the Hack

Presumably, you'll need to store the contents of a customer's shopping cart in your database before sending the data (and the customer) to PayPal. This means that the Add to Cart buttons on your site will need to submit data to your own server, and then, at checkout, your server will generate the HTML code for the Upload Complete Cart feature. Unfortunately, this means that you have to include an intermediate page, on which your customer will have to click another button to submit the cart to PayPal.

The solution is to add a little JavaScript to the <body> tag, so that the customer's browser submits the form automatically when the form loads:

 <body onload="document.form1.submit( );"> 

Here is a complete example of the code:

 <html> <body onload="document.form1.submit( );"> <form name="form1" action="https://www.paypal.com/cgi-bin/webscr"                  method="post"> <input type="hidden" name="cmd" value="_cart"> <input type="hidden" name="upload" value="1"> <input type="hidden" name="business" value="[e-mail]">   <input type="hidden" name="item_name_1" value="PayPal Hacks Book"> <input type="hidden" name="item_number_1" value="Item#PPHKS"> <input type="hidden" name="quantity_1" value="1"> <input type="hidden" name="amount_1" value="24.95"> <input type="hidden" name="shipping_1" value="3.00"> <input type="hidden" name="shipping2_1" value="2.00"> <input type="hidden" name="handling_1" value="1.00"> <input type="hidden" name="item_name_2" value="eBay Hacks Book"> <input type="hidden" name="item_number_2" value="Item#EBHKS"> <input type="hidden" name="quantity_2" value="1"> <input type="hidden" name="amount_2" value="24.95"> <input type="hidden" name="shipping_2" value="3.00"> <input type="hidden" name="shipping2_2" value="2.00"> <input type="hidden" name="handling_2" value="1.00"> <input type="image" src="http://images.paypal.com/images/x-click-but01.gif"                  name="submit" alt="Pay Now with PayPal">  </form> </body> </html> 

Depending on the speed of your customer's Internet connection and the traffic at the PayPal server, the page might redirect almost instantly or it might display momentarily for a second or two before the next page is displayed. For this reason, you might want to include some kind of "Please wait..." message on the page so that your customers don't interrupt the process out of confusion. Plus, you still need to include a real Submit button and a sentence of instruction just in case your customer has disabled the browser's support for JavaScript.