updates RSS feed

How to use 2Checkout Signature Generation API Endpoint

Overview

Before starting to use the 2Checkout Signature Generation API endpoint make sure you read about how to generate a JSON Web Token (JWT) and you have generated your merchant token.

To connect to the 2Checkout Signature Generation API endpoint you need to pass the merchant token to request headers and add the JSON formatted product payload.

Catalog Products Use Cases

Catalog products with lock

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • products: [] (array, required) – The products array.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        },
        {
            "code": "PRODUCT_CODE_2"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        },
        {
            "code": "PRODUCT_CODE_2"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with expiration date and lock

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • expiration: 1581003962 (string, optional) – Buy-link expiry date. The link becomes invalid after the date of this parameter. Send as a UTC UNIX timestamp.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with expiration date and custom price

Signature parameter(s):

  • currency: USD (string, required) – Pre-selected billing currency is used to charge your customers.
  • expiration: 1581003962 (string, optional) – Buy-link expiry date. The link becomes invalid after the date of this parameter. Send as a UTC UNIX timestamp.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][custom-price]: {} (object, required) – The products prices for different currencies.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 10,
                "USD": 8
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 10,
                "USD": 8
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with trial and expiration

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • expiration: 1581003962 (string, optional) – Buy-link expiry date. The link becomes invalid after the date of this parameter. Send as a UTC UNIX timestamp.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][trial-prices]: PRODUCT_CODE_1 (string, required) – The trial price for the corresponding currency.
  • products[][trial-period]: PRODUCT_CODE_1 (string, required) – The trial period.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "currency": "USD",
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "trial-prices": {"USD":10},
            "trial-period": 7
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "currency": "USD",
    "expiration": "1893456001",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "trial-prices": {"USD":10},
            "trial-period": 7
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with return method parameter

Signature parameter(s):

  • return-method[url]: https://www.example.com (string, optional) – URL to which customers are redirected after their finalized purchase.
  • return-method[type]: link (string, optional) – The return method used for redirecting your customers after a successful sale. Possible values: link, header.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

Learn more about the redirect URL in this article.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "return-method": {
        "url": "https:\/\/www.example.com",
        "type": "link"
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "return-method": {
        "url": "https:\/\/www.example.com",
        "type": "link"
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with order external reference

Signature parameter(s):

  • reference[external][order]: ref-1 (string, required) – Use this parameter to set an external reference to the order.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "external": {
            "order": "order_external_reference"
        }
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "external": {
            "order": "order_external_reference"
        }
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with customer reference

Signature parameter(s):

  • reference[customer]: ref-1 (string, required) – Customer numerical (integer) identifier/reference.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

It can be used for new acquisitions aggregating new subscriptions under an existing Customer account.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "customer": "customer_reference"
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "customer": "customer_reference"
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with external customer reference

Signature parameter(s):

  • reference[external][customer]: ref-1 (string, required) – The external customer reference.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "external": {
            "customer": "customer_external_reference"
        }
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "reference": {
        "external": {
            "customer": "customer_external_reference"
        }
    },
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with custom parameters

Signature parameter(s):

  • custom-parameters: [] (array, required) – The name field for all custom parameters is mandatory.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "custom-parameters": [
        {
            "name": "custom_param_name",
            "value": "custom_param_value"
        }
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "custom-parameters": [
        {
            "name": "custom_param_name",
            "value": "custom_param_value"
        }
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with coupons and lock parameter

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • coupons: [] (array, required) – An array of coupon codes.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "coupons": [
        "COUPON-CODE"
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "coupons": [
        "COUPON-CODE"
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with coupons and custom price

Signature parameter(s):

  • currency: USD (string, required) – Pre-selected billing currency is used to charge your customers.
  • coupons: [] (array, required) – An array of coupon codes.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][custom-price]: {} (object, required) – The products prices for different currencies.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "coupons": [
        "COUPON-CODE"
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "coupons": [
        "COUPON-CODE"
    ],
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with quantity and lock parameters

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][quantity]: integer (integer, required) – The number of units (quantity) for each product in checkout.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "quantity": 1
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "quantity": 1
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

 {"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with quantity and custom price parameters

Signature parameter(s):

  • currency: USD (string, required) – Pre-selected billing currency is used to charge your customers.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][quantity]: integer (integer, required) – The number of units (quantity) for each product in checkout.
  • products[][custom-price]: {} (object, required) – The products prices for different currencies.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "quantity": 1,
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "quantity": 1,
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with custom options and lock

Signature parameter(s):

  • lock: 1 (boolean, required) – Set TRUE or "1" to lock products.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][options]: {} (object, required) – The product options.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value2"
                }
            ]
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "lock": 1,
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value2"
                }
            ]
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with custom options and custom price

Signature parameter(s):

  • currency: USD (string, required) – Pre-selected billing currency is used to charge your customers.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][options]: {} (object, required) – The product options.
  • products[][custom-price]: {} (object, required) – The products prices for different currencies.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value2"
                }
            ],
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value2"
                }
            ],
            "custom-price": {
                "EUR": 1
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Catalog product with custom price

Signature parameter(s):

  • currency: USD (string, required) – Pre-selected billing currency is used to charge your customers.
  • products[][code]: PRODUCT_CODE_1 (string, required) – The product code.
  • products[][price]: {} (object, required) – The product prices for different currencies.
  • products[][custom-price]: {} (object, required) – The product custom prices for different currencies.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 10,
                "USD": 8
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "currency": "USD",
    "products": [
        {
            "code": "PRODUCT_CODE_1",
            "custom-price": {
                "EUR": 10,
                "USD": 8
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic Products Use Cases

Dynamic products

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Pre-selected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "price": 10
        },
        {
            "name": "PRODUCT_NAME_2",
            "price": 8
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "price": 10
        },
        {
            "name": "PRODUCT_NAME_2",
            "price": 8
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with product quantity

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][quantity]: 1 (integer, required) - The number of units (quantity) for each product in checkout.
  • products[][price]: 10 (integer, required) - The products prices value.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "quantity": 1,
            "price": 10
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "quantity": 1,
            "price": 10
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with options

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][options]: [] (array, required) - The product options.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "price": 10,
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value_1",
                    "surcharge": 3
                }
            ]
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME_1",
            "price": 10,
            "options": [
                {
                    "name": "option_name_1",
                    "value": "option_value_1",
                    "surcharge": 3
                }
            ]
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with price

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with product type

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][type]: product (string, required) - The type of dynamic product. Possible values: product, shipping, tax.

If the type parameter is empty or not send, the default line item is considered product.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "TAX_VALUE",
            "price": 10,
            "type": "tax"
        },
        {
            "name": "SHIPPING_NAME",
            "price": 10,
            "type": "shipping"
        },
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "type": "product"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "TAX_VALUE",
            "price": 10,
            "type": "tax"
        },
        {
            "name": "SHIPPING_NAME",
            "price": 10,
            "type": "shipping"
        },
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "type": "product"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with tangible parameter

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][type]: product (string, required) - The type of dynamic product. Possible values: product, shipping, tax.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][tangible]: 1 (boolean, required) - Send TRUE or 1 for products that require physical delivery.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "EUR",
    "products": [
        {
            "name": "TAX_VALUE",
            "type": "tax",
            "quantity": 1,
            "price": 1
        },
        {
            "name": "SHIPPING_NAME",
            "type": "shipping",
            "quantity": 1,
            "price": 1
        },
        {
            "name": "PRODUCT_NAME",
            "type": "product",
            "quantity": 1,
            "price": 1,
            "tangible": 1
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "EUR",
    "products": [
        {
            "name": "TAX_VALUE",
            "type": "tax",
            "quantity": 1,
            "price": 1
        },
        {
            "name": "SHIPPING_NAME",
            "type": "shipping",
            "quantity": 1,
            "price": 1
        },
        {
            "name": "PRODUCT_NAME",
            "type": "product",
            "quantity": 1,
            "price": 1,
            "tangible": 1
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with description

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][description]: text... (string, required) - Description is displayed in the checkout page.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "dynamic": "1",
    "currency": "USD",
    "merchant": "MERCHANT_CODE",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "description": "product description"
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "dynamic": "1",
    "currency": "USD",
    "merchant": "MERCHANT_CODE",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "description": "product description"
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with recurrence, duration and renewal price

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][recurrence][length]: 1 (integer, required) - Set product recurring period.
  • products[][recurrence][unit]: day (string, required) - Set product recurring unit. Example: day
  • products[][duration][length]: 1 (integer, required) - Set the duration of the recurrence period.
  • products[][duration][unit]: day (string, required) - Set the duration of the recurrence unit. Example: day
  • products[][renewal-price]: 20 (integer, required) - Set the price that should be applied to the renewal order. This parameter is conditioned by two other parameters: duration and renewal-price.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "recurrence": {
                "length": 1,
                "unit": "day"
            },
            "duration": {
                "length": 1,
                "unit": "day"
            },
            "renewal-price": 20
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "recurrence": {
                "length": 1,
                "unit": "day"
            },
            "duration": {
                "length": 1,
                "unit": "day"
            },
            "renewal-price": 20
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

Dynamic product with item external reference

Signature parameter(s):

  • dynamic: 1 (boolean, required) - Set TRUE or "1" for dynamic products.
  • currency: USD (string, required) - Preselected billing currency is used to charge your customers.
  • products[][name]: PRODUCT_NAME_1 (string, required) - The name of the dynamic product.
  • products[][price]: 10 (integer, required) - The products prices value.
  • products[][reference][external][item]: ref-1 (string, required) - Set product identifier for your dynamic products. You can send multiple values separated by semicolon.

cURL

curl -X POST \
  https://secure.2checkout.com/checkout/api/encrypt/generate/signature \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg' \
  -d '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "reference": {
                "external": {
                    "item": "item_external_reference"
                }
            }
        }
    ]
}'

PHP

$curl = curl_init();
$payload = '{
    "merchant": "MERCHANT_CODE",
    "dynamic": "1",
    "currency": "USD",
    "products": [
        {
            "name": "PRODUCT_NAME",
            "price": 10,
            "reference": {
                "external": {
                    "item": "item_external_reference"
                }
            }
        }
    ]
}';
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://secure.2checkout.com/checkout/api/encrypt/generate/signature",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'content-type: application/json',
        'merchant-token: eyJhbGciOiJIUz.............oXW6ykmEMx7XjGQPTMFg',
    ],
]);
$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response . PHP_EOL;
}

Result

{"signature":"ffff1f2daef1.....................f771ac345efff"}

 

Use PayPal

Overview

Place an order with dynamic product information, and collect the payment using PayPal.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. See code sample. 

Workflow

  1. Create the order object. Use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. Place the order.
  2. Once you place the order, Avangate logs it into the system. At this point in time, the status of the order is PENDING. Avangate responds with the Order information object.
  3. Redirect shoppers to the RedirectURL from the Order information object you receive as response from Avangate.
  4. Once shoppers log into their PayPal account and complete the transaction, they're redirected to the ReturnURL you set in the order object. Avangate also authorizes the order and updates the status to AUTHRECEIVED. 

Response

Order information Type/Description
  Object containing order information.

Request 

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->Currency = "EUR";
$Order->Language = "EN";
$Order->Country = "NL";
$Order->CustomerIP = '91.220.121.21';//"10.10.13.37";
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->CustomerReference = 421820775;
$Order->Items = array();

/**
 * 1st Product
 */
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = null;
$Order->Items[0]->Quantity = 2;
$Order->Items[0]->PurchaseType = 'PRODUCT';
$Order->Items[0]->Tangible = true; // physical
$Order->Items[0]->IsDynamic = true;

$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 100;
$Order->Items[0]->Price->Type = 'CUSTOM';

$Order->Items[0]->Name = 'Dynamic Product 1 '. date("Y-m-d H:i:s");
$Order->Items[0]->Description = 'Description Produs OTF';

$Order->Items[0]->PriceOptions = [];
$priceOption = new stdClass();
$priceOption->Name = 'Name';
$priceOption->Value = 'Value';
$priceOption->Surcharge = 10;
$Order->Items[0]->PriceOptions[] = $priceOption;

$priceOption1 = new stdClass();
$priceOption1->Name = 'Name';
$priceOption1->Value = 'Value123';
$priceOption1->Surcharge = 11;
$Order->Items[0]->PriceOptions[] = $priceOption1;

$priceOption2 = new stdClass();
$priceOption2->Name = 'Name1';
$priceOption2->Value = 'Value1';
$priceOption2->Surcharge = 12;
$Order->Items[0]->PriceOptions[] = $priceOption2;

$Order->Items[0]->RecurringOptions = new stdClass();
$Order->Items[0]->RecurringOptions->CycleLength = 1;
$Order->Items[0]->RecurringOptions->CycleUnit = 'MONTH';
$Order->Items[0]->RecurringOptions->CycleAmount = 1234;
$Order->Items[0]->RecurringOptions->ContractLength = 3;
$Order->Items[0]->RecurringOptions->ContractUnit = 'YEaR';

/**
 * 3rd Product - SHIPPING
 */
$Order->Items[2] = new stdClass();
$Order->Items[2]->Name = 'Shipping Item '. date("Y-m-d H:i:s");
$Order->Items[2]->PurchaseType = 'SHIPPING';
$Order->Items[2]->Quantity = 1;
$Order->Items[2]->Price = new stdClass();
$Order->Items[2]->Price->Amount = 123;
$Order->Items[2]->IsDynamic = true;

/**
 * 4th Product - TAX
 */
$Order->Items[3] = new stdClass();
$Order->Items[3]->Name = 'Tax Item '. date("Y-m-d H:i:s");
$Order->Items[3]->PurchaseType = 'TAX';
$Order->Items[3]->Quantity = 1;
$Order->Items[3]->Price = new stdClass();
$Order->Items[3]->Price->Amount = 456;
$Order->Items[3]->IsDynamic = true;
$Order->Items[3]->RecurringOptions = new stdClass();
$Order->Items[3]->RecurringOptions->CycleLength = 1;
$Order->Items[3]->RecurringOptions->CycleUnit = 'MONTH';
$Order->Items[3]->RecurringOptions->CycleAmount = 10.2;
$Order->Items[3]->RecurringOptions->ContractLength = 3;
$Order->Items[3]->RecurringOptions->ContractUnit = 'YEaR';

/**
 * 5th Product - COUPON
 */
$Order->Items[4] = new stdClass();
$Order->Items[4]->Name = 'Coupon Item '. date("Y-m-d H:i:s");
$Order->Items[4]->PurchaseType = 'COUPON';
$Order->Items[4]->Quantity = 1;
$Order->Items[4]->Price = new stdClass();
$Order->Items[4]->Price->Amount = 234;
$Order->Items[4]->IsDynamic = true;

/**/
$additionalField1 = new stdClass();
$additionalField1->Code = "additional_field_order_1";
$additionalField1->Text = "REST";
$additionalField1->Value = "1";

$additionalField2 = new stdClass();
$additionalField2->Code = "additional_field_order_2";
$additionalField2->Text = "REST";
$additionalField2->Value = "a";

$additionalField3 = new stdClass();
$additionalField3->Code = "additional_field_order_3";
$additionalField3->Text = "REST";
$additionalField3->Value = "a";

$Order->AdditionalFields = array();
$Order->AdditionalFields[0] = $additionalField1;
$Order->AdditionalFields[1] = $additionalField2;
$Order->AdditionalFields[2] = $additionalField3;

$additionalField1 = new stdClass();
$additionalField1->Code = "REST";
$additionalField1->Text = "REST";
$additionalField1->Value = "REST";



$Order->MachineId = 'machineIdTestDan';
$Order->Discount = null;
$Order->ExternalReference = null;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'Address 1';
$Order->BillingDetails->Address2 = 'Address 2';
$Order->BillingDetails->City = 'Billing City';
$Order->BillingDetails->State = 'Billing State';
$Order->BillingDetails->CountryCode = 'NL';
$Order->BillingDetails->Phone = US;
$Order->BillingDetails->Email = 'shopper@avangate.com';
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->Company = 'Billing Company';
$Order->BillingDetails->Zip = '12345';


/**/
$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Address 1';
$Order->DeliveryDetails->Address2 = 'Address 2';
$Order->DeliveryDetails->City = 'Billing City';
$Order->DeliveryDetails->State = 'Billing State';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer@email.com';
$Order->DeliveryDetails->FirstName = 'John';
$Order->DeliveryDetails->LastName = 'Doe';
$Order->DeliveryDetails->Zip = 12345;
/**/

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'PAYPAL';
$Order->PaymentDetails->Currency = 'eur';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '91.220.121.21';
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'http://yourreturnurl.com';
$Order->PaymentDetails->PaymentMethod->Email= 'email@avangate.com';

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'placeOrder';
$jsonRpcRequest->params = array($sessionID, $Order);
$jsonRpcRequest->id = $i++;

$APIOrderFullInfo = callRPC((Object)$jsonRpcRequest, $host);

$url = $APIOrderFullInfo->PaymentDetails->PaymentMethod->RedirectURL;

header ("Location: $url");

Place orders with cross-selling campaigns

Overview

Cross-selling allows you to recommend additional products to customers and increase the average order value. The 2Checkout Public API supports classic cross-sell campaigns which means you can recommend more products from your own product catalog to your shoppers.

CrossSell Object for the placeOrder API method

Use the CrossSell object below to recommend additional products to customers via JSON-RPC API 6.0.

Parameter name Type Required/Optional Description
ParentCode String Required Product code of the product to be recommended to the shopper.
CampaignCode String Required The upsell campaign code.

Request Example

{ 
  "Currency": "USD", 
  "Language": "EN", 
  "Country": "US", 
  "CustomerIP": "10.10.10.10", 
  "Source": "sourceAPI.net", 
  "CustomerReference": 421820775, 
  "Items": [ 

    { 
      "Code": "15", 
      "Quantity": 1 
    }, 
    { 
      "Code": "34924C876E", 
      "Quantity": 1, 
      "CrossSell":{ 
        "ParentCode" : "15", 
        "CampaignCode" : "2Xrl83KSkemCv3G3dL%2B9eA%3D%3D" 
      } 
    } 
  ], 

   "BillingDetails":{ 

      "FirstName":"Customer First Name", 
      "LastName":"Customer Last Name", 
      "CountryCode":"US", 
      "State":"California", 
      "City":"San Francisco", 
      "Address1":"Example Street", 
      "Zip":"90210", 
      "Email":"example@email.com" 

   }, 

  "PaymentDetails": { 
    "Type": "CC", 
    "Currency": "USD", 
    "CustomerIP": "10.10.10.10", 
    "PaymentMethod": { 

      "Vendor3DSReturnURL": "https:\/\/example.com", 
      "Vendor3DSCancelURL": "https:\/\/example.com", 
      "CardNumber": "4111111111111111", 
      "CardType": "VISA", 
      "ExpirationYear": "2020", 
      "ExpirationMonth": "12", 
      "CCID": "123", 
    } 
  } 
}

Response

Using the same structure, the getContents method will take into account the discount associated with the cross-sell campaign and display the appropriate prices and taxes.

{ 
    "Country": "DE", 
    "Currency": "EUR", 
    "Items": [ 
        { 
            "Code": "NIQRPI0GTU", 
            "Quantity": 1 
        }, 

        { 
            "Code": "0XICS3OVDK", 
            "Quantity": 1, 

"CrossSell":{ 
        "ParentCode" : " NIQRPI0GTU ", 
        "CampaignCode" : "2Xrl83KSkemCv3G3dL%2B9eA%3D%3D" 
      } 

        } 
    ], 

    "BillingDetails": { 
        "FirstName": "Customer First Name", 
        "LastName": "Customer Last Name", 
        "CountryCode": "DE", 
        "City": "Bucharest", 
        "Address1": "Example Street", 
        "Zip": "73331", 
        "Email": "example@email.com" 
    } 
}

Place an order

Overview

Use the placeOrder method to create an order and collect the payment.

Supported payment methods

  1. Credit/Debit cards: Visa, Visaelectron, MasterCard, Maestro, Amex, Discover, Dankort, Cartebleue, JCB. Avangate supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Puchase Order
  4. Wire
  5. Check
  6. Previous order references - In addition to the payment methods enumerated above, Avangate also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts. 

For antifraud purposes, Avangate limits the number of successive purchases made using the same credit card.

Requirements

As reseller of your products, Avangate must validate your compliance with the PCI requirements, making sure you meet Payment Card Industry (PCI) standards when using the New Purchase Avangate API. You alone control the level of complexity of your PCI compliance. 

Details on some of the most frequent PCI compliance levels for ecommerce businesses and the associated steps you need to follow to obtain the compliance and be able to start using the New Purchase Avangate API are available here: New Purchase Avangate API PCI DSS Requirements.

You're required to include the following text when using Avangate API-client side encryption and to make it visible for your customers in the ordering interface. 

Order processed by Avangate, authorized reseller and merchant of the products and services offered within this store.

Currency support

Check with Avangate support for a list of currencies available for each payment method. 

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

Response

Order information

Object

Request


<?php
 
//The following script let's you place an new order with Credit/Debit cards as the payment method
 
function callRPC($Request, $hostUrl, $Debug = true) {
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
 
 
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
 
    if (!empty($ResponseString)) {
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}
 
$host = 'https://api.avangate.com/rpc/3.0/';
 
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel.
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel.
 
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
// call login
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
 
$sessionID = callRPC($jsonRpcRequest, $host);
 
var_dump($sessionID);
$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1; 
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false; 
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'email@avangate.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 83.21; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 13.35; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

$jsonRpcRequest = array (
'method' => 'placeOrder',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Set up subscription upgrades

Overview

Make sure that your customers use the latest iteration of your products, and that they're able to upgrade to newer versions. The 2Checkout upgrade functionality supports scenarios such as switching to a different subscription plan or to another version of the same product.

Requirements

  • The upgrade product has the renewal/recurring billing system enabled (subscriptions are generated): the upgradable products also need to have the renewal/recurring billing system switched on.
  • The upgrade product doesn't use subscriptions (the renewal/recurring billing system is not enabled): all products are valid upgrade options, whether subscriptions are generated for them or not.

Upgrade scenarios

A different product Product A to Product B
A different version of the current product Product A v1 to Product A v2
A different subscription plan Product A 1 user to Product A 3 users
An upgraded product

Product A to Product B

and

Product A to Product C

(set up upgrades for one product to multiple products with different upgrade set-ups)

Set a product upgrade

  1. Select the products that are eligible.
  2. Set the pricing scheme and customize it.
  3. Set the subscription details for the upgrade.

Step 1: Configure upgrade products

Upgrades can be set up by configuring the Upgrade product.

  1. Navigate to Products, under Setup, and run a search to identify the upgraded product. Click to edit it, and then select the Upgrade tab.
  2. Choose the upgradable products from the list in the Edit your upgrade options area. Multiple selections are possible when holding down the CTRL key.

You can configure multiple products to upgrade to the same offering. 

The Available products area lists only items with subscriptions as valid options for upgrade products with subscriptions.

Step 2: Choose the pricing scheme

Choose the pricing scheme that you want to apply for the upgrade.

Pricing

In addition to defining the pricing strategy for the original and the upgrade products, the 2Checkout upgrade area offers additional controls impacting the costs customers incur during the upgrade process. Shoppers can pay:

  • Option 1. The full upgrade product price.
  • Option 2. The difference between the original subscription and the upgraded product.
  • Option 3. A prorated upgrade price calculated using the most recent costs incurred by the customer (Upgrade costs can differ from product price as they reflect the most recent transaction made for the subscription and reflect the impact of discounts offered, custom charges, on-the-fly pricing, etc.).
  • Option 4. A prorated upgrade price calculated using the product's pricing set-up at the time of the order (Upgrade costs are not impacted by previous discounts, custom charges, personalized pricing, etc.).

You can also customize the upgrade price by adding or subtracting a specific percent.

Prorated upgrade price

2Checkout offers the option of upgrading an ongoing subscription anytime during its lifecycle, except for when it's expired or disabled/canceled. Note: Expired subscriptions can still be upgraded during the grace period, while their status is Past due.

Using this feature together with the Upgrade option will result in a successful calculation of a prorated price for any model. 2Checkout will calculate the period of time that the customer has left from the current subscription cycle and how much he needs to be charged extra.

Note: When calculating the subscription period consumed, seconds are used as a time unit.

Ignore subscription past due period when calculating prorated upgrade price

Customers may renew their subscriptions even after they expire, taking advantage of the Grace Period you can set in the product Renewal setup. To avoid charging an unnecessary extra amount for the upgrade, you can ignore the previous past due period set on a subscription when computing the prorated price.

On the product upgrade page, mark the option Ignore grace period when calculating Upgrade to ignore the grace period set in your Renewal Settings when computing the prorated price for the upgrade.

Ignore grace period

Setup examples

1. Options selected:

  • The shopper will pay: The full upgrade product price
  • The upgrade does not affect the original subscription duration or
  • Create a new subscription (disable the existing one) or
  • Prolong the subscription from the upgrade purchase date

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

Irrelevant

$200/30 days

P1 to P2 upgrade price formula

The shopper will pay $200 for the upgrade, the full price of the upgraded product.

 

2. Options selected:

  • The shopper will pay: The difference between the original subscription and the upgraded product
  • The upgrade does not affect the original subscription duration or
  • Create a new subscription (disable the existing one) or
  • Prolong the subscription from the upgrade purchase date

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

$100

$200/30 days

P1 to P2 upgrade price formula

The shopper will pay $100 for the upgrade, the difference between the cost of Product 2 and the price of Product 1.

 

3. Options selected:

  • The shopper will pay: A prorated upgrade price calculated using the most recent costs incurred by the customer
  • Create a new subscription (disable the existing one) or
  • Prolong the subscription from the upgrade purchase date

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

$90

$200/30 days

P1 to P2 upgrade price formula

Product 2 price - Reference costs for Product 1 * Lifetime left from Product 1 subscription/ Total lifetime of Product 1 subscription = $140
This scenario is not supported for imported subscriptions, until a charge happens on them.

4. Options selected:

  • The shopper will pay: A prorated upgrade price calculated using the most recent costs incurred by the customer
  • The upgrade does not affect the original subscription duration

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

$90

$200/30 days

P1 to P2 upgrade price formula

Product 2 price - Reference costs for Product 1 * Lifetime left from the Product 1 subscription/ Total lifetime of Product 1 subscription - Product 2 price * (Total lifetime of Product 2 subscription - Lifetime left from the Product 1 subscription) / Total lifetime of Product 2 subscription = $73.4

 

5. Options selected:

  • The shopper will pay: A prorated upgrade price calculated using the product's pricing setup at the time of the order
  • Create a new subscription (disable the existing one) or
  • Prolong the subscription from the upgrade purchase date

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

$90

$200/30 days

P1 to P2 upgrade price formula

Product 2 price -Product 1 price * Lifetime left from the Product 1 subscription / Total Lifetime of Product 1 subscription = $133.3

 

6. Options selected:

  • The shopper will pay: A prorated upgrade price calculated using the product's pricing setup at the time of the order
  • The upgrade does not affect the original subscription duration

Product 1 price

Discounts or special pricing

Days used

Reference upgrade cost

Product 2 cost

$100/30 days

$10 or 10%

10

$90

$200/30 days

P1 to P2 upgrade price formula

Product 2 price - Product 1 price * Lifetime left from the Product 1 subscription/ Total Lifetime of Product 1 subscription - Product 2 price * (Total lifetime of Product 2 subscription - Lifetime left from the Product 1 subscription) / Total lifetime of Product 2 subscription = $66.8

Customize your upgrade price

Available only for the following options:

  • The full upgrade product price
  • The difference between original subscription and the upgrade product

These options enable you to modify the actual upgrade price by adding or subtracting a specific percentage.

Subscription period option for the upgrade

When configuring an upgrade for a product with the renewal/recurring billing system enabled (for which subscriptions are generated), you'll also be able to configure how the upgrade process impacts existing subscriptions. Note: Options are not displayed for products with the subscription renewal system disabled.

Three options are available:

  • Generate a new subscription for the upgraded product and disable the one created for the upgradable offering;
  • Prolong the subscription of the upgradable offering, even though the customer will be using the upgraded product;
  • The subscription duration of the upgraded product will not impact the subscription of the upgradable offering.

Using product catalog pricing

Enable the Use product catalog pricing option to ignore all custom upgrade prices set for a product, using instead its initial price, defined in the product catalog. Removing custom prices also disables any existing retention campaigns for the selected subscriptions.

Step 3: Subscription verification system

Optionally, you can enable the subscription verification system, directing shoppers to a generic product upgrade page and requiring them to provide the subscription activation key before they can see the available upgrade options. The subscription verification system only applies to subscriptions that require an activation code.

Zero value upgrades

When upgrading a subscription to one with a lower value, automatic renewal is kept regardless of the Collect Payment details for full discount or orders with 'zero' value option in Ordering options.

Retrieve a promotion

Overview

Use the getPromotion method to extract information on a promotion you set up for your account.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

PromotionCode

Required (string)

 

System-generated identifier Avangate associated with promotion campaigns.

Response

Promotion object.

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'YOUR_COUPON_CODE';

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getPromotion',
'params' => array($sessionID, $PromotionCode)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

Update order/product additional fields

Request

<?php

$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}

$AdditionalField                             = new stdClass();
$AdditionalField->Label                      = 'Do you agree with the new newsletter policy 2015?';
$AdditionalField->Type                       = 'LISTBOX';
$AdditionalField->Code                       = 'NewsletterPolicy1234576';
$AdditionalField->ApplyTo                    = 'ORDER';
$AdditionalField->Values                     = array();
$AdditionalField->Values[0]                  = 'YES';
$AdditionalField->Values[1]                  = 'NO';
$AdditionalField->ValidationRule             = null;
$AdditionalField->Translations               = array();
$AdditionalField->Translations[0]            = new stdClass();
$AdditionalField->Translations[0]->Label     = "Êtes-vous d'accord avec la politique de la newsletter?";
$AdditionalField->Translations[0]->Values    = array();
$AdditionalField->Translations[0]->Values[0] = 'Oui';
$AdditionalField->Translations[0]->Values[1] = 'Non';
$AdditionalField->Translations[0]->Language  = 'fr';
$AdditionalField->Translations[1]            = new stdClass();
$AdditionalField->Translations[1]->Label     = 'Haben Sie mit dem Newsletter Politik zu?';
$AdditionalField->Translations[1]->Values    = array();
$AdditionalField->Translations[1]->Values[0] = 'Ja';
$AdditionalField->Translations[1]->Values[1] = 'Nein';
$AdditionalField->Translations[1]->Language  = 'de';

$FieldCode = 'NewsletterPolicy1234576';

try {
    $UpdateAdditionalField = $client->updateAdditionalField($sessionID, $FieldCode, $AdditionalField);
}

catch (SoapFault $e) {
    echo "UpdateAdditionalField: " . $e->getMessage();
    exit;
}

var_dump("UpdateAdditionalField", $UpdateAdditionalField);


?>

Retrieve account's time zone

Overview

Use the getTimezone method to retrieve information on the time zone used by your account for the 2Checkout API.

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Response

Timezone

String

 

The time zone you selected or the default GMT+02:00 time zone of the 2Checkout system.

Request


<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
try {
    $Timezone = $client->getTimezone($sessionID);
}
catch (SoapFault $e) {
    echo "Timezone: " . $e->getMessage();
    exit;
}
var_dump("Timezone", $Timezone);

 

Retrieve account's time zone

Overview

Use the getTimezone method to retrieve information on the time zone used by your account for the 2Checkout API.

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Response

Timezone

String

 

The time zone you selected or the default GMT+02:00 time zone of the 2Checkout system.

Request


<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
try {
    $Timezone = $client->getTimezone($sessionID);
}
catch (SoapFault $e) {
    echo "Timezone: " . $e->getMessage();
    exit;
}
var_dump("Timezone", $Timezone);

 

Assign order/product additional fields

Overview

Use the assignAdditionalField method to update additional fields for your account.

Parameters

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

FieldCode

Required (string)

 

Field identifier. Alpha-numeric chars, underscores and dashes.

Required

Boolean

 

True or False depending on whether you want make the field mandatory or not.

ProductCode

Required (string)

 

The unique product code that you control not the system-generated product identifier.

Response

bool(true)

Request

<?php

$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}

$ProductCode = 'AAA4643116';
$FieldCode = 'NewsletterPolicy123457106';
$Required = true;
try {
    $AssignedAdditionalField = $client->assignAdditionalField($sessionID, $FieldCode, $Required, $ProductCode);
}

catch (SoapFault $e) {
    echo "AssignedAdditionalField: " . $e->getMessage();
    exit;
}

var_dump("AssignedAdditionalField", $AssignedAdditionalField);

?>

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.

Get in touch

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.

Contact sales Get Started
Verifone logo