Third-Party Shopping Carts – The Cart Upload Command

Third-party shopping carts integrate PayPal Payments Standard on behalf of PayPal merchants. Third-party carts use the Cart Upload command to pass the contents of shopping carts to PayPal for checkout and payment processing.

Note: If you are not a shopping cart developer, you can add a PayPal Shopping Cart to your site that is hosted by PayPal.

Read the following topics to learn more about third-party shopping carts:

Important This chapter includes unencrypted button code examples for illustrative purposes only. In reality, you must always use encrypted or hosted buttons in your web pages to prevent malicious users from tampering with the code. See Securing Your PayPal Payments Standard Buttons for instructions.

For a complete list of PayPal hosted button images and logos, see the Button Image Reference.

The Checkout Experience With the Cart Upload Command

The PayPal checkout experience with the Cart Upload command begins on a merchant's shopping cart page, when someone clicks the check-out button. Alternatively, it begins when someone selects PayPal on the merchant's payment methods page.

The example below shows how a third-party shopping cart works with PayPal and PayPal Payments Standard. The example merchant has the following account profile settings:

What Buyers See With Third-Party Shopping Carts

Steve is shopping for photos on the Designer Fotos website. He selects several photos for purchase by clicking the Add to Cart button underneath each one.

Figure 1. Third-Party Shopping Cart – Add to Cart


In this example integration, the third-party shopping cart is programmed by the vendor to display the contents of the cart each time Steve clicks an Add to Cart button. In addition, Steve can click the View Cart link at any time to review the items already in the cart and to begin the PayPal PayPal Payments Standard checkout experience.

Figure 2. Third-Party Shopping Cart – View Shopping Cart


After selecting the items he wants to buy and specifying their quantities, Steve clicks the Proceed to Checkout button.

Steve's browser is redirected to the PayPal website. Buyers with PayPal accounts can enter their PayPal account credentials and click the Log In button to access information already on file with PayPal, such as shipping addresses.

Figure 3. Third-Party Shopping Cart – PayPal Payment Log-in Page


Note: If your website gathers information about your buyer, you can define HTML code to prepopulate (prefill) the corresponding billing information fields. The buyers will see a collapsed version of the billing information section. For example, if you prefilled the billing address, the address information displays on the page without the entry fields. Each prefilled section of information is followed by a change link to let the buyers modify the information, if necessary.

For more information about prepopulation, see Filling Out FORMs Automatically with HTML Variables.

Steve does not have a PayPal account, so he clicks Don't have a PayPal account? to enter his payment and billing information on the payment login page. He clicks the Agree and Continue button. A review page displays the details of his payment.

Figure 4. Third-Party Shopping Cart – PayPal Payment Review Page


Designer Fotos has set up Shipping Calculations in the account profile, so PayPal calculates shipping costs automatically and adds them to the order.

Steve clicks the Pay Now button to complete the payment. In response, the browser takes Steve to a payment confirmation page.

Figure 5. Third-PartyShopping Cart – PayPal Payment Confirmation Page


Steve can:

  • Click Print Receipt to view and print a PayPal payment receipt.
  • Click Go to PayPal account overview to view his account.
  • Click Link your bank account to your PayPal account now to add a bank account to his PayPal account.

Steve clicks Print Receipt to get a copy for his records.

Figure 6. Third-PartyShopping Cart – PayPal Payment Receipt


PayPal sends Steve an email notice of his payment to Designer Fotos.

PayPal also sends Designer Fotos an email notice of Steve's payment.

Note: Designer Fotos (the user seller@designerfotos.com) can also see the payment in the PayPal account history.

Implementing the Cart Upload Command

Instead of relying on the PayPal Shopping Cart, many merchants use third-party shopping carts that are already integrated with PayPal. The section describes how you can use the Cart Upload command to integrate PayPal Payments Standard with your third-party cart.

Required Third-Party Shopping Cart Variables

Your HTML code requires at least the following hidden HTML variables. For a complete list of variables, see HTML Variables for PayPal Payments Standard.

Table 1. Required Third-Party Shopping Cart Variables
Name Description
amount_1 Price of a single item or the total price of all items in the shopping cart
business Email address of your PayPal account
item_name_1 Name of the item or a name for the entire shopping cart
upload Indicates the use of third-party shopping cart

There are two ways to integrate your third-party shopping cart with PayPal and PayPal Payments Standard:

  • Pass the details of the individual items.
  • Pass the aggregate amount of the total cart payment rather than the individual item details.

Passing Individual Item Details to PayPal

If you code your third-party shopping cart to pass individual items to PayPal, information about the items is included in buyers' and merchants' transaction histories and notifications.

  1. Set the cmd variable to _cart.
  2. Include the upload variable:
    <input type="hidden" name="upload" value="1">
    
  3. Define item details for each item in the cart.

Specify the required variables and any optional variables listed in Technical HTML Variables. Append _x to the variable name, where x is the item number, starting with 1 and increasing by one for each item added to the cart. The first item in the cart must be defined with variables ending in _1, like item_name_1, amount_1, and quantity_1; the second item with variables like item_name_2, amount_2, and quantity_2; the third item with variables like item_name_3, amount_3, and quantity_3; and so on.

TipImportant: Sequentially increment the _x value by 1 to have PayPal recognize each item. Skipping one or more numbers in the sequence causes PayPal to ignore items.. For example, if you skip from item #1 to item #3 without defining an item #2, PayPal ignores the third item.

The minimum required HTML for your post to PayPal looks similar to that shown below.

Important: The example button code shown below is unencrypted for illustrative purposes only. In reality, you must always use encrypted or hosted buttons in your web pages to prevent malicious users from tampering with the code. See Securing Your PayPal Payments Standard Buttons for instructions.

HTML for Passing Individual Item Detail to PayPal

<form 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="seller@dezignerfotos.com">
<input type="hidden" name="item_name_1" value="Item Name 1">
<input type="hidden" name="amount_1" value="1.00">
<input type="hidden" name="shipping_1" value="1.75">
<input type="hidden" name="item_name_2" value="Item Name 2">
<input type="hidden" name="amount_2" value="2.00">
<input type="hidden" name="shipping_2" value="2.50">
<input type="submit" value="PayPal">
</form>

Setting Currency in the Cart

PayPal interprets all monetary variables (amount_x, shipping_x, shipping2_x, handling_x, tax_x, and tax_cart) in the currency designated by the currency_code variable posted with the payment. Because currency_code is not item-specific, there is no need to append _x to the currency_code variable name. If you do not post a currency_code variable, all monetary values default to U.S. Dollars.

Setting Tax on Individual Items

Use the tax_x variable to specify the tax for a particular item in the cart. For example, the following line specifies that the tax on item 2 in the cart is 15 cents:

<INPUT TYPE="hidden" name="tax_2" value=".15">

Setting Profile-Based Shipping Charges by Weight on Individual Items

Use the weight_x and weight_unit variables to specify item weights if the merchant uses weight-based shipping rates. For example, the following lines specify the weight of item 3 in the cart as 1.5 kg.

<INPUT TYPE="hidden" name="weight_3" value="1.5">
<INPUT TYPE="hidden" name="weight_unit" value="kgs">

Use the quantity_x variable if the merchant uses quantity-based shipping rates. For example, the following line specifies that the quantity for item 3 in the cart is 6.

<INPUT TYPE="hidden" name="quantity_3" value="6">

For information on how merchants set up wieght-based shipping rates, see the Automatic Calculation of Shipping Charges (U.S. Merchants Only).

Setting the Tax for the Entire Cart

Use the tax_cart variable to specify a tax amount that applies to the entire transaction rather than to individual items. The tax_cart variable overrides any per-item tax amount specified with tax_x.

Setting the Weight for the Entire Cart

Use the weight_cart and weight_unit variables to specify the total weight of the cart, if the merchant uses weight-based shipping rates. The weight_cart variable overrides any per-item weights specified with weight_x.

Setting Discounts for the Cart

Use the discount variables to specify discount amount or percentages.

  • Use discount_amount_cart to charge a single discount amount for the entire cart.
  • Use discount_amount_x to set a discount amount associated with item x.
  • Use discount_rate_cart to charge a single discount percentage for the entire cart.
  • Use discount_rate_x to set a discount percentage associated with item x.

The discount amount displays on all pages, email messages, and reports that show payment information.

Default Tax and Discount Processing

Item-specific discounts apply before tax calculation for items in the third-party cart. Discounts and tax apply to each item based on the discounts and tax rate specified. However, your buyer sees only a total discount amount for the cart and one entry for any applicable sales tax.

Setting Consolidated Discount Amounts

Consolidated discounts apply to the entire cart. PayPal calculates the tax on the total of all items after applying the consolidated discount value. Your buyer sees a total discount amount for the cart and one entry for any applicable sales tax.

When you use consolidated discount amounts, you should specify a consolidated tax value in tax_cart. If you do not specify a tax value and your profile specifies a tax rate, PayPal applies your profile tax rate after applying the consolidated discount value.

PayPal ignores consolidated discount amounts if your third-party cart contains any item with an individual tax amount or rate specified using tax_x or tax_rate_x.

Passing the Aggregate Shopping Cart Amount to PayPal

You can aggregate your entire shopping cart and pass the total amount to PayPal. You must post a single item_name_1 for the entire cart and the total price of the cart contents in amount_1 as though it were a purchase of a single item.

Note: One drawback to passing aggregate cart information is that buyers do not see the individual items in their order on the PayPal payment pages.

The HTML code shown below is identical to the example in Passing Individual Item Details to PayPal, except here the example aggregates the individual item amounts and item names into a single amount and a single item.

Important: The example button code shown below is unencrypted for illustrative purposes only. In reality, you must always use encrypted or hosted buttons in your web pages to prevent malicious users from tampering with the code. See Securing Your PayPal Payments Standard Buttons for instructions.

HTML for Aggregate Cart Detail to PayPal

<form 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="seller@designerfotos.com">
<input type="hidden" name="item_name_1" value="Aggregated items">
<input type="hidden" name="amount_1" value="3.00">
<input type="submit" value="PayPal">
</form>

Securing Your Shopping Cart

After you have customized you third-party shopping cart, protect against malicious users tampering with the button code and submitting an incorrect charge by using one of the methods described in Securing Your PayPal Payments Standard Buttons.

Implementing the Instant Update API With the Cart Upload Command

The Instant Update API is a callback-style API that lets you update PayPal in real time with shipping, insurance, and tax amounts when buyers change their shipping address on the PayPal Review Your Payment page.

Read these topics to learn more about implementing the Instant Update API:

About the Instant Update API and the Cart Upload Command

The Instant Update API is a server call to your callback server that instantly updates PayPal pages and enhances the Express Checkout experience on the Review your information page.

Here is how the Instant Update API works:

  1. When a buyer logs in to PayPal, the PayPal server calls your callback server with the buyer's default shipping address, which is stored in the PayPal system.
  2. Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
  3. PayPal displays this information on the Review your information page so buyers can choose from the options.

How Instant Update Works With the Cart Upload Command

The figure below shows how the Instant Update callback works in the Cart Upload checkout experience.

Figure 7. How Instant Update Works in the Cart Upload Checkout Experience


The checkout experience proceeds from left to right. Numbered events in the illustration above are described below.

  1. The checkout experience begins when a buyer clicks the checkout button on the Shopping Cart page of your third-party cart.

    In the HTML code of the checkout button, provide the URL where PayPal can call your callback server, as well as fallback tax, shipping and insurance amounts. If you or your carrier base shipping rates on shipment size, include the shippping dimension HTML variables on individual items in the cart.

  2. The buyer is redirected to PayPal to enter billing information or to log in to PayPal.
  3. Before displaying the PayPal Review page, PayPal sends the buyer's shipping address to your callback server.

    Every time the buyer changes the shipping address, PayPal calls your callback server.

  4. Your callback server calculates tax, shipping, and insurance, based on the address in the callback request.

    Calculate the amounts in your own code, or request the shipping and insurance amounts from your preferred carrier. If the address in the request is outside of the areas where you ship, respond with NO_SHIPPING_OPTION_DETAILS set to 1.

  5. PayPal updates the Review Your Payment page to show the options and rates that you sent back in the callback response from your callback server.
  6. The buyer makes final selections and clicks the Pay button.
  7. PayPal displays a confirmation page, from which the buyer can click a link to print a receipt.

Implementing Instant Update With the Cart Upload Command

You need a callback server to respond to Instant Update requests from PayPal. Also, you need to add Instant Update HTML variables to your Cart Upload command to set up the checkout for Instant Update.

  1. Set up a secure server as your Instant Update callback server to accept Instant Update requests from PayPal.
  2. Develop you callback server to process Instant Update requests and respond with tax, shipping, and insurance amounts.
  3. Modify the HTML code of your Cart Upload commands by adding Instant Update HTML variables:
    • The URL of your callback server and the timeout duration
    • Fallback tax, shipping options, and an insurance amount. You must specify at least 1 shipping option
    • Dimensions for all individual items, if you base shipping rates on shipping dimensions
  4. Eliminate your shipping options page.
  5. Test your implementation of the callback and your fallback options.

The Review Your Payment Page After Implementing Instant Update

After you integrate the Instant Update API, you can display the shipping options, related insurance options, and the tax amount. You control what to display, which is instantly updated on the page.

The shipping options, related insurance options, and the tax amount appear on the page, as follows:

Figure 8. PayPal Review Your Payment Page With Shipping Options, Insurance, and Tax


Best Practices for Implementing Instant Update

PayPal recommends its list of best practices as a checklist for completing your implementation of the Instant Update API.

  • Meet the pre-requisites – Provide individual item details instead of aggregate order amounts to take advantage of the Instant Update API.
  • Streamline the checkout experience – Eliminate the shipping options page in your standard checkout experience.
  • Use the default callback timeout – Use the recommended 3-second callback response timeout.
  • Follow PayPal-defined semantics and syntax – Adhere to well-formed variable names and syntax rules in the callback response to PayPal. If errors occur in the response, PayPal uses the fallback options.
  • Ensure a consistent and good buyer experience – When fallback shipping options are used, you should honor the rates to ensure a consistent and good buyer experience.
  • Localize shipping options – Return localized shipping options, based on the buyer's country and locale, which PayPal sends in the callback request.

Other Considerations for Implementing Instant Update

When you implement the callback, you must consider callback response errors, .timeouts, and shipping options.

Callback Response Errors

If there are any callback response errors, PayPal responds by displaying the fallback options on the PayPal Review Your Payment page. To obtain the richer set of options available through the callback, exercise care in the syntax and values you specify and test the callback integration.

Minimum and Maximum Shipping Options

You can specify up to 10 shipping options for the fallback options in the HTML code for the Cart Upload command and for the detailed options based on shipping address in the callback response. You must specify at least 1 shipping option.

Callback Timeouts

If the callback does not return within the timeout period, PayPal displays the fallback shipping options you specified in the HTML code for the Cart Upload command in the drop-down menu on the PayPal Review Your Payment page.

The PayPal Review your information page in the figure below shows 2 shipping options from which the buyer can choose if the callback times out. An amount of $1.00 is offered for insurance:

Figure 9. Example PayPal Review Page When Callback Times Out


You Do Not Ship to the Buyer's Shipping Address

If you do not ship to the buyer's shipping address that PayPal sends in the callback request, set NO_SHIPPING_OPTION_DETAILS to 1 in the callback response.

The sample code below illustrates the callback response when you do not ship to the buyer's address.

METHOD=CallbackResponse
NO_SHIPPING_OPTION_DETAILS =1
CALLBACKVERSION= <61.0 or greater >

When your callback server sends the previous response, the Review your information page has these features:

  • A message at the top of the page indicates that your business does not ship to this location.
  • The shipping and handling section and the insurance section are dimmed.
  • The buyer can change the shipping address.
  • A new callback request is sent if the buyer changes the shipping address.
Figure 10. Example PayPal Review Page When You Do Not Ship to the Buyer's Address


Setting Up the Callback for Instant Update

To set up the callback, establish a connection with PayPal by providing the location where PayPal calls your callback server, along with your shipping options.

There are two sides to setting up the Instant Update callback:

  • Establishing your Instant Update callback server
  • Passing Instant Update callback information to PayPal

Establishing Your Instant Update Callback Server

To start, you must build and operate a secure, reliable, and fast callback server that computes shipping options, corresponding insurance options, and tax, based on your business rules. To verify that callback requests originate from PayPal.

The HTTP protocol to specify in your callback URL depends on the integration environment you are using:

  • The callback URL must start with HTTPS for production integration.
  • The callback URL must start with HTTP or HTTPS for PayPal Sandbox integration.

Passing Instant Update Callback Information to PayPal

You pass Instant Update callback information in the HTML code of the Cart Upload command. The Instant Update HTML variables let you specify the URL of you callback server and the fallback values for shipping, insurance, and tax amounts.

To set up the Cart Upload command for Instant Update during the checkout experience, use at a minimum the following Instant Update HTML variables:

  • callback_url – the URL of your callback server
  • callback_timeout – always use the value 3, unless instructed otherwise by PayPal
  • fallback_shipping_option_x – one or more sets of shipping option variables.

    You must include 1 instance of this variable, with its index (x) set to 0. If you include just 1 instance, you must include fallback_shipping_option_is_default_x with its index (x) set to 0 and its value set to 1.

The sample code below illustrates a basic setup for the Instant Update callback, which you include in the HTML Form variables for the Cart Upload command.

...
<input type="hidden" name="callback_url" value="your_callback_server_URL">
<input type="hidden" name="callback_timeout" value="3">
<input type="hidden" name="callback_version" value="61"><!--Required! -->

<input type="hidden" name="fallback_shipping_option_name_0" value="Option 1">
<input type="hidden" name="fallback_shipping_option_amount_0" value="1">
<input type="hidden" name="fallback_shipping_option_is_default_0" value="1">

<input type="hidden" name="fallback_shipping_option_name_1" value="Option 2">
<input type="hidden" name="fallback_shipping_option_amount_1" value="3">
<input type="hidden" name="fallback_shipping_option_is_default_1" value="0">
<input type="hidden" name="fallback_insurance_option_offered" value="0">
...

Responding to the Callback for Instant Update

PayPal sends your callback server an Instant Update request whenever buyers enter billing information or log in to PayPal to make payments. Your callback server calculates shipping options and rates and sends them back to PayPal, in Name-Value pair (NVP) format.

PayPal sends Instant Update callback requests to the location that you specified with the callback_url HTML variable. The fields in the callback request include:

  • Individual item details that you included in the Cart Upload command.
  • Shipping address of the buyer.

Using the information in the callback request, calculate the rates and options yourself or send the information in an API call to your carrier to perform the calculations for you. Then send the shipping options, insurance amounts, and taxes to PayPal in the callback response.

The Callback Request for Instant Update With the Cart Upload Comand

Callback requests specify the shipping addresses that buyers want to use when they are about to complete a payment. Also, callback requests include individual item details for the payments that buyers want to complete.

The sample code below illustrates an Instant Update callback request, with these features:

  • 2 individual item details, which can be used to calculate taxes
  • Weight information with one line item, which can be used to calculate shipping charges
  • A shipping address
METHOD=CallbackRequest
&CALLBACKVERSION=57.0
&CURRENCYCODE=USD
&LOCALECODE=en_US
&L_NAME0=10% Decaf Kona Blend Coffee
&L_NUMBER0=623083
&L_DESC0=Size: 8-oz
&L_AMT0=9.95
&L_QTY0=2
&L_NAME1=Coffee Filter bags
&L_NUMBER1=6230
&L_DESC1=Size: Two 24-piece boxes
&L_AMT1=39.70
&L_QTY1=2
&L_ITEMWEIGHTUNIT1=lbs
&L_ITEMWEIGHTVALUE1=0.5
&SHIPTOSTREET=1 Main St
&SHIPTOCITY=San Jose
&SHIPTOSTATE=CA
&SHIPTOCOUNTRY=US
&SHIPTOZIP=95131
&SHIPTOSTREET2

The Callback Response for Instant Update With the Cart Upload Command

Callback responses let you specify one or more shipping options, with unique shipping, insurance, and tax amounts. Your callback server calculates the amounts based on shipping addresses that buyers provide during the PayPal checkout experience.

The sample code below illustrates an Instant Update callback response, with these features:

  • Shipping insurance, with a different amount for each shipping option
  • 3 shipping methods, with different shipping amounts
  • Taxes, with different amounts for each shipping method
  • The UPS Expedited shipping method is the default method
METHOD=CallbackResponse
&OFFERINSURANCEOPTION=true
&L_SHIPPINGOPTIONNAME0=UPS Air
&L_SHIPPINGOPTIONLABEL0=UPS Next Day Air Freight
&L_SHIPPINGOPTIONAMOUNT0=20.00
&L_TAXAMT0=2.20
&L_INSURANCEAMOUNT0=1.51
&L_SHIPPINGOPTIONISDEFAULT0=false
&L_SHIPPINGOPTIONNAME1=UPS Expedited
&L_SHIPPINGOPTIONLABEL1=UPS Express 2 Days
&L_SHIPPINGOPTIONAMOUNT1=10.00
&L_TAXAMT1=2.00
&L_INSURANCEAMOUNT1=1.35
&L_SHIPPINGOPTIONISDEFAULT1=true
&L_SHIPPINGOPTIONNAME2=UPS Ground
&L_SHIPPINGOPTIONLABEL2=UPS Ground 2 to 7 Days
&L_SHIPPINGOPTIONAMOUNT2=5.99
&L_TAXAMT2=1.99
&L_INSURANCEAMOUNT2=1.28
&L_SHIPPINGOPTIONISDEFAULT2=false

The sample code above produces the following result on the PayPal Review Your Payment page: