Skip to main content

ConvertPlus Buy-Link Signature for Catalog Products

ConvertPlus Buy-Link Signature for Catalog Products

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

Overview

You can generate links for catalog products outside the Merchant Control Panel, using the ConvertPlus parameters explained in this article. Some of the ConvertPlus buy-link parameters require a signature for the redirect.

 

Recommended resources

Generate custom links

ConvertPlus parameters that require a signature:

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

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

  • Link in the Thank You page
  • Header Redirect
expiration

Buy link expiry date. The link becomes invalid after the date of this parameter. Send as a UTC timestamp.

Example: 

1537549421 

order-ext-ref Use this parameter to set an external reference to the order.
item-ext-ref Set product identifier for your catalog products. When included, the parameter needs to be signed.
customer-ref The 2Checkout system generates default customer numerical (integer) IDs automatically for all orders of products that feature subscriptions. It can be used for new acquisitions aggregating new subscriptions under an existing Customer account.
customer-ext-ref The external customer reference.

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-url, return-type, expiration, order-ext-ref,customer-ref, customer-ext-ref, lock.
  2. 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.
  3. Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
  4. Parameters to be included for on-the-fly pricing for catalog products: prod, priceqty, opt, coupon, currency.
  5. 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.

Build the ConvertPlus Signature

To sign a ConvertPlus buy-link, you need to follow these steps:

  1. Sort the parameters that require a signature alphabetically.
  2. Serialize the parameters and append to them the length of their values.
  3. Concatenate the resulting values.
  4. The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
  5. The resulting value is added to the buy-link under the signature parameter.

In order to generate a valid ConvertPlus signature, you can include the below parameters as well. The merchant parameter does not require to be signed.

  •     merchant = '2COLRNC' (this is the merchant code)
  •     prod = 'E2932D0DE2'  (this is the product code)
  •     qty = 1

EXAMPLE 

When encrypting the values to generate the signature, for the return-url parameter, use an URL with the following structure: https://..... Do not use an encoded URL.

Let's consider the following parameters:

  •     return-url = 'https://www.2checkout.com'
  •     return-type = 'redirect'
  •     expiration = '1665835200'
  •     order-ext-ref = '123456'

The regular buy-link will have the following structure:

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&prod=E2932D0DE2&qty=1&return-url=https%3A%2F%2Fwww.2checkout.com&return-type=redirect&expiration=1665835200&order-ext-ref=123456

Sort the parameters alphabetically 

  •     expiration = '1665835200'
  •     order-ext-ref = '123456'
  •     return-type = 'redirect'
  •     return-url = 'https://www.2checkout.com'

Serialize the values 

To serialize a value, you need to append before it the number of letters or digits a value has. For example, the expiration parameter has the '1665835200' value that will be serialized as '101665835200', where 10 is the number of digits that make up the value. The value of the return-type parameter is 'redirect', so the serialized value will be '8redirect', where 8 is the number of letters that make up the value.

  •     expiration = '101665835200'  
  •     order-ext-ref = '6123456'
  •     return-type = '8redirect'
  •     return-url = '25https://www.2checkout.com'

Concatenate the values 

    '10166583520061234568redirect25https://www.2checkout.com'

Encrypt using your Secret Word 

The serialized value is then encrypted using the HMAC method.
    - the algorithm used is sha256
    - the key used when encrypting is the merchant secret word (in this example, the secret word is 'secret_word')

This outputs a 64 character string:

520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358

Add the string in the buy-link 

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&prod=E2932D0DE2&qty=1&test=1&return-url=https%3A%2F%2Fwww.2checkout.com&return-type=redirect&expiration=1665835200&order-ext-ref=123456&signature=520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358
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