Vendors who use our 3rd party cart parameters often wish for the product details to be displayed on our 2Checkout.com order page. By default, when using this parameter set, only the value of the cart_order_id parameter and the total of the sale are displayed on this page. Did you know it was possible for you to create the products in your vendor account, reference them with a few parameters, and still pass 2Checkout an arbitrary total value? The process is quite simple. We will start from the beginning and you are welcome to follow along by placing your Supplier ID number as the value for the sid parameter in our example links.

Continue reading…

It has become necessary for 2CO to know the specific product that is being sold at the time of sale and for that product’s description to be stored in our database for reference. This change is required both by 2CO and by our banking partners to better mitigate risk and to monitor items being sold. Because of this requirement, we are asking cart makers and/or users to make changes to their cart or programs so that additional information about the items being sold is passed to 2CO.

It is very important to note that:

1. All previous parameters remain supported and should continue to be passed in (2CO, Authorize.net),
2. The parameter total (or the authorize.net parameter : x_amount) passed in for the order will continue to be the amount billed for the sale,
3. The paramaters cart_order_id and sid (or the authorize.net parameters: x_invoice_num and x_login) are still manditory with this parameter set.

REQUIRED PARAMETERS
These parameters are required to identify cart products being purchased and should be supplied ASAP.

For some clients it may make sense to create 1 or multiple generic products in the 2CO db, like “Premium Hosting”, “Super Saver Hosting” and pass in a total for the sale as generated on their site. If this option works for you please make the product name reasonably descriptive, (i.e. “website design services” would be a good description, “web services” a poor one for the same item ).

• c_prod or c_prod_[:digit] : This parameter will contain either the assigned_product_id given to the product upon creation in the 2CO system or a vendor specified id. It may, optionally, also contain the id followed by a ‘,’ (ASCII comma) followed by an integer which will represent the quantity. This parameter should not be autogenerated with each individual sale but should be tied to a specific product. The c_prod value should match whatever external vendor id is recorded in the 2CO system. The external vendor id may be a cart assigned product id or the vendors own internal product id as long as the value matches the value stored in the 2Co system. Examples of valid values:
  • 1
  • my_product_17
  • product_5,3
• id_type This parameter will contain an integer value representing the type
  or classification of the ids used in the c_prod parameter(s). This value will
  apply universally per transaction. That is to say c_prod parameters must contain
  only assigned_product_id values or only vendor_product_id values. Current
  valid values for this parameter are defined as follows.
  • 1 is defined as vendor_product_id
  • 2 is defined as assigned_product_id
  • 3 - 0 are reserved for future use.

OPTIONAL PARAMETERS
These parameters are intended for carts that retain no product database or as a transition method of populating the 2CO database. Although it is desirable to receive as many parameters as possible with the purchase the option of creating products on the fly should only be used when no other options exist.

• sh_cost (optional) : This parameter will contain shipping and handling cost, if any. The sh_cost parameter is completely optional. This parameter has the same format rules as the parameter containing the total (total or x_amount) that you are currently using. This value received is assumed to be in the selected currency of your 2CO account.
  Examples of valid values: 0.50, 5.00, 10
• c_name or c_name_[:digit] : This parameter is required for product information to be displayed at checkout. The value of this parameter should contain the name of the product to be created. It is limited to 128 characters including spaces and punctuation. If the value is too long it will be cut off at 128 characters.
• c_description or c_description_[:digit] : This parameter is required for product information to be displayed at checkout. The value of this parameter should contain a short description of the product to be sold. It is limited to 255 characters including spaces and punctuation. If the value is too long this value will be stored as the long description instead. The long description will not show on the checkout pages but it will be saved in the 2Co product database.
• c_price or c_price_[:digit] : This parameter is required for product information to be displayed at checkout. This value should reflect the price of the product in your 2CO account selected currency. This parameter has the follow format restrictions
  • Numbers and decimal point only.
  • Max value: 999999.99
• c_tangible or c_tangible_[:digit] (optional) : This parameter is optional. If you do not provide a value for it a default value of Y will be used. This field indicates if the product is a physical product or an e-good/service.
  This parameter has the following format restrictions: Valid values: y Y n N

NEW PARAMETERS IN PRACTICE
Below you will find an example form that shows how these new parameters might be implemented:

<form action="https://www.2checkout.com/2co/buyer/purchase" method="post">

	<input type="hidden" name="id_type" value="1">
	<input type="hidden" name="c_prod_1" value="QAWSZX0678,3">
	<input type="hidden" name="c_name_1" value="Sample 	Product">
	<input type="hidden" name="c_description_1" value="Sample Product Description">
	<input type="hidden" name="c_price_1" value="5.00">
	<input type="hidden" name="c_tangible_1" value="N">

	<input type="hidden" name="c_prod_2" value="CABLE0029,1">
	<input type="hidden" name="c_name_2" value="A Second Sample Product">
	<input type="hidden" name="c_description_2" value="This Products Description">
	<input type="hidden" name="c_price_2" value="10.00">
	<input type="hidden" name="c_tangible_2" value="N">

	<input type="hidden" name="sid" value="XXXXXX">
	<input type="hidden" name="cart_order_id" value="050304-102658-3874">
	<input type="hidden" name="total" value="25.00">

	<input type="submit">
</form>

Please note that you will need to replace the sample values with your own.

Below are the parameters supported by the Plug and Play Cart. These parameters can only be used if you have added your products to the 2CO database. You are using the Plug and Play cart if you are passing in the three parameters listed under the Required section below.

Multi-page Payment Routine:
https://www.2checkout.com/2co/buyer/purchase
Supports all payment methods. Supports tangible and intangible products/services.

Single Page Payment Routine:
https://www.2checkout.com/checkout/spurchase
Credit card-only payment routine only available for intangible products/services.

Required Parameters:
sid - Your 2checkout vendor account number (64 characters max)
product_id - The 2CO ID for the product or service in the 2Checkout database
quantity - The Quantity of the product (99 max value)

Additional Parameters:
demo - Y to enable demo mode, do not pass this in for live sales
fixed - Y to remove the Continue Shopping button and lock the quantity fields
lang - “sp” for Spanish purchase routine pages, defaults to English if this is absent, but “en” may be used for English as well.
return_url - used to control where the Continue Shopping button will send the customer when clicked (255 characters max)
merchant_order_id - Specify your order number with this parameter. It will also be included in the confirmation emails to yourself and the customer. (50 characters max)
pay_method - CC for Credit Card, CK for check, PPI for PayPal, PPL for PayPal Pay Later, or FXS for FXSource. This will set the default selection on the payment method step during the checkout process.
skip_landing - If set to 1 it will skip the order review page of the purchase routine. If there are options on the products it will cause an error and redirect the customer back to the order review page.

To populate the billing information page you may pass in:
card_holder_name - Card holder’s name. (128 characters max)

The card holder’s name can also be populated using the first_name, middle_initial, and last_name parameters. IMPORTANT: If you use these three parameters, the data will be combined into and returned as card_holder_name to your Approved URL script.

street_address - Card holder’s street address (64 characters max)
street_address2 - The second line for the street address, typically suburb or apartment number information (64 characters max)
city - Card holder’s city (64 characters max)
state - Card holder’s state (64 characters max)
zip - Card holder’s zip (16 characters max)
country - Card holder’s country (64 characters max)
email - Card holder’s email address (64 characters max)
phone - Card holder’s phone number (16 characters max)
phone_extension - Card holder’s phone extension (9 characters max)

To populate the shipping information page you may pass in:
ship_name
ship_street_address
ship_street_address2
ship_city
ship_state
ship_zip
ship_country

Please note that shipping information will only be collected for items that are defined as tangible in our system. Shipping is also only charged for tangible items. We will ask for shipping information if you pass in any of the shipping parameters, regardless of whether the item is tangible or not. This does not mean we will apply shipping charges to the sale, but their information will be collected.

The billing information page will also be populated with the information from the shipping page if the shipping information is collected on that sale and the billing information is not passed in.

Custom Parameters:
You may pass in any additional parameters that you may need and they will be returned to you at the end of the sale. The only restrictions on custom parameters are that they can not share the name of ANY parameter that our system uses, even from the other sets. Please note that you WILL need a return script set up on the Look and Feel page to receive any of these parameters back as they are not included in the confirmation emails.

Passing Multiple Plug and Play Products:
You may also pass multiple plug and play products in one form. To do this add a corresponding digit to the quantity and product_id parameters to group them for each product. For example, if we wanted to pass two products into the system we would be passing in first the sid parameter, then product_id1 and quantity1, and then product_id2 and quantity2.

Example:

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123' >
<input type='hidden' name='quantity1' value='1' >
<input type='hidden' name='product_id1' value='1008' />
<input type='hidden' name='quantity2' value='1' >
<input type='hidden' name='product_id2' value='1014' >
<input type='hidden' name='quantity3' value='1' >
<input type='hidden' name='product_id3' value='1011' >
<input name="submit" type='submit' value='Buy from 2CO' >
</form>

You can receive back all of the parameters that were passed in as well as the following parameters:
order_number - 2Checkout.com order number
total - the total amount of the purchase
ship_method - the shipping method that was selected for this order (if applicable)
credit_card_processed - Y if successful (Approved), K if waiting for approval (Pending)
merchant_product_id - your product ID for purchased item
key - the MD5 hash that can be used to verify that the sale came from one of our servers

Also note that this is the only parameter set that can be used for recurring billing with our service.

Important: You can not mix the three parameter sets. This will cause problems during payment or may prevent the payment pages from working at all.

Related Article: Country Codes

Below you will find a listing of the supported Authorize.net-compatible parameters and what information each parameter should contain. This parameter set is used by third party carts and custom designed scripts. Please note that 2Checkout must know what is being sold in every sale. There are parameters available that allow for dynamic product creation. These will be discussed as well, and must be used if you are using this parameter set, but they are not Authorize.Net specific.

Multi-page Payment Routine:
https://www.2checkout.com/2co/buyer/purchase
Supports all payment methods. Supports tangible and intangible products/services.

Single Page Payment Routine:
https://www.2checkout.com/checkout/spurchase
Credit card-only payment routine only available for intangible products/services.

Required Parameters:
x_login - your numerical 2checkout vendor account number.
x_amount - the total amount to be billed, without a currency symbol, and only two decimal places if used (8 characters, decimal, 2 characters: Example: 99999999.99)
x_invoice_num - a unique order id from your system. (64 characters max)

Additional Parameters:
demo - Y to enable demo mode, do not pass this in for live sales
lang - “sp” for Spanish purchase routine pages, defaults to English if this is absent, but “en” may be used for English as
well.
merchant_order_id - Specify your order number with this parameter. It will also be included in the confirmation emails to yourself and the customer. (50 characters max)
pay_method - CC for Credit Card, CK for check, PPI for PayPal, PPL for PayPal Pay Later, or FXS for FXSource. This will set the default selection on the payment method step during the checkout process.
skip_landing - If set to 1 it will skip the order review page of the purchase routine. If there are options on the products it will cause an error and redirect the customer back to the order review page.
x_Receipt_Link_URL - An additional parameter that behaves as follows (no limit):

• This parameter will over-ride any URL set on the Look and Feel page.
• If Direct Return is disabled: If only one product is ordered, it will over-ride the return URLs on the product as well. If more than one product is ordered, then this parameter will control where the “Click Here to Notify [Your Company]” button on the final page takes the customer, but the return URLs on the products will be listed as links below the button, next to the description of the product.
• If Direct Return is enabled : If one product is ordered, this parameter will NOT over-ride the return URLs on the products. If more than one product is ordered, then this parameter will over-ride the product return URLs. Also keep in mind that many third party shopping carts recommend that Direct Return be disabled to work properly.

To populate the billing information page you may pass in:
x_First_Name - buyers first name (64 characters max)
x_Last_Name - buyers last name (64 characters max)
x_Phone - buyers phone number (16 characters max)
x_Email - buyers email address (64 characters max)
x_Address - buyers address (64 characters max)
x_City - buyers city (64 characters max)
x_State - buyers state (64 characters max)
x_Zip - buyers zip code (16 characters max)
x_Country - buyers country (64 characters max)

To populate the shipping information page you may pass in:
x_Ship_To_First_Name
x_Ship_To_Last_Name
x_Ship_To_Address
x_Ship_To_City
x_Ship_To_Country
x_Ship_To_State
x_Ship_To_Zip

Please note that since this parameter set is for third party shopping carts, we do not collect shipping information for these types of orders. This is because your cart is responsible for calculating the shipping and it is passed in as part of the x_amount parameter. We will present the shipping information page if any of the shipping parameters are passed in, but this does not mean we will apply shipping charges to the order. If the shipping information is passed in, we will also populate the billing information using that information unless any of the above parameters are passed in by your cart to populate the billing information page.

It is also important to note that when using the Authorize.Net set of parameters, 2CO only requires the three listed under the required section. We will therefore not passback strictly Authorize.Net style parameters for everything unless they are passed in to us. This is not often a problem as most carts do this anyways. For example, x_First_Name and x_Last_Name will prepopulate the billing name, but 2CO uses cardholder_name for this. cardhold_name will then be returned unless x_First_Name and x_Last_Name are passed into 2Checkout.

Custom Parameters:
You may pass in any additional parameters that you may need and they will be returned to you at the end of the sale. The only restrictions on custom parameters are that they can not share the name of ANY parameter that our system uses, even from the other sets. Please note that you WILL need a return script set up on the Look and Feel page to receive any of these parameters back as they are not included in the confirmation emails.

Return Parameters:
You can receive back all of the parameters that were passed in as well as the following parameters:
x_2checked - Y if card was successfully processed, K if pending.
x_MD5_Hash - The MD5 hash that can be used to verify that the sale came from a 2CO server.
x_trans_id - the 2CO order number for the order.

Using this parameter set, we are not receiving any product information. As you can see, you are only passing in a total amount to us. Usually, the cart will have some means of using the x_invoice_num to determine what was purchased after the sale. A return URL will need to be set up on the Look and Feel page for the cart to correctly determine this.

Consult the documentation that came with your cart or contact the cart manufacturer for assistance with setting this up or to determine what URL you should enter on the Look and Feel page for your cart to receive the product information.

Recurring billing can not be done with this parameter set. You must use the Plug-N-Play parameter set and have the products defined within the 2CO database for recurring billing.

Product Creation Parameters:
As mentioned above, 2CO must know what is being sold in every sale. Parameters are available to suppliers to fulfill this requirement with third party cart sales. These parameters will also benefit suppliers as when used correctly the product information will be displayed to customers on the purchase pages and will be listed on the sale detail page to suppliers. Information on these parameters is available here.

Important: You can not mix the three parameter sets. This will cause problems during payment or may prevent the payment pages from working at all.

Related Article: Country Codes

An HTTP 404 File Not Found error indicates that the URL specified as for your script is incorrect. For the pass back to function, 2CO must be able to locate and access the script and post the variables to it.

HTTP errors are not generated specifically by 2Checkout. They are a part of the HTTP protocol and are common amongst all web servers. It is therefore beyond the realm of 2Checkouts support to provide you with specific instructions for making these changes as every server is set up differently and 2CO does not provide server administration services as part of our support plan.

To correct this issue, follow these steps:

1. Login to your account.
2. Under the ‘Helpful Links’ section, click on ‘Settings’ near the ‘Look and
   Feel’ section.
3. Check the URL that is currently entered there and correct any mistakes that
   it may contain.
4. Click ‘Save Changes’.