# 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](/shopping-carts/convertplus/convertplus-url-parameters.md) 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.

{% hint style="info" icon="lightbulb" %}

#### 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!

<a href="https://www.2checkout.com/lp/2checkout_convertplus_cart.html" class="button primary" data-icon="book-open-lines">Read more</a>
{% endhint %}

## ConvertPlus parameters that require a signature

<table><thead><tr><th width="184">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>return-url</code></td><td>URL to which customers are redirected after their finalized purchase. Learn more about Redirect URL on <a href="/pages/176f15b833b9311d6f352514eb3f1aa3e1a3f188">this</a> article.</td></tr><tr><td><code>return-type</code></td><td><p>The return method used for redirecting your customers after a successful sale. Possible values:</p><ul><li>Link in the Thank You page</li><li>Header Redirect</li></ul></td></tr><tr><td><code>expiration</code></td><td><p>Buy link expiry date. The link becomes invalid after the date from this parameter. Send as a UTC timestamp.</p><p>Example: 1537549421 </p></td></tr><tr><td><code>order-ext-ref</code></td><td>Use this parameter to set an external reference to the order.</td></tr><tr><td><code>item-ext-ref</code></td><td>Set product identifier for your dynamic products. You can send multiple values separated by semicolon ;.</td></tr><tr><td><code>customer-ref</code></td><td>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.</td></tr><tr><td><code>customer-ext-ref</code></td><td>The external customer reference.</td></tr><tr><td><code>currency</code></td><td>Preselected <strong>billing currency</strong> 2Checkout uses to charge your customers.</td></tr><tr><td><code>prod</code></td><td><p>The name of the dynamic product. For multiple products, send them separated by a semicolon. </p><p>Example: name1;name2;name3.</p></td></tr><tr><td><code>price</code></td><td><p>For dynamic products, enter the product price. For multiple dynamic items, send the values separated by a semicolon. </p><p>Example: price1;price2;price3.</p></td></tr><tr><td><code>qty</code></td><td><p>The number of units (quantity) for each product in checkout, separated by a semicolon;. Do not use spaces or blanks. Example: <strong>qty=2;1</strong>.</p><p><strong>qty</strong> works in conjunction with <strong>prod</strong>, based on their respective order. The first value of the <strong>qty</strong> parameter controls the number of units for the products whose identifier is in the first position of the <strong>prod</strong> parameter. </p><p>Example: <a href="https://secure.2checkout.com/checkout/buy/?merchant=2COLNC&#x26;">https://secure.2checkout.com/checkou...rchant=2COLNC&#x26;</a><strong>prod=6FD08E61B5;E2932D0DE2&#x26;qty=4;3</strong></p></td></tr><tr><td><code>type</code></td><td><p>The type of dynamic product. Possible values:</p><ul><li>digital</li><li>physical</li><li>shipping</li><li>tax</li></ul><p>If type is empty or not send, the default line item is considered <strong>product</strong>.</p><p>For multiple dynamic items, send the values separated by a semicolon.</p></td></tr><tr><td><code>opt</code></td><td><p>Defines the product pricing options.</p><p><strong>URL formating rules:</strong></p><p>":" is considered a pair separator</p><ul><li><p>1 product with 1 price option with 1 value (includes scale option type)</p><ul><li>prod=code1&#x26;opt=gr1:val1</li></ul></li><li><p>1 product with 1 price option with multiple values</p><ul><li>prod=code1&#x26;opt=gr1:val1:val2</li></ul></li></ul><p>"," is considered a value separator</p><ul><li><p>1 product with 2 price options with 1 value each</p><ul><li>prod=code1&#x26;opt=gr1:val1,gr2:val2</li></ul></li><li><p>1 product with 2 price options with multiple values each</p><ul><li>prod=code1&#x26;opt=gr1:val1:val2,gr2:val3:val4</li></ul></li></ul><p>";" is considered a parameter separator between products</p><ul><li><p>2 products with 1 price option containing 1 value</p><ul><li>prod=code1;code2&#x26;opt=gr1:val1;gr2:val2</li></ul></li><li><p>2 products with 1 price option containing multiple values</p><ul><li>prod=code1;code2&#x26;opt=gr1:val1:val2;gr2:val3:val4</li></ul></li><li><p>2 products with 2 price options containing 1 value each</p><ul><li>prod=code1;code2&#x26;opt=gr1:val1,gr2:val2;gr3:val3,gr4:val4</li></ul></li><li><p>2 products with 2 price options containing multiple values each</p><ul><li>prod=code1;code2&#x26;opt=gr1:val1:val2,gr2:val3:val4;gr3:val5:val6,gr4:val7:val8</li></ul></li></ul></td></tr><tr><td><code>description</code></td><td>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.</td></tr><tr><td><code>recurrence</code></td><td><p>For dynamic products, set product recurring options.</p><p>Send multiple dynamic items separated by a semicolon.</p><p>Example: period1:unit1;period2:unit2;</p><p>Possible values for units:</p><ul><li>DAY</li><li>WEEK</li><li>MONTH</li><li>YEAR</li><li>FOREVER</li></ul><p>*This parameter is conditioned by two other parameters: <strong>duration</strong> and <strong>renewal-price</strong>.</p></td></tr><tr><td><code>duration</code></td><td>For dynamic products, set the duration of the recurrence.</td></tr><tr><td><code>renewal-price</code></td><td>For dynamic products, set the price that should be applied to the renewal order.</td></tr></tbody></table>

## 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](https://docs.2checkout.com/get-started-with-the-2checkout-api/) 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:

* &#x20;   **merchant** = 'MCODE'
* &#x20;   **dynamic** = '1'
* &#x20;   **prod** = 'Software'
* &#x20;   **price** = 10
* &#x20;   **currency** = 'USD'
* &#x20;   **qty** = 1
* &#x20;   **type** = 'digital'
* &#x20;   **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:

* &#x20;   **merchant** = '2COLRNC'
* &#x20;   **dynamic** = '1'
* &#x20;   **prod** = 'Software' <-- SIGNATURE REQUIRED
* &#x20;   **price** = 10        <-- SIGNATURE REQUIRED
* &#x20;   **currency** = 'USD'        <-- SIGNATURE REQUIRED
* &#x20;   **qty** = 1             <-- SIGNATURE REQUIRED
* &#x20;   **type** = 'digital'         <-- SIGNATURE REQUIRED
* &#x20;   **expiration** = '1893456000' <-- SIGNATURE REQUIRED

We extract only those parameters:

* &#x20;   **prod** = 'Software'
* &#x20;   **price** = 10
* &#x20;   **currency** = 'USD'
* &#x20;   **qty** = 1
* &#x20;   **type** = 'digital'
* &#x20;   **expiration** = 1893456000

#### Sort the parameters alphabetically

* &#x20;   **currency** = 'USD'
* &#x20;   **expiration** = 1893456000
* &#x20;   **price** = 10
* &#x20;   **prod** = 'Software'
* &#x20;   **qty** = 1
* &#x20;   **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.

* &#x20;   **currency** = '3USD'
* &#x20;   **expiration** = 101893456000 &#x20;
* &#x20;   **price** = 210
* &#x20;   **prod** = '8Software'
* &#x20;   **qty** = 11
* &#x20;   **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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2checkout.com/shopping-carts/convertplus/convertplus-buy-links-signature-for-dynamic-products.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.