2Checkout.com » parameters

Documentation Update

cliff — Thu, 26 Jun 2008 20:52:18 +0000

We’ve recently updated our third party cart parameter articles to simplify our integration requirements.

If you are developing a 2CO-compatible shopping cart, this consolidates our technical requirements into a single document, based on the parameter set you prefer.

Most developers will want to refer to our custom parameter set as detailed in the article titled What are 2Checkout.com’s own parameters?

Developers who prefer to use our supported subset of Authorize.net parameters will want to refer to the article titled What Authorize.net parameters does 2CO support?

As always, if you have any questions about integrating our service with your product, please contact us directly by telephone or by opening a support ticket in the Tech Support category.

TUTORIAL: Creating 2Checkout Purchase Links

simba — Mon, 10 Mar 2008 20:17:57 +0000

There are several different ways you can set up your website using the four different parameter sets available in 2Checkout’s purchase system. The system works through sending HTML parameters (aka. variables) to the purchase routine to initiate a sale, whether they be sent by a HTML submission form or a direct purchase link.

As you are working through developing your integration, you can make use of our developers.2Checkout area to test and play around with the various parameter sets and see their interaction with 2Checkout’s purchase routine.

Universal Parameters

Four universal parameters will be available to use with every set. These parameters assist you with various aspects of integrating the 2Checkout purchase system into your website:

demo — You can set this equal to ‘Y’ to tell the purchase routine that the sale is a test. While the cart will act the same, and even ask you for billing details, no monetary transaction will actually take place.
lang — Set this to ’sp’ to translate the purchase routine into Spanish.
pay_method — This can be set to one of the following values to specifically set the purchase routine to use the specified payment method: ‘CC’ for Credit Card, ‘CK’ for check, ‘PPI’ for PayPal, or ‘PPL’ for PayPal Pay Later.
merchant_order_id — You can set this to any ID number (eg. ‘merchant_order_id=SALE-001′), which will display on the customer’s email receipt of their purchase and can assist you with organizing customers and their purchases within your records.

The following are explanations of the four individual parameter sets available within our system.

Plug and Play Parameters

The Plug-n-Play parameters provide the simplest method for vendors to sell their products. Using this method, vendors will create products inside of their account and then put links to those products on their site. Although we provide other ways to sell products than the Plug-n-Play method, do keep in mind that this is the only method that is able to do recurring orders.

Basic Payment Link

To create a direct purchase link using the basic Plug-n-Play parameters after you have set up the products under your 2Checkout account, you will need to use at least the three base required parameters for the set (sid, product_id, quantity). An example direct payment link looks as such:

https://www.2checkout.com/checkout/purchase?sid=123456&product_id=101&quantity=1

To put this in explainable terms, our purchase routine (https://www.2checkout.com/checkout/purchase) is being told that the customer wants to purchase one (quantity=1) of the product that was assigned an ID of “101″ (product_id=101) by our system from this vendor (sid=123456).

This can also be represented within an HTML form, which can provide you more flexibility in terms of how you construct your site. Below is the base required elements to an HTML submission form for a single product:

Multiple Products in One Form

You can also have multiple products within a direct payment link or HTML submission form. This is helpful for vendors who sell products as a package or in bulk. To do this, you would add an incrementing digit to the end of both ‘product_id’ and ‘quantity’ for each individual product to be purchased. A direct payment link would look like this:

https://www.2checkout.com/checkout/purchase?sid=123456&product_id1=101&
quantity1=1&product_id2=202&quantity2=1

The same format would be reflected within the HTML submission form:

Additional Parameters

In addition to the universal parameters, you also have the ‘fixed’ parameter available as part of this set. Setting this equal to ‘Y’ will lock the quantity fields in the purchase routine and remove the continue shopping button.

More Information

For more information on how to use this parameter set, please refer to the link below:

http://www.2checkout.com/community/?p=205

3rd-Party Cart Parameters

The 3rd-Party Cart parameters works by sending the customer from your website to the 2Checkout purchase routine with only a total amount for the sale and a cart order ID number. This set does not require that you have products established under your 2Checkout account, although it does require that the New Product Creation parameter set be used in combination with this set to specify the details of the products contained within the cart sale. The combination of both sets is best for third party cart software since it allows the cart software on your website to handle most of the checkout process, including maintaining product information within your cart’s administrative area and detailing out products within the cart on the customer’s receipt.

The New Product Creation parameters are actually an extension onto the 3rd-Party Cart and Authorize.net parameter sets. This allows you to send in raw product information to the purchase routine, and will save the product to your 2Checkout account once the sale completes successfully if it has not already been created.

Basic Payment Link

To create a direct purchase link using the 3rd-Party Cart parameters, you will need to use at least the three base required parameters for the set (sid, total, cart_order_id). An example direct payment link looks as such:

https://www.2checkout.com/checkout/purchase?sid=123456&total=2.00&
cart_order_id=CART-001

To break this down, our purchase routine is being instructed that the customer wants to purchase the items in the cart (which, the items in the cart will be managed by the shopping cart software on your website) from the vendor (sid=123456), and total sale amount for the items in the cart plus any shipping charges comes to 1 dollar (total 2.00). The cart order has an ID (cart_order_id=CART-001) which will identify this order uniquely to the vendor amongst other orders.

The above direct payment link can also be represented within an HTML form by using the appropriate INPUT tags for the three required parameters. However, the above link is missing the parameters that specify details about the products contained within the cart sale. While the above link will work and the customer will be charged the amount, there will be no record of the items that are being purchased in the cart. To specify product details, use the New Product Creation set in combination with the 3rd-Party Cart set.

Combining with the New Product Creation Parameters

To specify individual products within the cart sale, you will need to use the following parameters:

c_prod — This parameter should be set to contain either the system-specified ID given to the product upon creation within your 2Checkout account, or a vendor-specified ID. It may, optionally, also contain the ID followed by a comma and an integer representing the quantity. The value of this parameter should not be automatically generated with each individual sale, but should rather be tied to a specific product at all times to avoid creating multiple copies of the same product within your account.
id_type — This parameter will specify the type of IDs being used with the ‘c_prod’ parameter(s). This setting will apply universally per transaction, so ‘c_prod’ parameters must contain only system-specified IDs (if set to ‘1′) or only vendor-specified IDs (if set to ‘2′).
c_name — This will contain the name of your individual product, and will be displayed at the time of checkout so your customer will know what is being purchased.
c_description — This should continue a short description of the details about your product. This will not show on the purchase routine, but it will be saved along with the product under your account.
c_price — This parameter specifies the price for each individual item.
sh_cost — This parameter specifies the cost of the shipping and handling. If there is no shipping and handling, then this parameter may be either set to “0.00″ or completely omitted.

A direct purchase link using the 3rd-Party Cart set in combination with the New Product Creation set in its most basic form would look similar to this:

https://www.2checkout.com/checkout/purchase?sid=123456&total=2.00&
cart_order_id=CART-001&id_type=1&sh_cost=1.00&c_prod=PRODUCT-10&
c_name=Product 10&c_description=This is my 10th product&c_price=1.00

This can also be represented within an HTML form. Below is the base required elements to an HTML submission form for establishing a single new product:

Multiple Products in One Form

You can also specify multiple products. To do this, you would add an underscore followed by an incrementing digit to the end of each parameter that defines products (ie. parameters starting with “c_”). A direct purchase link would look like this:


https://www.2checkout.com/checkout/purchase?sid=123456&total=4.00&
cart_order_id=CART-001&id_type=1&sh_cost=1.00&c_prod_1=PRODUCT-10&
c_name_1=Product 10&c_description_1=This is my 10th product&c_price_1=1.00&
amp;c_prod_2=PRODUCT-20&c_name_2=Product 20&c_description_2=This is my 20th
product&c_price_2=2.00

Converting this to an HTML submission form, it would appear as so:

Authorize.net Parameters

This parameter set works just like the 3rd-Party Cart parameter set, except that the parameter names use the Authorize.net naming conventions. The only real change is the names of the parameters, as the behavior of the purchase routine remains the same as if you were using the 3rd-Party Cart parameters. This set simply makes it easier for developers and shopping carts that already know/use the Authorize.net parameter names.

The three required Authorize.net parameters are:

x_login — same as ’sid’
x_amount — same as ‘total’
x_invoice_num — same as ‘cart_order_id’

Basic Payment Link

Taking from the example purchase link above for the single-product purchase using the 3rd-Party Cart set in combination with the New Product Creation set, a direct purchase link would look like this:

https://www.2checkout.com/checkout/purchase?x_login=123456&x_amount=2.00&
amp;x_invoice_num=CART-001&id_type=1&sh_cost=1.00&c_prod=PRODUCT-10&
c_name=Product 10&c_description=This is my 10th product&c_price=1.00

Notice that all other parameters stay the same except for the three required parameters. This also means that the set up of the HTML submission form, as well as setting up for multiple products, remains the same regardless of whether you use the 3rd Part Cart parameters or the Authorize.net parameters.

Additional Parameters

In addition, you also have the ‘x_receipt_link_url’ parameter available as part of this set. However, this parameter is given a special exception, as it can be used in *all* parameter sets. This parameter allows you to specify the Approved URL (the URL that your customers will return to once the sale has completed successfully) on-the-fly by passing it into the purchase routine.

This parameter has a few very specific behaviors that should be paid attention so that it can be used effectively:

This parameter will over-ride any Approved URL set within your account.
Direct Return DISABLED — This parameter will control where the ‘Click Here to Finalize your Order’ button takes the customer after the successful sale. If there are product-specific Approved URLs and only one product is ordered, it will over-ride the individual product’s return URLs. If there are product-specific Approved URLs and more than one product is ordered, then this parameter will control where the ‘Click Here to Finalize Your Order’ button on the Order Complete page as normal, but any product-specific return URLs will be listed as links on the Order Complete page next to each line item listed out.
Direct Return ENABLED — This parameter will control where the customer gets directed to automatically after the successful sale. If there are product-specific Approved URLs and only one product is ordered, this parameter will *not* over-ride the return URLs on the individual product. If there are product-specific Approved URLs and more than one product is ordered, then this parameter will over-ride all the product return URLs.

More Information

For information on the 3rd-Party Cart parameter set, please refer to the article that details this parameter set here.

If you need more information regarding the Authorize.net parameters, please refer to the article that details this parameter set here.

BILLING & SHIPPING INFORMATION

Lastly, the parameter sets offer the ability to take in billing and shipping information. This allows you to create your own interface on your website for requesting customer information, and then passing the customer’s information to the 2Checkout purchase routine to populate the Billing Information and Shipping Information forms. This way, you can record information on your customer before they reach 2Checkout, and customers will not have to enter their information twice.

There are two naming conventions for billing and shipping parameters. The standard naming convention can be used with the Plug-n-Play and 3rd-Party Cart parameters. The second naming convention variation is to be used with the Authorize.net set only.

Standard Naming Convention

To populate the Billing Information page, the following parameters can be used:

card_holder_name – Card holder’s name. This can also be populated using the ‘first_name’, ‘middle_initial’, and ‘last_name’ parameters. However, if you use these three parameters, the data will be combined into and returned as ‘card_holder_name’ in the parameters passed back to an Approved URL script.
street_address
street_address2
city
state
zip
country
email
phone
phone_extension

To populate the Shipping Information page, the following parameters can be used:

ship_name
ship_street_address
ship_street_address2
ship_city
ship_state
ship_zip
ship_country

Authorize.net Naming Convention

To populate the Billing Information page, the following parameters can be used:

x_First_Name
x_Last_Name
x_Phone
x_Email
x_Address
x_City
x_State
x_Zip
x_Country

To populate the Shipping Information page, the following parameters can be used:

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

EXTENDED EXAMPLES

Below are three examples of the parameter sets, which include many of the other available parameters in addition to the ones required for each set.

Plug-n-Play Example

This is a sale for two products, the quantity of which can not be changed due to enabling the ‘fixed’ parameter, and establishing all the billing and shipping information.

3rd-Party Cart Example

This is a cart sale establishing two new products, using vendor-specified product IDs, specifying the Approved URL that the customer will be taken at the end of the sale, and only populating the billing information.

Authorize.net Example

This is also a cart sale, only it uses the Authorize.net naming convention. It establishes one new product, using a system-assigned product ID, and only populating the shipping information.

Displaying Product Information

joel — Mon, 11 Jun 2007 16:42:25 +0000

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.

Let’s say that you are using the following link to sell your products or services to your customers:

https://www.2checkout.com/checkout/purchase?sid=XXXXXXX&total=20.00&cart_order_id=1234ABCD

When this link is processed, the value 1234ABCD is listed as the “Purchase Item” on our Order Details page. For our example, we are a vendor selling widgets at variable prices. Because of the variable price, you are not able to use our plug and play parameters, which require a set price for a product. If we want the customer to be able to see which widget they are purchasing but still offer the variable price we can do this. First, we need to create the widgets in our vendor account products area. To do this log into your account and click on link #4, “Set Up Products”. Next click on “New Product” link located on the right hand side of the screen. We will now enter all the required fields to describe our widget. The first required field is “Your Product ID”. You will have the ability to reference this product using this value. For this example, let’s enter the value “W1?. The Name field will be displayed on the Order Details page so for this example let’s enter the value “Widget Block” in this field. When you get to the “Price” field don’t panic because it is required, the system will not read this value when placing a sale and this is not what the customer will be charged. What I recommend, to prevent customers from attempting to purchase from the built in 2Checkout Order Page is to set this value to a high value as opposed to a low value such as 1.00. Let’s enter 1000.00 in this field for our example. The next required field is “Tangible”. If your product can be shipped then you will select YES and if your product is not something that is shipped you will select NO. Choosing either one will not affect the sales process at all in this example. Because our widgets will be shipped let’s choose YES. Now click the “Create Product” button to complete our widget.

Now that we have our product created, we can edit our purchase link to reference the product. This is done by using the parameters, id_type and c_prod, which are part of our New Cart Purchase Parameters. Id_type can hold a value of 1 if you wish to reference your product from the “Your Vendor ID” value which you entered when you created your product or a value of 2 if you wish to reference the product based on the “Product ID” which is assigned to your product by the 2Checkout system. Because the assigned product ID could be any number depending on your specific account, we will set the id_type parameter to the value of 1. Now that we have decided to use the “Your Product ID” value, we need to reference the product in our link using the c_prod parameter with the “Your Product ID” value, W1, as the value of the parameter. Adding these 2 parameters will cause our link to look like the following:

https://www.2checkout.com/checkout/purchase?sid=XXXXXXX&total=20.00&cart_order_id=1234ABCD&id_type=1&c_prod=W1

When you process this link in your web browser you will see the “Purchase Item” of “1234ABCD” and Total of 20.00 just as we saw before. Below this information, we now see a section showing our Widget’s Product Name and a quantity, which defaults to 1. We have successfully displayed what product our customer purchased without actually using the product and price that was set in the 2Checkout account.

It is also very easy to add the quantity of the product purchased so the customer can see this as well. All you need to do is place a comma after your c_prod value and list the quantity value. For example if we sold 3 Widget Blocks to our customer, our link would look like the following:

https://www.2checkout.com/checkout/purchase?sid=XXXXXXX&total=20.00&cart_order_id=1234ABCD&id_type=1&c_prod=W1,3

You can also use this method to list more then one product on the Order Details page. Let’s say we had created a Widget Cube in our account that we gave a ID of W2. The customer then purchases 2 of these widgets in addition to 3 Widget Blocks. Our link would now look like this:

https://www.2checkout.com/checkout/purchase?sid=XXXXXXX&total=20.00&cart_order_id=1234ABCD&id_type=1&c_prod_1=W1,3&c_prod_2=W2,2

With closer inspection, you will see some changes in the parameters that we passed. If you pass in more then one c_prod parameter, you must place a underscore and then a digit after c_prod so our parameters are now c_prod_1 and c_prod_2. It is also important to point out that while we have 2 c_prod parameters we still are only required to pass in 1 id_type parameter. This parameter is applied to each c_prod value passed into the system.

After reading this article, you should be able to display product information to your customers on the 2Checkout Order Details page even if you are not using our Plug and Play Cart parameters.

Using Checkboxes With The Plug and Play Purchase Parameters

joel — Mon, 21 May 2007 20:11:51 +0000

While the Plug and Play parameter set is typically implemented based on the provided HTML code, it can be extended and used in other forms. In this article we will explain how you can use the plug and play parameters with checkboxes. This will allow you to build an order form on your site where your customers can check the products or services they wish to buy all at once. We will also look at the use of checkboxes for product add-on and options.

Checkboxes are typically used when you want to allow a visitor of your site to select one or more options from a set of alternatives. In an HTML form the checkbox input type carries the following common attributes.

Name – This attribute carries the name of the parameter that will be submitted with the form if the check box is checked. In our case this will carry the product_id parameter name.

Value – This attribute holds the value of the name attribute and is the value of the parameter that is passed with the form when the checkbox is checked. In our case this will carry the assigned product ID of the product that is associated with the check box.

To define a checkbox in our form we will create the input type and add the 2 attributes. This would look like the following example:

When checked, this checkbox will pass the parameter named product_id with a value of 1 to the URL attached to the HTML form.

Now that we understand the basic attributes of the checkbox input type, and how to define one in our form, we will create a simple example. This example will allow the customer to purchase 1 of any product when they check the checkbox. Remember to subscript your product_id and quantity parameters with a corresponding digit. This will allow the customer to select multiple products at one time along with a quantity that corresponds to the product_id with the same subscript.



Product 1:




Product 2:




Product 3:

It is also very easy to add the ability for your customers to enter the quantity themselves as well. To do this we will replace this line:

with the following:

Checkboxes can also be used to allow your customers the ability to purchase an add-on or option for your product. In this example, we have a product that you can purchase with the option of being a gift. First we start with our basic HTML snippet that is provided by the 2Checkout system.




Quantity

To allow the customer to choose the gift option we need to first add the checkbox input that will be linked to the gift product. You will create this gift add-on in your account as another 2Checkout product. Let’s say this add-on option is given a product ID of 2. The following lines need to be added to the above form.

This is a gift:

After reading this article, you should be able to add the checkbox input to your purchase forms.

What are the New Cart Purchase Parameters?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

Announcement

The new cart purchase parameter descriptions have been integrated into the parameter set articles they are required for. Please review the “Product Identification parameters” section of the 3rd party cart parameter article or the Authorize.net parameter article to find information on these parameters. If you would like to test your integration of these parameters, try using our developers.2Checkout area. The information below is provided for historical reference only.

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:

All previous parameters remain supported and should continue to be passed in (2CO, Authorize.net),
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,
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:

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

What carts are 2CO compatible with?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

A third party shopping cart is not necessary in order to use our service. We provide you with the option of using our easy-to-use Plug-N-Play shopping cart. Our PNP shopping cart uses simple HTML links, so you do not need to install extra software.

However, if you wish to use a third party shopping cart with our service, you may do so. The 2Checkout service generally is compatible with the following third party shopping carts:

Any cart listed in our Recommended Cart section.
Any shopping cart compatible with the Authorize.net parameter set, provided that it allows you to change the gateway URL. Nearly all shopping carts today support the Authorize.net standard.
Any shopping cart that advertises 2Checkout support on their Web site should work with our service.
Miscellaneous shopping carts. If your shopping cart does not fit either of the above criteria, or if it is simply in question, there is a way to determine whether or not your cart supports our service. Simply check with the manufacturer of the shopping cart to confirm it’s compatibility. You can contact the maker personally, go to their Web site, or read any documentation that may have been provided with the cart, itself.

TECHNICAL SUPPORT

2Checkout cannot provide technical support for questions regarding third party shopping carts. Basically, we did not develop them, so, therefore, we do not have any working knowledge of their inner mechanisms. Questions about configuration and/or setup should be directed towards the maker of the cart. However, we can provide technical support for questions or information needed to set up the shopping cart to work with our service.

You may find additional help regarding third party shopping carts from other vendors of ours by going to our Community, located at: http://www.2checkout.com/community/public/

What are the parameters for 2CO’s Plug and Play cart?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

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. If you would like to test your integration of these parameters, try using our developers.2Checkout area.

Multi-page Payment Routine:
https://www.2checkout.com/checkout/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 your 2Checkout account.
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 – Chinese – zh, Danish – da, Dutch – nl, French – fr, German – gr, Greek – el, Italian – it, Japanese – jp, Norwegian – no, Portuguese – pt, Slovenian – sl, Spanish – es_ib, Spanish – es_la, Swedish – sv, 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, AL for Acculynk PIN-debit, PPI for PayPal, or PPL for PayPal Pay Later. 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 -Used to specify an approved URL on-the-fly, but is limited to the same domain that is used for your 2Checkout account, otherwise it will fail. (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:
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.

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:

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).
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.

Important Note: When you are testing parameters, please be certain to clear the cookies in your browser between tests to ensure the changes you have made are applied. For more information on clearing the cookies please click here.

Related Article: Country Codes

What are 2Checkout.com’s own parameters?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

2CO has our own proprietary set of parameters that you can use if your cart supports them. If you would like to test your integration of these parameters, try using our developers.2Checkout area.

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

Single Page Payment Routine:
https://www.2checkout.com/checkout/spurchase
Only supports credit card payments and intangible products/services.

Required Parameters:
sid – Your 2Checkout vendor account number.
total – The total amount to be billed, in decimal form, without a currency symbol. (8 characters, decimal, 2 characters: Example: 99999999.99)
cart_order_id – A unique order id from your program. (128 characters max)

Product Identification Parameters:
Suppliers using this parameter set must pass in parameters to identify what is being sold during the purchase. 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 suppliers 2Checkout.com sale detail page.

id_type – Due to changes in with the Product Identification parameters this parameter should be passed in once during the purchase and will need to have its value set to 1.
c_prod – The ID of the product that is being purchased. The quantity of product being purchased can passed with this parameter by placing a comma after the ID and then the quantity in numeric format.
c_name – The value of this parameter should contain the name of the product to be created. (128 characters max)
c_description – The value of this parameter should contain a short description of the product to be sold. (255 characters max)
c_price – The price of your product. Please note that in order to prevent a discrepancy between the total parameter and the sum of the product identification c_price parameters which may confuse the customer, the product price will not be displayed on the purchase page. (8 characters, decimal, 2 characters: Example: 99999999.99)

You can use these identification parameters to pass in multiple products as well. To do so you will need to append a digit to each parameter. For example, c_prod_1, c_name_1, c_description_1, c_price_1 will describe the first product, then to describe the second product you would use a 2 so the parameters will read c_prod_2, c_name_2 and so on.

Additional Parameters:
demo – Y to enable demo mode. Do not pass for live sales. Can also be controlled within the account.
lang – Chinese – zh, Danish – da, Dutch – nl, French – fr, German – gr, Greek – el, Italian – it, Japanese – jp, Norwegian – no, Portuguese – pt, Slovenian – sl, Spanish – es_ib, Spanish – es_la, Swedish – sv, 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, AL for Acculynk PIN-debit, PPI for PayPal, or PPL for PayPal Pay Later. 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.
x_Receipt_Link_URL – Used to specify an approved URL on-the-fly, but is limited to the same domain that is used for your 2Checkout account, otherwise it will fail. This parameter will over-ride any URL set on the Look and Feel page. (no limit)

To pre 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 (64 characters max)
phone – Card holder’s phone (16 characters max)
phone_extension – Card holder’s phone extension (9 characters max)

To pre 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.

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.

You can receive back all of the parameters that were passed in as well as the following parameters:
order_number – 2Checkout.com order number
cart_order_id – Your cart ID number passed in.
credit_card_processed – Y if successful (Approved).
key – the MD5 hash used to verify that the sale came from one of our servers

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.

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

What Authorize.net parameters does 2CO support?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

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. If you would like to test your integration of these parameters, try using our developers.2Checkout area.

Multi-page Payment Routine:
https://www.2checkout.com/checkout/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. Can also be controlled within the account.
lang – Chinese – zh, Danish – da, Dutch – nl, French – fr, German – gr, Greek – el, Italian – it, Japanese – jp, Norwegian – no, Portuguese – pt, Slovenian – sl, Spanish – es_ib, Spanish – es_la, Swedish – sv, 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, AL for Acculynk PIN-debit, PPI for PayPal, or PPL for PayPal Pay Later. 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.
x_Receipt_Link_URL – Used to specify an approved URL on-the-fly, but is limited to the same domain that is used for your 2Checkout account, otherwise it will fail. This parameter will over-ride any URL set on the Look and Feel page. (no limit)

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.

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 card_holder_name for this. card_holder_name will then be returned unless x_First_Name and x_Last_Name are passed into 2Checkout.

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.
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.

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.

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

Can I specify the return URL ‘on the fly’?

knowledgebase — Sat, 30 Dec 2006 07:00:00 +0000

Yes, this is possible. You may pass in a parameter called x_receipt_link_url to control where the customer is returned to on a per-sale basis. Keep in mind that this parameter will over-ride any return URL set on the Look and Feel page of your account, but it will not over-ride any return URLs that are set up on the product itself if there are any. Using this method, you could create a special button or link that would return the customer to a different page on your site than is set up on the Look and Feel page. This is useful for ‘promotional’ type sites as you can avoid having to make any configuration changes to your actual account.

If you are using buttons on your site to sell your goods through 2Checkout, you would add a single line to the button such as this:

This must go between the opening and closing FORM tag that you see when you view your existing code.

If you are using links to sell your goods through 2Checkout, then you would add this parameter to your links to specify the return url, such as this:

&x_receipt_link_url=http://www.your-site.com/return.php

Notice that in both of the above examples, the FULL path is used for the value of this.

Important Note: For security reasons, the domain on your account and the domain that hosts the pass back page must match exactly for this to work correctly. For example, if you have http://www.your-site.com specified on your account, you could pass back to http://www.your-site.com/pages/pass.php but not to http://www.your-other-site.com/pages/pass.php.