Skip to main content

Buy-link parameters

Last updated: 29-Feb-2024
Rate this article:

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 Sales 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 commaDo 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. 
For example: INFO1234567=free%20download orINFO1234567=technical%20support%20included. Use %20 instead of blanks for browser compatibility purposes.

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 MD5 HASH (a 32 characters string) instead of longer references. 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:

  • 1 - the link will generate a checkout page with review; displays the credit card details form in the selected landing page. Shoppers will place orders from the review page.
  • 2 - the link will generate a checkout page without review; displays the credit card details form in the selected landing page, and enables shoppers to place orders immediately after entering their payment data, excluding the review page altogether and shortening the purchase funnel.
CART Optional

Possible values:

  • CART=0 or missing - the cart contents are "read only", meaning that the customer cannot change/edit pricing options, quantity, etc. This link will be used in the "Request payment" feature from the cPanel Generate links page.  To make the contents of the cart read-only, select the Locked Express payments checkout, which contains the CART=0 parameter. 
  • CART=1 value means that the cart permits changes to the products contained in it, e.g. quantity, pricing options, add extra products from a cross-sell).

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). 
Possible values are:

  • ALIPAY - 支付宝 (Alipay)
  • BOLETO - Boleto/Pix
  • CARTE_BLEUE - Carte Bleue
  • CCAMEX - American Express
  • CCDINERS - Diners Club
  • CCJCB - JCB
  • CCVISAMC - Visa/MasterCard/Eurocard
  • CHECK - Check
  • DIRECT_DEBIT - Direct Debit
  • DIRECT_EBANKING - DIRECTebanking.com
  • DISCOVER - Discover/Novus
  • FAX - Fax
  • FREE - Payment not required
  • GIROPAY - Giropay
  • IDEAL - iDEAL
  • PAYNEARME - Pay cash at 7-Eleven
  • PAYPAL - PayPal
  • PURCHASE_ORDER - Purchase order
  • SOLO - Solo (Discontinued)
  • TRIALPAY - TrialPay Checkout
  • VENDOR2VENDOR - Vendor to vendor
  • WEBMONEY - WebMoney
  • WE_CHAT_PAY - WeChat Pay
  • WIRE - Bank/Wire transfer

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. 

  • ar العربية Arabic
  • bg български език Bulgarian
  • cs Česky Czech
  • da Dansk Danish
  • de Deutsch German
  • el Ελληνικά Greek
  • en English
  • es Español Spanish
  • fa فارسی Persian
  • fi Suomi Finnish
  • fr Français French
  • he Hebrew עִבְרִית
  • hi Hindi
  • hr Hrvatski jezik Croatian
  • hu Magyar Hungarian
  • it Italiano Italian
  • ja 日本語 Japanese
  • ko 한국어 Korean
  • nl Nederlands Dutch
  • no Norsk Norwegian
  • pl Polski Polish
  • pt Português Portuguese
  • pt-br Português do Brasil Brazilian Portuguese
  • ro Română Romanian
  • ru Русский Russian
  • sk Slovenčina Slovak
  • sl Slovène Slovenian
  • sr Serbian
  • sv Svenska Swedish
  • th ไทย Thai
  • tr Türkçe Turkish
  • zh 中文 Chinese Simplified (Cantonese)
  • zy 繁体中文 Chinese Mandarin Traditional

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:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&CART=1

Add the recommended (cross-sell) product to cart using its link, to which the &CROSS_SELL parameter is added:

https://secure.2checkout.com/order/checkout.php?PRODS=5566778&CART=1
&CROSS_SELL[5566778]=1234567 ​​​​

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:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567,5566778&QTY=1
&CURRENCY=USD&CROSS_SELL[5566778]=1234567

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.

https://secure.2checkout.com/order/upgrade.php?LICENSE=1234567, where 1234567 represents the 2Checkout subscription reference.

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

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

  • 30 (30 days before the subscription expiration date)
  • 15 (15 days before the subscription expiration date)
  • 7 (7 days before the subscription expiration date)
  • 1 (1 days before the subscription expiration date)
  • 0 (on the expiration date)
  • 5 (5 days after the subscription expiration date)
  • 15 (15 days after the subscription expiration date)
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:

  • 1 = interstitial page
  • 2 = pop-up page
FRAUD_REVIEW Optional

Use this parameter to receive the order's fraud evaluation in the Thank You page. Possible values:

  • 1  = to receive the order fraud score in the Thank You page
  • 0 = default value; it does not trigger the fraud score evaluation.

When fraud status tracking is enabled, check the values returned in the FraudStatus variable from omnitureVars. Possible values:

  • APPROVED for orders with a low fraud risk that passed the fraud screening.
  • DENIED for orders with high score risk that were automatically rejected by the fraud engine.
  • UNDER REVIEW for orders with a high fraud risk that require manual review and approval before the charge can be collected.
  • PENDING for orders that are yet to enter the fraud screening.

Secure 'buy-links'

Use a HMAC_MD5/ HMAC_SHA signature to prevent links from being exploited. To calculate the HMAC_MD5/ 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). 

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_MD5/ 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

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:

  1. The 2Checkout platform will perform this action by default for links generated in the Merchant Control Panel and will generate the PHASH value for you.
  2. Parameter BACK_REF should be used in clear (raw, not coded) in the PHASH calculation (ex: &BACK_REF=http://www.YourCustomRedirectURL.com/), but should be encoded when adding it to the URL (ex: &BACK_REF=http%3A%2F%2Fwww.YourCustomRedirectURL.com%2F).
  3. Parameter SECURE_CART should not be taken into consideration when calculating the PHASH.
     

Example

HTTPS GET request

https://secure.2checkout.com/order/checkout.php?CART=1&PRODS=123456&QTY…

STRING for HMAC_MD5/ 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_MD5 signature*

26e471daffb47cccd9fb52e85c6abce1

Resulting HMAC_SHA2 signature*

bfd1096dd441a7907e45671a2bd9c4347700581198c2a61c09543bf97673d78d

Resulting HMAC_SHA3 signature*
ce0bb4dac94589a5f8ba778cd2ec0b3bcfaff7ff68935ddc9204ff152f3c140c
   Note: The hashing algorithm (MD5/ SHA2/ SHA3) will be determined based on an internal system configuration. 
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo