Hosted checkout parameters
Overview
These parameters can be used to dynamically pass in tangible/intangible and recurring/non-recurring products, product options, shipping, taxes, and coupons as items without having to create the products in the admin area.
Checkout URL
https://www.2checkout.com/checkout/purchaseRequired Parameters
| Parameter | Description |
|---|---|
| sid | Your 2Checkout account number. |
| mode | Defines the parameter set. Should always be passed as ‘2CO’. |
| li_#_type | The type of line item that is being passed in. (Always Lower Case, ‘product’, ‘shipping’, ‘tax’ or ‘coupon’, defaults to ‘product’) |
| li_#_name | Name of the item passed in with the corresponding li_#_type. (128 characters max, cannot use ‘<' or '>’, defaults to capitalized version of ‘type’.) |
| li_#_quantity | Quantity of the item passed in with the corresponding li_#_type. (0-999, defaults to 1 if not passed in.) |
| li_#_price | Price of the line item. Format: 0.00-99999999.99, defaults to 0 if a value isn’t passed in, no negatives (use positive values for coupons), leading 0 & decimal are optional. Important note: If the li_#_price parameter isn’t used to pass in line item pricing, the pricing for the corresponding item will default to 0.00. |
| li_#_tangible | Specifies if the corresponding li_#_type is a tangible or intangible. ( Must be Upper Case, ‘Y’ or ‘N’, if li_#_type is ‘shipping’ forced to ‘Y’.) |
You can use these parameters to pass in multiple products as well. To do so you will need to append a digit to each parameter. For example, li_0_type, li_0_quantity, li_0_name, li_0_price, li_0_product_id, li_0_description, li_0_tangible will describe the first product, then to describe the second product you would increment so the parameters will read li_1_type, li_1_quantity, and so on. Please Note: With this parameter set # may be represented by 0-999 and aren’t required to be consecutive.
Additional Parameters
| Parameter | Description |
|---|---|
| li_#_product_id | Id that you use to identify the product. 64 characters max, cannot use ‘<' or '>’. |
| li_#_description | Description you use for the product. 255 characters max, cannot use ‘<' or '>’. |
| li_#_recurrence | Sets billing frequency. Ex. ‘1 Week’ to bill order once a week. (Can use # Week, # Month, or # Year) |
| li_#_duration | Sets how long to continue billing. Ex. ‘1 Year’, to continue billing based on li_#_recurrence for 1 year. (Forever or # Week, # Month, # Year) |
| li_#_startup_fee | Any start up fees for the product or service. Can be negative to provide discounted first installment pricing, but cannot equal or surpass the product price. |
| li_#_option_#_name | Name of product option. Ex. Size (64 characters max – cannot include ‘<' or '>’) |
| li_#_option_#_value | Option selected. Ex. Small (64 characters max, cannot include ‘<' or '>’) |
| li_#_option_#_surcharge | Option price in seller currency. (0.00 for no cost options) |
| demo | Y to enable demo mode. Do not pass for live sales. Can also be controlled within the account. |
| currency_code | AFN, ALL, DZD, ARS, AUD, AZN, BSD, BDT, BBD, BZD, BMD, BOB, BWP, BRL, GBP, BND, BGN, CAD, CNY, COP, CRC, CZK, DKK, DOP, XCD, EGP, EUR, FJD, GTQ, HKD, HNL, HUF, INR, IDR, ILS, JMD, JPY, KZT, KES, LAK, MMK, LBP, LRD, MOP, MYR, MVR, MRO, MUR, MXN, MAD, NPR, TWD, NZD, NIO, NOK, PKR, PGK, PEN, PHP, PLN, QAR, RON, RUB, WST, SAR, SCR, SGD, SBD, ZAR, KRW, LKR, SEK, CHF, SYP, THB, TOP, TTD, TRY, UAH, AED, USD, VUV, VND, XOF, YER. Use to specify the currency for the sale. |
| lang | Chinese – zh, Danish – da, Dutch – nl, French – fr, German – gr, Greek – el, Italian – it, Japanese – jp, Norwegian – no, Portuguese – pt, Slovenian – sl, Spanish |
| 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) |
| purchase_step | Sets the purchase step that the buyer will land on when being directed to the checkout page. Possible values are ‘review-cart’, ‘shipping-information’, ‘shipping-method’, ‘billing-information’ and ‘payment-method’. Please Note: To skip a purchase step, all required fields must be pre-populated with the parameters that are passed in with the sale. If a required field is not pre-populated, the buyer will revert back to the step that needs to be completed. |
| 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 Site Management page. (no limit) |
| coupon | Specify a 2Checkout created coupon code. If applicable, the coupon will be automatically applied to the sale. |
To pre-populate the billing information page you may pass in:
| Parameter | Description |
|---|---|
| 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). Required if “country” value is: CHN, JPN, RUS - Optional for all other “country” values. |
| city | Card holder’s city (64 characters max) |
| state | Card holder’s state (64 characters max). Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values. |
| zip | Card holder’s zip code/post code. Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values. (16 characters max) |
| country | Card holder’s country (64 characters max) |
| 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:
| Parameter | Description |
|---|---|
| ship_name | Recipient Name |
| ship_street_address | Recipient Address 1 |
| ship_street_address2 | Recipient Address 2. Required if “ship_country” value is: CHN, JPN, RUS - Optional for all other “ship_country” values. |
| ship_city | Recipient City |
| ship_state | Recipient State. Required if “ship_country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “ship_country” values. |
| ship_zip | Recipient Zip Code/Post Code. Required if “ship_country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “ship_country” values. |
| ship_country | Recipient Country |
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 Site Management page to receive any of these parameters back as they are not included in the confirmation emails.
Parameters Returned
You will receive back all of the parameters that were passed in as well as the following parameters:
| Parameter | Description |
|---|---|
| order_number | 2Checkout order number |
| invoice_id | 2Checkout invoice id |
| credit_card_processed | Y if successful (Approved). |
| total | the total amount of the purchase |
| key | the MD5 hash used to verify that the sale came from one of our servers |
Important: You can not mix parameter sets. This will cause problems during payment or may prevent the payment pages from working at all.
