Skip to main content

ConvertPlus URL parameters

ConvertPlus URL parameters

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

Overview

Use 2Checkout ConvertPlus to provide your customers with a swift and safe payment experience. Depending on your desired workflow, you can either create ordering interface links using our dedicated interface (ConvertPlus) or generate the parameters dynamically, in your own system.

2Checkout enables you to use ConvertPlus with both catalog products and with products generated dynamically via buy-link parameters.

 

Availability 

Eligible 2Checkout accounts. Contact 2Checkout to inquire about ConvertPlus. 

Requirements 

To use ConvertPlus dynamic ordering, pass the dynamic parameter with TRUE or 1 value. When creating orders with catalog products, the prod parameter should contain the product code of your catalog item. For dynamic ordering, the prod parameter should contain the name of your dynamic product.  

How to create dynamic ConvertPlus buy-links

  1. Start from the base ConvertPlus buy-link:

     https://secure.2checkout.com/checkout/buy/?
    
  2. Add your merchant code to the buy-link, so that 2Checkout links the sale to your account. Your merchant code can be found in your Control Panel, in the Account Information area. Example: merchant=2COLRNC.

  3. Set the dynamic parameter to TRUE or 1.

  4. Add product information such as product typename, price, and quantity.

  5. Include additional product information, such as recurring options or customer redirect URL.

Sample ConvertPlus buy-link for dynamic product information

The following buy-link reproduces a dynamic ordering experience:

https://secure.2checkout.com/checkout/buy/?merchant=2COLRNC&dynamic=1&prod=2CheckoutSubscription&type=PRODUCT&qty=1&price=10&test=1

Buy-link 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 products, discounts, currency, and more. You can use these query parameters to generate checkout links in your own system, without having to rely on the functionality in your account. 

Parameter Required/Optional Description

Billing information

 

Use these parameters to control the billing information displayed in the shopping cart. By adding these parameters in the buy-link, you can pre-fill the customer information and minimize the customer effort in the ordering process.

email Optional Send customer email
name Optional Send full customer name. Ex: "John Steward Doe".
phone Optional Send customer phone number
country Optional Send customer country code. Two-digits code. Ex: "UK".
state Optional Send customer state code. Two-digits code. Ex: "CA".
city Optional Send customer city.
address Optional Send customer address
address2 Optional Send customer additional address information
zip Optional Send customer zip code
company-name Optional

Send Company name.

When sending the Company name, the Company checkout flow will be triggered. Otherwise, the default checkout flow for ConvertPlus is the individual flow.

fiscal-code Optional

Send company Fiscal code.

When sending the Fiscal code, the Company checkout flow will be triggered only if also another company flow relevant parameter will be also sent (Company name and/or Tax office). Otherwise, the default checkout flow for ConvertPlus is the individual flow.

tax-office Optional

Send company Tax office.

When sending the Tax office, the Company checkout flow will be triggered. Otherwise, the default checkout flow for ConvertPlus is the individual flow.

Delivery information

Use these parameters to control the billing information displayed in the shopping cart. By adding this parameters in the buy-link, you can pre-fill the customer information and minimize the customer effort in the ordering process.

ship-name Optional Send customer delivery name. Ex: "John Steward Doe".
ship-country Optional Send customer delivery country code. Two-digits code. Ex: "UK".
ship-state Optional Send customer delivery state code. Two-digits code. Ex: "CA".
ship-address Optional Send customer delivery address
ship-address2 Optional Send customer additional delivery address information
ship-zip Optional Send customer delivery zip code

Product information

Use the parameters to create products with dynamic information, skipping the need of handling a product catalog in your 2Checkout Control Panel

dynamic Required for dynamic products Boolean. Set TRUE for dynamic products.
prod For catalog products Product codes added to checkout, separated by a semicolon.

Do not use spaces or blanks. Example: prod=46CC15F39;7488E17CC0. Product codes are assigned by you at the moment you are adding new products.

In the Control Panel, click to edit a product, and select the Information tab. The Product code of the item you're editing is available at the top of the General area under Information.

Warning: Changing a product code already used in active buy-links will completely break the checkout flow for those links. If you change a product code, make sure all your buy-links for that product are replaced with new links generated with your current product code. 

For buy-links with on-the-fly and trial pricing, this parameter is mandatory and has to be included in the signature.

prod For dynamic products

Set the dynamic parameter TRUE to use dynamic products in the ordering process.

When using dynamic products, the prod parameter contains as value the name of the dynamic product. For multiple products, send them separated by a semicolon.

Example: name1;name2;name3.

item-ext-ref For dynamic products Set product identifier for your dynamic products. When included, the parameter needs to be signed.
type Required for dynamic products

The type of the dynamic product. Possible values:

  • PRODUCT
  • SHIPPING
  • TAX

For multiple dynamic items, send the values separated by a semicolon.

qty Required 

The number of units (quantity) for each product in checkout, separated by a semicolon ;. Do not use spaces or blanks. Example: qty=2;1.

qty works in conjunction with prod, based on their respective order. The first value of the qty parameter controls the number of units for the products whose identifier is in the first position of the prod parameter. 

Example: https://secure.2checkout.com/checkou...rchant=2COLNC&prod=6FD08E61B5;E2932D0DE2&qty=4;3

  • For buy-links with on-the-fly pricing, this parameter is required and has to be included in the signature.
  • For trials, qty parameter can only be 1 and it is not required.
price Required for catalog products with on-the-fly pricing

For catalog products with on-the-fly pricing, custom price and currency must be included in the buy-link.

For multiple products with on-the-fly pricing, send the values separated by a semicolon.

Example: price=currency1:val1;currency2:val2;currency3:val3.

For buy-links with multiple prices per each product in a catalog product with on-the-fly pricing scenario, there are multiple use cases:

  1. The values of separate products (qty=1;2;3) are separated by a semicolon. This means that the first product will have quantity 1, the second product will have quantity 2, and the third product will have quantity 3.
  2. The pair values for different products: price=EUR:10;EUR:11;EUR:12. Each pair of currency-price is separated by a semicolon and the pairs of products itself are separated by a colon. This means that the first product will have a custom price of 10EUR, the second product will have a custom price of 11EUR, and the third product will have a price of 12EUR.
  3. The pair values for the same product: price=EUR:10,USD:11,RON:12. Each pair of currency-price is separated by a comma, while the values inside each pair are separated by a colon. This means that this price definition is for a single product with custom prices of 10EUR, 11USD and 12RON.
  4. The pair values for multiple products: price=EUR:10,USD:11,RON:12,EUR:20,USD:21,RON:22. Use a colon to separate the custom prices for multiple products. Each pair of currency-price is separated by a comma and the values of each pair are separated by a colon. This means that the price definition for the first product will be 10EUR, 11USD and 12RON and the price definition for the second product will be 20EUR, 21USD, and 22RON.

For buy-links with on-the-fly pricing, this parameter is mandatory and has to be included in the signature.

Note:

  • Values of parameters that relate to separate products are separated with a semicolon.
  • Parameters that are configured to support multiple values, like price or opt, should have their values separated by a comma if those values refer to the same product.
  • Pair values should be separated by a colon.
price Required for dynamic products

For dynamic products, enter the product price.

For multiple dynamic items, send the values separated by a semicolon.

Example: price1;price2;price3.

tprices Required for catalog product with trial pricing

For catalog products with trial pricing, the currency must be included in the buy-link.

Multiple products not supported:

 

  • The pair values for the same product: price=EUR:10,USD:11,RON:12. Each pair of currency-price is separated by a comma, while the values inside each pair are separated by a colon. This means that this price definition is for a single product with custom prices of 10EUR, 11USD and 12RON.

For buy-links with trial pricing, this parameter is mandatory and must be included in the signature.

 

Note:

  • Parameters that are configured to support multiple values, like opt, should have their values separated by a comma if those values refer to the same product.
  • Pair values should be separated by a colon.

Note: tprices and tperiod are incompatible with custom price, as tprices and tperiod go hand in hand. 

tperiod Required for catalog product with trial pricing The minimum tperiod number is 7 days. 
currency

Required for catalog product with trial pricing

E.g.,: currency=USD
tangible Required for dynamic products

Boolean.

Send TRUE or 1 for products that require physical delivery.

opt Optional Defines the product pricing options.

URL formating rules:

":" is considered a pair separator

  • 1 product with 1 price option with 1 value (includes scale option type)
    • prod=code1&opt=gr1:val1
  • 1 product with 1 price option with multiple values
    • prod=code1&opt=gr1:val1:val2

 

"," is considered a value separator

  • 1 product with 2 price options with 1 value each
    • prod=code1&opt=gr1:val1,gr2:val2
  • 1 product with 2 price options with multiple values each
    • prod=code1&opt=gr1:val1:val2,gr2:val3:val4

 

";" is considered a parameter separator between products

  • 2 products with 1 price option containing 1 value
    • prod=code1;code2&opt=gr1:val1;gr2:val2
  • 2 products with 1 price option containing multiple values
    • prod=code1;code2&opt=gr1:val1:val2;gr2:val3:val4
  • 2 products with 2 price options containing 1 value each
    • prod=code1;code2&opt=gr1:val1,gr2:val2;gr3:val3,gr4:val4
  • 2 products with 2 price options containing multiple values each
    • prod=code1;code2&opt=gr1:val1:val2,gr2:val3:val4;gr3:val5:val6,gr4:val7:val8

For buy-links with on-the-fly and trial pricing, this parameter is mandatory and has to be included in the signature.

description Optional for dynamic products For dynamic products, set a description that is displayed in the checkout page. The description field is displayed only for the 'One column with payment buttons' template. The description will not be visible in the default template.
recurrence Required for dynamic products

For dynamic products, set product recurring options.

Send multiple dynamic items separated by a semicolon.

Example: period1:unit1;period2:unit2;

 

Possible values for units:

  • DAY
  • WEEK
  • MONTH
  • YEAR
  • FOREVER

*This parameter is conditioned by two other parameters: duration and renewal-price.

duration Required for dynamic products

For dynamic products, set the duration of the recurrence.

Send multiple dynamic items separated by a semicolon.

Example: period1:unit1;period2:unit2;

 

Possible values for units:

  • DAY
  • WEEK
  • MONTH
  • YEAR
  • FOREVER

*This parameter is conditioned by two other parameters: recurrence and renewal-price.

renewal-price Required for dynamic products For dynamic products, set the price that should be applied to the renewal order.
product-additional-fields Optional (only for new acquisitions, manual renewal, and custom prices) For LISTBOX additional fields the value must be a valid value from the dropdown.

Cart behavior

Use the parameters below to control the purchasing flow. You can add a success URL for your finalized orders, change the cart template, add a source parameter or choose to place test orders.

merchant Required Your merchant identification code. The merchant code is available in Settings > Edit system settings, under the System settings tab.

subscription

Required for the manual renewal of catalog products 

Unique system-generated identifier of your subscriptions. The subscription reference is available on Orders and customers à Subscriptions à Edit subscription details.

expiration Optional Buy-link expiry date. The link becomes invalid after the date from this parameter. Send as a UTC timestamp. Example: 

1537549421 

return-url Optional URL to which customers are redirected after their finalized purchase. Learn more about Redirect URL on this article.
return-type Optional

The return method used for redirecting your customers after a successful sale. Possible values:

  • Link 
  • Redirect

Read more about redirect URL.

coupon

Optional

Promotion coupon code discounting the price of a product added to checkout. You can send multiple values separated by semicolon when standalone coupons discount different products added to checkout. 
For example: [...]&coupon=voucher1;voucher2[...]

If this parameter is added to the buy-link, it has to be included in the signature.

src Optional

Use this parameter to identify the source of your sales (which links are performing better).  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.

tpl Optional

Cart template used for the checkout experience.

Possible values:

  • default
  • one-column

Use the style parameter to send ConvertPlus cart themes customized via Cart Editor.

currency Optional Preselected billing currency 2Checkout uses to charge your customers.
empty-cart Optional Boolean. Use for resetting cart contents.
back-url Optional Use this parameter behind the 'Back to Shopping' link in the shopping cart to redirect your customers to a website of your choice.
order-ext-ref Optional Use this parameter to set an external reference to the order.
language Optional

Defines the language for the order interface. English is the default language.

Available values for language codes are displayed in this article.

origin-url Optional Set an origin URL for the purchase.
style Optional

Use style for setting a customized cart template for the checkout experience.

The parameter can be populated with the styling code assigned to each of your customized ConvertPlus cart themes. Contact 2Checkout to learn how to retrieve the styling code for your customized themes.

test Optional Use test=1 to place test orders. Exclude for regular order. Dummy credit card details are provided so you can test the entire order placing process. Guidance on the 2Checkout test ordering system is available here.
customer-ref Optional The 2Checkout system generates default customer numerical (integer) IDs automatically for all orders of products that feature subscriptions. Can be used for new acquisitions aggregating new subscriptions under an existing Customer account.
customer-ext-ref Optional The external customer reference
lock Optional (only for catalog products)

You can define customized packages or products for your shoppers and increase consistency and reconciliation between internal reporting, considering the details available at checkout and the ones valid when placing the order.

This action can be done by using the 'lock' buy-link parameter which must be included in the signature along with other parameters that could impact the price: coupon, currency, lock, prod, qty, opt.

When the cart is locked, the coupon field will not be visible anymore and the shoppers will not be able to add coupons to the cart.

To enable, add the lock parameter to the generated buy-link, set it to 1 (lock = '1') and sign it.

order-additional-fields Optional (only for new acquisitions and manual renewal)

For LISTBOX additional fields the value must be a valid value from the dropdown.

Example: product-additional-fields=field_identifier:value1;field_identifier2:value2

ConvertPlus parameters to be included in the signature 

  1. General parameters included in the signature, regardless of the type of checkout (catalog products, dynamic products, renewal, unfinished payment): return-urlreturn-typeback-url, expirationorder-ext-refcustomer-refcustomer-ext-ref.
  2. Parameters to be included in the signature for dynamic products buy-links: currencyprod, priceqtytangibletypeoptdescriptionrecurrencedurationrenewal-price, item-ext-ref.
  3. Parameters to be included in the signature for manual renewal buy-links: prodqtyopt.
  4. Parameters to be included for on-the-fly pricing for catalog products: prodpriceqtyopt, coupon, currency.
  5. Parameters to be included for trial pricing for catalog products: prod, tprices, tperiod, opt, currency.
  6. Parameters to be included in order to lock the cart for catalog products: lock.
  7. Parameters to be included when an approved URL is set: in this case, all parameters will be included in the signature, when redirected after successful completion of a sale.
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