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.

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, ‘PPL’ for PayPal Pay Later, or ‘FXS’ for FXSource.
• 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/2co/buyer/purchase?sid=123456&product_id=101&quantity=1

To put this in explainable terms, our purchase routine (https://www.2checkout.com/2co/buyer/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:

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='product_id' value='101' >
<input type='hidden' name='quantity' value='1' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>

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/2co/buyer/purchase?sid=123456&product_id1=101&quantity1=1&product_id2=202&quantity2=1

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

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='product_id1' value='101' >
<input type='hidden' name='quantity1' value='1' >
<input type='hidden' name='product_id2' value='202' >
<input type='hidden' name='quantity2' value='1' >
<input name='submit' type='submit' value='Buy from 2CO' >
</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/2co/buyer/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/2co/buyer/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:

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='total' value='2.00' >
<input type='hidden' name='cart_order_id' value='CART-001' >
<input type='hidden' name='id_type' value='1' >
<input type='hidden' name='sh_cost' value='1.00' >
<input type='hidden' name='c_prod' value='PRODUCT-10' >
<input type='hidden' name='c_name' value='Product 10' >
<input type='hidden' name='c_description' value='This is my 10th product' >
<input type='hidden' name='c_price' value='1.00' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>

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/2co/buyer/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&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:

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='total' value='4.00' >
<input type='hidden' name='cart_order_id' value='CART-001' >
<input type='hidden' name='id_type' value='1' >
<input type='hidden' name='sh_cost' value='1.00' >
<input type='hidden' name='c_prod_1' value='PRODUCT-10' >
<input type='hidden' name='c_name_1' value='Product 10' >
<input type='hidden' name='c_description_1' value='This is my 10th product' >
<input type='hidden' name='c_price_1' value='1.00' >
<input type='hidden' name='c_prod_2' value='PRODUCT-20' >
<input type='hidden' name='c_name_2' value='Product 20' >
<input type='hidden' name='c_description_2' value='This is my 20th product' >
<input type='hidden' name='c_price_2' value='2.00' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>

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/2co/buyer/purchase?x_login=123456&x_amount=2.00&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 or Pending 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/Pending URLs and only one product is ordered, it will over-ride the individual product’s return URLs. If there are product-specific Approved/Pending 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/Pending 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/Pending 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.

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='product_id1' value='101' >
<input type='hidden' name='quantity1' value='1' >
<input type='hidden' name='product_id2' value='202' >
<input type='hidden' name='quantity2' value='1' >
<input type='hidden' name='fixed' value='Y' >
<input type='hidden' name='card_holder_name' value='Checkout Shopper' >
<input type='hidden' name='street_address' value='1785 OBrien Road' >
<input type='hidden' name='street_address2' value='Suite 200' >
<input type='hidden' name='city' value='Columbus' >
<input type='hidden' name='state' value='OH' >
<input type='hidden' name='zip' value='43228' >
<input type='hidden' name='country' value='USA' >
<input type='hidden' name='email' value='example@2co.com' >
<input type='hidden' name='phone' value='614-921-2450' >
<input type='hidden' name='phone_extension' value='197' >
<input type='hidden' name='ship_name' value='Gift Receiver' >
<input type='hidden' name='ship_street_address' value='1234 Address Road' >
<input type='hidden' name='ship_street_address2' value='Apartment 123' >
<input type='hidden' name='ship_city' value='Columbus' >
<input type='hidden' name='ship_state' value='OH' >
<input type='hidden' name='ship_zip' value='43235' >
<input type='hidden' name='ship_country' value='USA' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>

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.

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='sid' value='123456' >
<input type='hidden' name='total' value='4.00' >
<input type='hidden' name='cart_order_id' value='CART-001' >
<input type='hidden' name='id_type' value='1' >
<input type='hidden' name='sh_cost' value='1.00' >
<input type='hidden' name='c_prod_1' value='PRODUCT-10' >
<input type='hidden' name='c_name_1' value='Product 10' >
<input type='hidden' name='c_description_1' value='This is my 10th product' >
<input type='hidden' name='c_price_1' value='1.00' >
<input type='hidden' name='c_prod_2' value='PRODUCT-20' >
<input type='hidden' name='c_name_2' value='Product 20' >
<input type='hidden' name='c_description_2' value='This is my 20th product' >
<input type='hidden' name='c_price_2' value='2.00' >
<input type='hidden' name='card_holder_name' value='Checkout Shopper' >
<input type='hidden' name='street_address' value='1785 OBrien Road' >
<input type='hidden' name='street_address2' value='Suite 200' >
<input type='hidden' name='city' value='Columbus' >
<input type='hidden' name='state' value='OH' >
<input type='hidden' name='zip' value='43228' >
<input type='hidden' name='country' value='USA' >
<input type='hidden' name='email' value='example@2co.com' >
<input type='hidden' name='phone' value='614-921-2450' >
<input type='hidden' name='phone_extension' value='197' >
<input type='hidden' name='x_receipt_link_url' value='http://www.yourdomain.com/returnscript.php' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>

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.

<form action='https://www.2checkout.com/2co/buyer/purchase' method='post'>
<input type='hidden' name='x_login' value='123456' >
<input type='hidden' name='x_amount' value='2.00' >
<input type='hidden' name='x_invoice_num' value='CART-001' >
<input type='hidden' name='id_type' value='2' >
<input type='hidden' name='sh_cost' value='1.00' >
<input type='hidden' name='c_prod' value='5' >
<input type='hidden' name='c_name' value='Product 5' >
<input type='hidden' name='c_description' value='This is my 5th product' >
<input type='hidden' name='c_price' value='1.00' >
<input type='hidden' name='x_ship_to_first_name' value='Gift' >
<input type='hidden' name='x_ship_to_last_name' value='Receiver' >
<input type='hidden' name='x_ship_to_address' value='1234 Address Road' >
<input type='hidden' name='x_ship_to_city' value='Columbus' >
<input type='hidden' name='x_ship_to_state' value='OH' >
<input type='hidden' name='x_ship_to_zip' value='43235' >
<input type='hidden' name='x_ship_to_country' value='USA' >
<input name='submit' type='submit' value='Buy from 2CO' >
</form>