ConvertPlus Buy-Link signature for catalog products

Overview

Use signed buy-links to override the configured price of a catalog product at checkout. The signature prevents tampering with the price and other parameters passed as query strings.

The buy link signature is an HMAC-SHA256 hash computed from a subset of URL parameters using your **Buy Link Secret Word** (you can find this in the Merchant Control Panel) as the key. Any parameter listed as *signed* below must be included in the hash if it is present in the URL.

The merchant parameter is never signed.

Buy-link URL format

The buy-link URL should have the following format:

https://secure.2checkout.com/checkout/buy?merchant=MERCHANT_CODE&prod=PRODUCT_CODE&qty=QTY&price=CURRENCY:AMOUNT&currency=CURRENCY&signature=SIGNATURE

Parameters

Parameter	Required / Optional	Signed	Description
merchant	Required	No	Your merchant code.
prod	Required	Yes	Catalog product code. Multiple products: semicolon-separated (`prod=CODE1;CODE2`).
qty	Required	Yes	Quantity. Multiple products: semicolon-separated (`qty=1;2`).
price	Required	Yes	Price override. See Price Format below.
currency	Required	Yes	ISO 4217 currency code (e.g. `USD`, `EUR`).
opt	Optional	Yes	Pricing option codes, semicolon-separated.
coupon	Optional	Yes	Coupon code.
lock	Optional	Yes	Set to `1` to prevent the customer from modifying the cart.
return-url	Optional	Yes	Redirect URL after a successful purchase. Use the unencoded URL when computing the signature.
return-type	Optional	Yes	Redirect method: `redirect` (header redirect) or `link` (link on thank-you page).
expiration	Optional	Yes	UTC Unix timestamp after which the link is no longer valid.
order-ext-ref	Optional	Yes	External order reference.
customer-ref	Optional	Yes	Numeric customer ID.
customer-ext-ref	Optional	Yes	External customer reference (e.g. email).
customer-lock	Optional	Yes	Set to "1" to lock all pre-filled billing/delivery information and route shoppers directly to the order review page. When set to "1", the following parameters need to also be included in the signature: customer-ref or customer-ext-ref or billing fields email name phone country state city address address2 zip company-name fiscal-code tax-office delivery fields ship-email ship-name ship-phone ship-country ship-state ship-city ship-address ship-address2

Price format

For catalog products, the `price` parameter must embed the currency code as a prefix: price=USD:100

For multiple currencies on the same product, separate pairs with a comma: price=USD:100,EUR:90,GBP:80.

For multiple products, separate per-product price definitions with a semicolon: price=USD:100,EUR:90;USD:50,EUR:45.

Using a plain numeric value (e.g. `price=100`) without the currency prefix will result in an Empty cart error.

renewal-price is not a valid parameter for catalog products. It is only available for dynamic products (dynamic=1). To set a renewal price for a subscription catalog product, you must configure it in the product settings in the Merchant Control Panel.

Signature algorithm

Follow these steps to generate the signature:

1. Collect signed parameters - Take only the parameters marked as *Signed* that are present in your URL. Skip any that you are not using.
2. Sort alphabetically by parameter name: currency, expiration, lock, opt, order-ext-ref, price, prod, qty, return-type, return-url, etc.
3. Serialize each value by prepending the character length of the value to the value itself:

   Value	Serialized
   USD	3USD
   USD:100	7USD:100
   VQHKBLQNXW	10VQHKBLQNXW
   1	11

4. Concatenate all serialized values by joining them into a single string (no separator).
5. Compute HMAC-SHA256 by using your Buy Link Secret Word as the key.
6. Append to URL - Add the resulting 64-character hex string as the `signature` parameter.

Example

Parameters

Parameter	Value	Signed
merchant	2COLRNC	No
prod	E2932D0DE2	Yes
qty	1	Yes
price	USD:100	Yes
currency	USD	Yes

Step-by-step

1. Signed parameters, sorted alphabetically: currency = USD price = USD:100 prod = E2932D0DE2 qty = 1
2. Serialized values: USD → 3USD USD:100 → 7USD:100 E2932D0DE2 → 10E2932D0DE2 1 → 11
3. Concatenated string: 3USD7USD:10010E2932D0DE211
4. HMAC-SHA256 (with secret word `secret_word`): <64-character hex signature>.
5. Final URL:

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&prod=E2932D0DE2&qty=1&price=USD:100&currency=USD&signature=<signature> 

Example with general parameters

Parameter	Value	Signed
merchant	2COLRNC	No
prod	E2932D0DE2	Yes
qty	1	Yes
price	USD:100	Yes
currency	USD	Yes
return-url	https://www.example.com	Yes
return-type	redirect	Yes
expiration	1893456000	Yes

Sorted signed parameters: currency, expiration, price, prod, qty, return-type, return-url.

Concatenated serialized string: 3USD101893456000 7USD:10010E2932D0DE2118redirect22https://www.example.com.

For `return-url`, use the raw, unencoded URL in the signature even if it is percent-encoded in the final URL.

Code sample

Python

```python
import hmac
import hashlib

merchant = "YOUR_MERCHANT_CODE"
secret   = "YOUR_BUY_LINK_SECRET_WORD"

# Add only the parameters you are using
params = {
    "currency": "USD",
    "price":    "USD:100",   # must use CURRENCY:AMOUNT format
    "prod":     "YOUR_PRODUCT_CODE",
    "qty":      "1",
    # "return-url":  "https://yoursite.com/thank-you",
    # "return-type": "redirect",
    # "expiration":  "1893456000",
}

# Sort alphabetically, serialize, concatenate
serialized = "".join(str(len(v)) + v for _, v in sorted(params.items()))

# HMAC-SHA256
signature = hmac.new(
    secret.encode("utf-8"),
    serialized.encode("utf-8"),
    hashlib.sha256
).hexdigest()

url = (
    f"https://secure.2checkout.com/checkout/buy"
    f"?merchant={merchant}"
    f"&prod={params['prod']}"
    f"&qty={params['qty']}"
    f"&price={params['price']}"
    f"&currency={params['currency']}"
    f"&signature={signature}"
)

Javascript - (Browser — Web Crypto API)

javascript
async function generateBuyLink({ merchant, secret, prod, qty, price, currency }) {
  const params = { currency, price, prod, qty };

  const sorted = Object.entries(params).sort(([a], [b]) => a.localeCompare(b));
  const serialized = sorted.map(([, v]) => String(v.length) + v).join("");

  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw", enc.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false, ["sign"]
  );
  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(serialized));
  const signature = Array.from(new Uint8Array(sig))
    .map(b => b.toString(16).padStart(2, "0")).join("");

  const query = new URLSearchParams({ merchant, prod, qty, price, currency, signature });
  return `https://secure.2checkout.com/checkout/buy?${query}`;
}

Validating your signature

Use the Signature Generation API endpoint to generate a signature server-side and compare it against your own implementation. The API uses the Buy Link Secret Word configured in your merchant account.

```bash
curl -X POST https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H "Content-Type: application/json" \
  -H "merchant-token: YOUR_JWT" \
  -d '{
    "merchant": "YOUR_MERCHANT_CODE",
    "currency": "USD",
    "products": [
      {
        "code": "YOUR_PRODUCT_CODE",
        "quantity": 1,
        "custom-price": { "USD": 100 }
      }
    ]
  }'

Troubleshooting

Error	Cause	Fix
Empty cart	Invalid signature	Verify serialized string.
Empty cart	Wrong price format (`price=100`)	Use `price=USD:100`.
Empty cart	`renewal-price` used with a catalog product	Remove it; set it in the Merchant Control Panel
Empty cart	Wrong secret key	Use Buy Link Secret Word, not API/INS key.
Wrong price displayed	Currency mismatch	Match `currency` param with prefix in `price`.