Overview

Place upgrade orders for subscriptions on behalf of your customers.

• Streamline upgrades for your existing customer base.
• Leverage payment data customers already shared with you to make the upgrade process frictionaless.

Availability

Contact 2Checkout directly to start using this functionality. 

Requirements

2Checkout strongly recommends PCI Data Security Standards (PCI DSS) compliance for this feature. 

For subscriptions to be upgradable, either by you or by the customer, the following requirements must be met:

• The product governing the subscription needs to feature a valid upgrade setup. You will only be able to upgrade subscriptions sold to your customers provided that you configured an upgrade for the product they purchased.
• The subscription up for upgrade needs to have been purchased using a credit or debit card. You won't be able to place subscription upgrade orders on behalf of your partners using payment methods other than credit/debit cards.

User privileges

You need to make sure that account users have the necessary rights to perform upgrades for customers. To enable access to this feature for users of your account, navigate to Account settings, and select Manage user access. Click on the Roles associated to specific accounts, and check the Place orders on behalf of customer under Orders & Reports option.

How to

Follow the steps below to place an upgrade order for a subscription.

1. Go to Orders & customers -> Subscriptions.
2. Run a search to find the item you want upgraded and click View to access the Subscription details page.
3. Click the Upgrade subscription button.
4. Select one of the two options available
   
   • With current payment information - the 2Checkout system uses the cardholder details currently associated with the subscription in order to bill and charge the customer for the upgrade.
   • With new payment information - you need to supply new cardholder information in order for 2Checkout to bill and charge the customer for the upgrade.

With current payment information

1. Select With current payment information.
2. Optional: Enter a valid coupon code to provide a discount. Note: the code must be associated with an already defined promotion. Click Continue.
3. On the next screen select the upgrade options and click Upgrade now.
4. You'll be redirected to the Checkout page which features all the necessary info pre-filled. You have the option of modifying the details, including the product quantity. Check the details available and click Place order to purchase the upgrade on behalf of the customer.
5. A new upgrade order will become available in the 2Checkout system for the customer's subscription. You'll get information on the new order on the Finish page.

With new payment information

1. Select With new payment information.
2. Optional: Enter a valid coupon code to provide a discount. Note: the code must be associated with an already defined promotion.
3. On the next screen select the upgrade options and click Upgrade now.
4. You'll be redirected to the Checkout page which features all the necessary info pre-filled, with the exception of the payment details, which you'll need to provide at step 5. You have the option of modifying the info on this page, including the product quantity.
5. Review the billing and delivery info, and enter new cardholder data. 2Checkout will use the credit/debit card provided here to bill and charge the customer for the subscription upgrade. Click Place order to purchase the upgrade on behalf of the customer.
6. A new upgrade order will become available in the 2Checkout system for the customer's subscription. You'll get information on the new order on the Finish page.

After you purchase an upgrade on behalf of one of your shoppers, the details page of the subscription used by the customer will be updated to reflect the details of the upgrade operation.

Overview

Renew a subscription in the Avangate system on-demand, controlling the number of days, price and currency of the extension. Use the renewSubscription method renew a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$days = 4;
$price = 50;
$currency = 'eur';

$jsonRpcRequest = array (
'method' => 'renewSubscription',
'params' => array($sessionID, $subscriptionReference, $days, $price, $currency),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Use the getPriceOptionGroup method to extract information about a specific price option group that you configured.

Parameters

Response

Request

<?php

$host   = "https://api.avangate.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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "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;
}

$GroupCode = 'USERS';

try {
    $existentPriceOptionGroup = $client->getPriceOptionGroup($sessionID, $GroupCode);
}

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

var_dump("existentPriceOptionGroup", $existentPriceOptionGroup);

?>

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'MY_PROMO_CODE_1';

// Define the first product to remove from the promotion
$newProduct1 = new stdClass;
$newProduct1->Code = '';
$newProduct1->PricingConfigurationCode = '';
$newProduct1->PricingOptionCodes = ['',''];

// Define another product to remove from the promotion
$newProduct2 = new stdClass;
$newProduct2->Code = '';
$newProduct2->PricingOptionCodes = [''];

$productPromotion = [$newProduct1, $newProduct2];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'deletePromotionProducts',
'params' => array($sessionID, $promotionCode, $productPromotion)
);
var_dump (callRPC($jsonRpcRequest, $host));

Overview

Use the unassignProductGroup method to unassign a product from a specific product group and assign it to the General product group instead. 

Parameters

Response

bool(true)

Request

<?php
 
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)) {
//        var_dump($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 = "YOURCODE12345";//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
 
$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 the login method for authentication
 
$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);
 
$ProductCode = "NewSubscriptionPlan_Code_12345";
$Code = "Code_12345AB";
 
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'unassignProductGroup',
'params' => array($sessionID, $ProductCode, $Code)
);
 
var_dump (callRPC($jsonRpcRequest, $host));
 
 
?>

Overview

Use the getOrder method to retrieve details on a specific order using its unique, system generated reference.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$orderReference = 'YOUR_ORDER_REFERENCE';

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

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

Overview

Use the getProductGroup method to extract information about a specific product group you created for your account.

Parameters

Response

Request

<?php
 
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)) {
//        var_dump($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 = "YOURCODE12345";//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
 
$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 the login method for authentication
$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);
$Code = '5C08A761E1';
 
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getProductGroup',
'params' => array($sessionID, $Code)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

Overview

Use the getProductGroups method to extract information about the product groups you created for your account.

Parameters

Response

Request

<?php

$host   = "https://api.avangate.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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "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 {
    $ProductGroups = $client->getProductGroups($sessionID);
}

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

var_dump("ProductGroups", $ProductGroups);


?>

Overview

The getProductByCode method is used to extract product information using the unique identifier you assign to subscription plans/products in SOAP API 4.

Parameters

Response

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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "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;
}

$ProductCode = 'my_subscription_1';

try {
    $ProdbyCode = $client->getProductByCode($sessionID, $ProductCode);
}

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

var_dump("ProductInfo", $ProdbyCode);


?>

Overview

The FREE payment method is ideal for free orders, where you do not require any payment information from your customers.

Availability

Available for all 2Checkout accounts.

Requirements

Free orders are available only for catalog products. The final order price has to be 0. You can either use products with 0 prices, or add a promotion for 100% of the total order price. It's mandatory to set RecurringEnabled to 'False'.

Request example

The full JSON used to place an order with credit cards would look like:

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"FREE_PRODUCT_CODE",
         "Quantity":1
      }
   ],
   "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":"FREE",
      "Currency":"USD",
      "PaymentMethod":{
         "RecurringEnabled":false
      }
   }
}

Integrate test cases

1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API the response contains an order object (order was placed successfully).
2. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully.