Buy-link parameters
Overview
To start selling with 2Checkout, you need to redirect shoppers to 2Checkout's hosted secure checkout (ordering interface). Depending on your desired workflow, you can either generate buy-links using our dedicated interface (Generate Buy Links) or generate the parameters dynamically, in your own system.
Availability
All 2Checkout accounts.
Requirements
Configure at least one product to generate a buy-link.
Query parameters
When you generate a checkout link, 2Checkout automatically includes some of the parameters in the list below in the URL, depending on a number of variables, such as the purchase flow you choose, the products, discounts, currencies, cart languages, preselected payment methods and more. You can use these query parameters to generate checkout links in your own system, without having to rely on the functionality in you account.
| PARAMETER | Required/Optional | DESCRIPTION |
|---|---|---|
| PRODS | Required |
IDs for the products added to checkout, separated by a comma. Do not insert spaces or blanks between values. PRODS=1234567,1234568. 2Checkout automatically assigns each product added/imported into the platform a system-generated unique numeric (int) identifier. Example: Product ID = 1234567. In the Control Panel, click to edit a product, and select the Information tab. The Product ID of the item you're editing is available at the top of the General area under Information. Product IDs are different than Product Codes, also available in this area, but which you control. |
| QTY | Required | The number of units (quantity) for each product in checkout, separated by a comma. Do not insert spaces or blanks between values. QTY=2,1 |
| INFO1234567 | Optional |
Maximum length: 100 chars. Extra information that you can associate with the items in an order. In the examples above, 1234567 is the unique product identifier (Product ID) from the 2Checkout platform. |
| OPTIONS123456 | Optional |
Preselected pricing options for the corresponding product. The values used are the pricing options codes (the codes are set for each option individually). For example: OPTIONS5211=5usr,2year. Pricing options codes are case sensitive. For scale pricing options group, you also need to send a specific value within the intervals defined. Let's assume that you created a Users scale pricing options group with the unique code: users, and two options: 1 to 10 ($99 per user) and 11 to 50 ($88 per user). If you want to build the buy-link for a product using the Users scale pricing options group and charge customers for 35 users, the parameter should be formatted as such:OPTIONS=users=35, including both the unique code of the pricing options group and the specific value of the scale pricing interval. |
| COUPON | Optional | Promotion coupon code discounting the order. To send multiple values separate them by commas, in scenarios in which different coupons discount specific products added to cart. For example: [...]&COUPON=voucher1,voucher2[...]. The order of the values you send for the COUPON parameter does not need to match the order of products identifiers sent using PRODS. |
| REF | Optional | External order reference. Add a string identifier to buy-links (max 100 char), to save extra info with the order, in addition to the system generated 2Checkout order reference. Consider using a HASH for increased security. You can validate the hash after you receive the order notification from 2Checkout. External references are visible when accessing the order details page for your orders. |
| CARD | Optional |
Possible values:
|
| CART | Optional |
Possible values:
|
| PAY_TYPE | Optional |
Preselected payment method for the order. The parameter can be used in both modules, "Shopping Cart" or "Checkout". By default, if the parameter is missing, the default payment method for the order is assumed to be Credit/debit card (Visa/MasterCard).
|
| LANG | Optional | Selected language for order processing interface and emails. The parameter can be used in both modules, "Shopping Cart" or "Checkout". By default, if the parameter is missing, the used language is assumed to be English. All possible values for this moment are listed in the table below. |
| LANGUAGES | Optional |
This parameter sets the order interface language.
|
| SRC | Optional | To identify the source of your sales (which links are performing better), a separate link identifier can be assigned to each link. For instance, if there are two buy-links on your website, one in the product page and another one in the download page, you can track the source page by entering the following parameters: SRC=prodpage for the product page or SRC=dldpage for the link on the download page (dldpage and prodpage are example strings only, you can use any combination). Note: SRC cannot have the value "0". |
| CHK_CROSS | Optional | If cross selling products are available in the shopping cart, sending this parameter will check all products in cross-selling. This is only available for shopping cart landing pages |
| CROSS_SELL | Optional |
CROSS_SELL[cross_sell_product_ID]=main_product_ID CROSS_SELL must be used in conjunction with CART=1 in the same buy-link. The presence of the CART=1 parameter in the buy-link is mandatory, otherwise the cross-selling campaign will not be triggered. Let's assume there's a cross-selling campaign configured between Product A with the following Product ID=1234567, which is the main product, and Product B, the recommended product with Product ID=5566778. 1. Add the main product to cart using its buy-link: Add the recommended (cross-sell) product to cart using its link, to which the &CROSS_SELL parameter is added: Result: both the main product and the cross-sell product are added to cart one after the other; any discounts impacting the recommended offering are set accordingly. 2. Build a mixt buy-link with the main and cross-sell product: Result: both the main product and the cross-sell product are added to cart simultaneously; any discounts impacting the recommended offering are set accordingly. |
| CHK_BCKUP | Optional | If you have the Backup CD option enabled for your account, sending this parameter will check the Backup CD option available in shopping cart. This is only available for shopping cart landing pages |
| CHK_DIS | Optional | If you have the Download Insurance option enabled for your account, sending this parameter will check the Download Insurance option available in shopping cart. This is only available for shopping cart landing pages |
| CHK_GIFT | Optional | If you have enabled gift feature for the products available in the shopping cart, sending this parameter will check the option to buy the products as a gift for someone else. This is only available for shopping cart landing pages |
| SHOPURL | Optional | Custom URL used for "Back to shopping" link |
| CURRENCY | Optional | Preselected billing currency to be used in the transaction. This is the currency used to charge your customers. |
| DCURRENCY | Optional | Preselected display currency to be used in the order in order to give an estimate of the cost in the local currency detected by geolocation. See the "Tips & tricks" section below in order to learn about exchange rates used. Display currency can differ than billing currency, and in the shopping cart it's presented to customers in a more prominent position. |
| DOTEST | Optional | Set this parameter to 1 to place orders in a test environment. Dummy credit card details are provided so you can test the entire order placing process. |
| CLEAN_CART | Optional | Set this parameter to 1 to reset the cart contents or to ALL to reset the cart session. Use this parameter to remove products from the current cart session. Note: CLEAN_CART does remove production options or custom prices from the current cart session. However, it does not delete cookies and cache. |
| ORDERSTYLE | Optional | Allows you to set the corresponding template, overriding the default template assigned to the product group. Each template defined in the Interface Templates area of the Control Panel has a unique identifier associated which is visible in the browser address bar when previewing the shopping cart. |
| AFFILIATE | Optional |
A valid 2Checkout Affiliate ID that you want to credit the sale to. Affiliate identifiers can be extracted from the Active Relationships area of the Affiliate network, by clicking on names of your affiliates to access their details.
In case the value of the parameter is set to 0, ‘AFFILIATE=0’, and the “Disable Affiliate Parameter” option is disabled in GAP for the vendor account, the platform will not attribute the order to any affiliate, regardless if the affiliate cookie is set. |
| LICENSE | Optional for upgrade links |
Is used with upgrade links to trigger the upgrade of a specific subscription, such as in the following example. |
| CUSTOMERID | Optional | The external customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by taking advantage of the CUSTOMERID (case sensitive) parameter added to buy-links. |
| AV_CUSTOMERID | Optional | The 2Checkout customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by taking advantage of the AV_CUSTOMERID (case sensitive) parameter added to buy-links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions. |
| PLNKEXP | Optional | UTC timestamp for link expiration |
| PLNKID | Optional | Unique link identifier used to restrict access to the link only to the IP address of the first user that clicks it. 250 chars. |
| PHASH | Required | Required HMAC_SHA signature in order to prevent the request from being exploited. |
| TPERIOD | Required (only for trials) | Trial period must be at least 7 days. For example enter TPERIOD=7 for a 7-day trial, or TPERIOD=30 for a 30-day evaluation period. Can also be used as TPERIOD1234567=7, with 1234567 representing the product ID. |
| WS_ORDER | Optional | (optional) - Use the WS_ORDER parameter to control what website URL is displayed in the email messages customers receive from 2Checkout. |
| BACK_REF | Optional |
Redirect URL. Shopper redirect will only happen after the order is placed successfully (the Thank you page is bypassed completely). To use the new URLs their domain needs to be whitelisted in Control Panel. For more information see the Set a redirect URL for default checkout flows documentation. |
| LAYOUT_TYPE | Optional |
LAYOUT_TYPE enables you to control which version of the shopping cart is served to shoppers. Possible values: CLASSIC - the desktop variant of the shopping cart (using LAYOUT_TYPE=CLASSIC will always display the desktop version of the cart even to mobile device users); MOBILE - 2Checkout mobile cart (using LAYOUT_TYPE=MOBILE will always display the mobile version of the shopping cart, even to users of desktop browsers). |
| AVGAFFILIATE | Optional | AVGAFFILIATE=12345 (for an affiliate with the 12345 affiliate ID). By including affiliate ID parameters in redirects to your website, 2Checkout enables you to better monitor the traffic generated by your affiliates. |
| UPGRADEPROD | Required (only for upgrades) | Product to be upgraded to, the form of the product ID |
| UPGRADEOPT | Required (only for upgrades) | Options of the product to be upgraded to, in the form of the option code |
| RENEWAL_SRC | Not required (only for subscription renewals) |
RENEWAL_SRC is added automatically ONLY to the system-generated manual renewal links sent by 2Checkout to customers via manual renewal notifications (emails). Manual renewal links available in subscription details pages do not include this parameter. RENEWAL_SRC can be used in conjunction with analytics systems to identify the notification email that acted as the source for customers to manually renew their subscription. Possible values correspond to the Notification time settings for manual billing emails
|
| NODATA | Optional | Value=1. Use in conjunction with PAY_TYPE=PAYPAL to trigger the Express payments checkout flow with PayPal which will circumvent 2Checkout checkout and redirect customers directly to PayPal. Expected behavior: Shoppers click on a buy-link using the NODATA=1 and PAY_TYPE=PAYPAL parameters, and are redirected to PayPal, rather than be taken to the 2Checkout shopping cart (checkout.php). |
| DESIGN_TYPE | Optional |
Value = 1. When DESIGN_TYPE=1 is used in buy-links the parameter changes the layout of the shopping cart template interface, positioning the payment methods selector in a more prominent position, above the billing details area. Value = 2. When DESIGN_TYPE=2 is used in buy-links customers are redirected to their PayPal account, where they log in and confirm the payment. After payment confirmation, they are redirected to the shopping cart to confirm the billing and delivery data and enter their VAT ID. We recommend using the DESIGN_TYPE parameter with value 2, as it embeds latest practices for a swift checkout experience. |
| AUTO_PREFILL | Optional |
Include AUTO_PREFILL=1 in buy-links for shopping carts.
When the AUTO PREFILL feature is active and AUTO_PREFILL=1 used in buy-links, the ZIP code and country pair become the only required aspects of the billing address.
Address, City and State details are calculated automatically by the 2Checkout system. The address can miss altogether.
Note: Using the AUTO_PREFILL=1 parameter without the feature being enabled for your account will result in shoppers following the classic purchase flow, where all billing address data is mandatory. |
| SHORT_FORM | Optional | Case sensitive. Include SHORT_FORM=1 in buy-links for shopping carts. Use it to streamline the shopping cart by minimizing data entry and providing an optimized ordering experience for customers. Guidance is available here. |
| UPSELL_DISPLAY_TYPE | Optional |
Optional parameter used to define the type of up-selling page to include in the buy-links. The parameter is not required for the PHASH calculation. Available values:
|
| FRAUD_REVIEW | Optional |
Use this parameter to receive the order's fraud evaluation in the Thank You page. Possible values:
When fraud status tracking is enabled, check the values returned in the FraudStatus variable from omnitureVars. Possible values:
|
Secure 'buy-links'
Use a HMAC_SHA signature to prevent links from being exploited. To calculate the HMAC_SHA signature, you need to build a string from the query parameters of the buy-link prefixed by the length of the sequence of parameters in tandem with the 2Checkout-generated SECRET KEY for your account (view secret key).
If you're using SHA2, the parameter syntax is PHASH=sha256.[hash_value]. For SHA3, the syntax is PHASH=sha3-265.[hash_value].
| PARAMETER | DESCRIPTION |
|---|---|
| PRODS | Required. Product IDs for which the order will be processed, separated by comma (,), with no blanks. Example: PRODS=1234567, 1234568. |
| QTY | Required. The number or quantity for each corresponding for corresponding above object, separated by comma (,), with no blanks: Example: QTY=2,1 |
| OPTIONS123456 | Optional. List of pricing options codes separated by comma |
| PRICES[Product ID][Currency] | Required parameter to set the price for product default currency. For example, for a product with the 2Checkout product ID: 123456, the currency EUR, and the price 99.99, this parameter would look like: PRICES123456[EUR]=99.99. If not sent for other billing currencies, 2Checkout will convert based on the submitted default price. |
| PLNKEXP | Optional. UTC timestamp for link expiration. |
| PLNKID | Optional. Unique link identifier used to restrict access to the link only to the IP address of the first user that clicks it. 250 chars. |
| PHASH | Required HMAC_SHA signature in order to prevent the request from being exploited. Used when the price of products is specified statically using 'on the fly pricing' and for trials - buy-links will contain the PRICES URL parameter. If the PHASH parameter value is removed or tampered with, the system will return an "Invalid signature or link expired!" error message as long as the PRICES parameter is also used in the link. An "Invalid signature" error is always returned in scenarios in which PHASH is removed from trial links. |
| BACK_REF |
To use the new URLs and replace the Thank you page, their domain needs to be whitelisted in Control Panel. For more information see the Set a redirect URL for default checkout flows documentation.
Optional. Used only if SECURE_CART parameter is set to value ‘1’ and represents the URL value in clear/raw/not encoded that is to be hashed.
Notes:
|
Example
| HTTPS GET request |
|---|
| https://secure.2checkout.com/order/checkout.php?CART=1&PRODS=123456&QTY… |
| STRING for HMAC_SHA calculation |
|
129PRODS=123456&QTY=1&OPTIONS123456=option1,option2&PRICES123456[EUR]=10&PRICES123456[USD]=11.5&PLNKEXP=1286532283&PLNKID=4A4681F0E5 129 represents the length of the sequence of parameters. |
| Secret key for this example |
| _SECRET_KEY_ |
| Resulting HMAC_SHA2 signature* |
| bfd1096dd441a7907e45671a2bd9c4347700581198c2a61c09543bf97673d78d |
| Resulting HMAC_SHA3 signature* |
| ce0bb4dac94589a5f8ba778cd2ec0b3bcfaff7ff68935ddc9204ff152f3c140c |
