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.
Read the following topics to learn more about third-party shopping carts:
- The Checkout Experience With the Cart Upload Command
- Implementing the Cart Upload Command
- Implementing the Instant Update API With the Cart Upload Command
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:
PayPal Account Optional is turned on –
The buyer can pay without an existing PayPal account and is offered
the chance to sign up for one after completing the payment.
For more information, see PayPal Account Optional.
- Shipping Calculations have been set up – PayPal calculates the shipping charges automatically and adds them to the order.
is turned off – Buyers must click a Return to Merchant button
to redirect their browsers to the merchant website after completing
their payments with PayPal.
For more information, see Auto Return.
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.
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.
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.
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.
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.
- 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.
PayPal sends Steve an email notice of his payment to Designer Fotos.
PayPal also sends Designer Fotos an email notice of Steve's payment.
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.
||Price of a single item or the total price of all items in the shopping cart|
||Email address of your PayPal account|
||Name of the item or a name for the entire shopping cart|
||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.
- Set the
cmdvariable to _cart.
- Include the
<input type="hidden" name="upload" value="1">
- 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
quantity_1; the second
item with variables like
quantity_2; the third
item with variables like
quantity_3; and so
_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.
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="email@example.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
all monetary variables (
tax_cart) in the
currency designated by the
posted with the payment. Because
not item-specific, there is no need to append
_x to the
name. If you do not post a
all monetary values default to U.S. Dollars.
Setting Tax on Individual Items
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
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">
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
to specify a tax amount that applies to the entire transaction rather than
to individual items. The
overrides any per-item tax amount specified with
Setting the Weight for the Entire Cart
to specify the total weight of the cart, if the merchant uses weight-based
shipping rates. The
overrides any per-item weights specified with
Setting Discounts for the Cart
Use the discount variables to specify discount amount or percentages.
discount_amount_cartto charge a single discount amount for the entire cart.
discount_amount_xto set a discount amount associated with item
discount_rate_cartto charge a single discount percentage for the entire cart.
discount_rate_xto set a discount percentage associated with item
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
PayPal ignores consolidated discount amounts
if your third-party cart contains any item with an individual tax
amount or rate specified using
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
the entire cart and the total price of the cart contents in
amount_1 as though
it were a purchase of a single item.
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.
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="firstname.lastname@example.org"> <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:
- 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.
- Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
- 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.
The checkout experience proceeds from left to right. Numbered events in the illustration above are described below.
- 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.
- The buyer is redirected to PayPal to enter billing information or to log in to PayPal.
- 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.
- 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
- 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.
- The buyer makes final selections and clicks the Pay button.
- 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.
- Set up a secure server as your Instant Update callback server to accept Instant Update requests from PayPal.
- Develop you callback server to process Instant Update requests and respond with tax, shipping, and insurance amounts.
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
- Eliminate your shipping options page.
- 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:
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.
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:
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
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.
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_xwith its index (x) set to
0and its value set to
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
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: