ConvertPlus Buy-Links Signature for Dynamic Products

Overview

You can generate links for dynamic products outside the Merchant Control Panel, using the ConvertPlus parameters explained in this article. Some of the ConvertPlus buy-link parameters require a signature, to prevent any interference in the ordering process. Optional parameters also require a signature if they are included in the generated buy-link.

ConvertPlus parameters that require a signature

ConvertPlus parameters to be included in the signature - general rules

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.
2. Parameters to be included in the signature for dynamic products buy-links: currency, prod, price, qty, 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, price, qty, opt, coupon.
5. The parameter to be included in order to lock the cart for catalog products: lock.
6. 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

Example

Let's consider the following parameters:

•     merchant = 'MCODE'
•     dynamic = '1'
•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

The regular buy-link will have the following structure:

https://www.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10currency=USD&qty=1&type=digital&expiration=1893456000 

This link is missing one last parameter, a signature.

Let's take a look at the list of parameters that require a signature:

•     merchant = '2COLRNC'
•     dynamic = '1'
•     prod = 'Software' <-- SIGNATURE REQUIRED
•     price = 10        <-- SIGNATURE REQUIRED
•     currency = 'USD'        <-- SIGNATURE REQUIRED
•     qty = 1             <-- SIGNATURE REQUIRED
•     type = 'digital'         <-- SIGNATURE REQUIRED
•     expiration = '1893456000' <-- SIGNATURE REQUIRED

We extract only those parameters:

•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

Sort the parameters alphabetically

•     currency = 'USD'
•     expiration = 1893456000
•     price = 10
•     prod = 'Software'
•     qty = 1
•     type = 'digital'

Serialize the values

To serialize a value, you need to prepend to it the number of letters or digits a value has. For example, the currency parameter has the 'USD' value that will be serialized as '3USD', where 3 is the number of letters that make up the value. The value of the price parameter is '10', so the serialized value will be '210', where 2 is the number of digits that make up the value.

In case a value uses special characters, to serialize it, you need to prepend to it the number of bytes in the string, also known as the UTF-8 string length. To count the bytes in the string, you can use an online bytes counter. For example, if the prod parameter has the 'ελληνικά' value, this will be serialized as '16ελληνικά' and not as '8ελληνικά', due to the use of special characters, where '16' is the number of bytes in the string.

•     currency = '3USD'
•     expiration = 101893456000  
•     price = 210
•     prod = '8Software'
•     qty = 11
•     type = '7digital'

Concatenate the values

    '3USD1018934560002108Software117digital'

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_wordbuylink')

This outputs a 64 character string:

c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762

Add the string in the buy-link

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10&currency=USD&qty=1&type=digital&expiration=1893456000&signature=c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762