ConvertPlus URL parameters
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.
ConvertPlus is a full-stack solution that enables you to increase conversion rates with faster loading time and optimized flows. Download this solution brief to learn more!
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
Start from the base ConvertPlus buy-link:
https://secure.2checkout.com/checkout/buy/?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.
Set the dynamic parameter to TRUE or 1.
Add product information such as product type, name, price, and quantity.
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:
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.
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.
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:
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.
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.
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.
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.
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.
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.
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: https://verifone.cloud/docs/2checkout/Documentation/07Commerce/2Checkout-ConvertPlus/Set-a-redirect-URL-for-ConvertPlus-ordering-flows/
return-type
Optional
The return method used for redirecting your customers after a successful sale. Possible values: Link, Redirect. Read more about redirect URL: https://verifone.cloud/docs/2checkout/Documentation/07Commerce/2Checkout-ConvertPlus/Set-a-redirect-URL-for-ConvertPlus-ordering-flows/
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. 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). Example: src=prodpage or src=dldpage.
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
1 or 0. 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: https://verifone.cloud/docs/2checkout/Documentation/07Commerce/Checkout-links-and-options/2Checkout-supported-languages/
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: https://verifone.cloud/docs/2checkout/Documentation/Test_ordering_system
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. Use 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: order-additional-fields=field_identifier:value1,field_identifier2:value2
ConvertPlus parameters to be included in the signature
General parameters included in the signature, regardless of the type of checkout (catalog products, dynamic products, renewal, unfinished payment): return-url, return-type, back-url, expiration, order-ext-ref, customer-ref, customer-ext-ref.
Parameters to be included in the signature for dynamic products buy-links: currency, prod, price, qty, tangible, type, opt, description, recurrence, duration, renewal-price, item-ext-ref.
Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
Parameters to be included for on-the-fly pricing for catalog products: prod, price, qty, opt, coupon, currency.
Parameters to be included for trial pricing for catalog products: prod, tprices, tperiod, opt, currency.
Parameters to be included in order to lock the cart for catalog products: lock.
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.
Related:
Generate a Buy-Link using the ConvertPlus and InLine Checkout: https://verifone.cloud/docs/2checkout/Documentation/07Commerce/Checkout-links-and-options/Generate-a-Buy-Link-using-ConvertPlus-and-InLine-Checkout
Products and subscriptions listing query parameters: https://verifone.cloud/docs/2checkout/Documentation/myAccount/Products-and-subscriptions-listing-query-parameters
Subscriber management and self-service: https://verifone.cloud/docs/2checkout/Documentation/Subscription-Billing/03Subscriber-management-and-self-service
Need help?
Contact support or get 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.
Get in touch: https://verifone.cloud/need-help
Not yet a Verifone customer?
Contact sales
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.
Contact sales: https://www.verifone.com/en/global/contact-sales Get Started: https://www.verifone.com/en/global/contact-sales
Last updated
Was this helpful?