ConvertPlus Buy-Link Signature for Catalog Products
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:
|
| 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
- 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.
- 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 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:
- Sort the parameters that require a signature alphabetically.
- Serialize the parameters and append to them the length of their values.
- Concatenate the resulting values.
- The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
- 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:
520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358Add 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
