Overview

Use the setSubscriptionUpgrade method to upgrade a subscription.

Requirements

You can only upgrade subscriptions with automatic renewal enabled.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$productCode = 'YOUR_PRODUCT_CODE';
$options = 'YOUR_PRICE_CODES'; //case sensitive; include only price options codes (exclude spaces)
$customPrice = 1;

$jsonRpcRequest = array (
'method' => 'setSubscriptionUpgrade',
'params' => array($sessionID, $subscriptionReference, $productCode, $options, $customPrice),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Use the createCrossSellCampaign method to create a cross-sell campaign for your 2Checkout account.

Request parameters

Response parameters

Request sample

<?php 

require ('PATH_TO_AUTH'); 

$csCampaign = new stdClass(); 
$csCampaign->MasterProducts = ['C8851A5BC9']; 
$csCampaign->DisplayType = 'cart'; 
$csCampaign->DisplayInEmail = false; 
$csCampaign->Name = 'testing'; 
$csCampaign->StartDate = '2019-09-20'; 
$csCampaign->EndDate = '2020-10-21'; 
$csCampaign->Products = []; 
$csCampaign->Products[0] = new stdClass(); 
$csCampaign->Products[0]->ProductCode = '512712FA53'; 
$csCampaign->Products[0]->Discount = 15; 
$csCampaign->Products[0]->DiscountType = 'PERCENT'; 


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

$csCampaignResponse = callRPC($jsonRpcRequest, $host, true); 

Overview

Use the getProductUpgradeOptionsPrice method to retrieve information about the costs a customer incurs when upgrading a specific subscription. Retrieve information about the costs a customer incurs when upgrading a specific subscription.

Parameters

Response

The response returns details about the upgrade price for a single product. For multiple products, the user needs to calculate the value using the quantity x upgradePrice (the value from the returned response) parameters.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$productCode = 'my_subscription_123';
$currency = 'usd';
$options = 'emailsupport;oneuser1';

try {
    $upgradeOptions = $client->getProductUpgradeOptionsPrice($sessionID, $subscriptionReference, $productCode, $currency, $options);
}
catch (SoapFault $e) {
    echo "upgradeOptions: " . $e->getMessage();
    exit;
}
var_dump("upgradeOptions", $upgradeOptions);

Overview

Use the searchPayouts method to extract information on the historical payouts issued by 2Checkout for your account.

You can retrieve information on the payment for a specific invoice, or search based on numerous filters such as payment status, transfer date, or payout method.

Search filters

Request

<?php

require('PATH_TO_AUTH');

$SearchOptions = new stdClass();
//$SearchOptions->Reference = 'FBV8572'; // search for a specific invoice
$SearchOptions->Status = ['PAID', 'CANCELED'];
$SearchOptions->Currency = 'USD';
$SearchOptions->StartDate = '2018-05-01';
$SearchOptions->EndDate = '2018-06-01';
$SearchOptions->PaymentType = 'WIRE';
$SearchOptions->OrderBy = [];
$orderBy = new stdClass();
$orderBy->Field = 'TransferCompletionDate';
$orderBy->Direction = 'DESC';
$SearchOptions->OrderBy[] = $orderBy;
$SearchOptions->Pagination = new stdClass();
//$SearchOptions->Pagination->Page = 1;
//$SearchOptions->Pagination->Limit = 200;

try {
    $subscriptionInfo = $client->searchPayouts($sessionID, $SearchOptions);
}
catch (SoapFault $e) {
    echo "AccountPayouts: " . $e->getMessage();
    exit;
}
var_dump("Payouts", $subscriptionInfo);

Response

Historical payout object

Overview

2Checkout provides recurring-revenue-based businesses with a comprehensive suite of revenue recovery tools, as well as the expertise and guidance to tailor and fine-tune your strategy to achieve industry-high revenue loss prevention and revenue recapture rates. Use the Revenue Recovery Tools to fight involuntary churn and increase your long-term revenues by up to 20%.

Revenue Recovery Tools are a unique set of features of the 2Checkout platform that are used for recovering and collecting transactional revenues lost due to poor authorization rates and include, without limiting, the following :

Availability

• Basic revenue recovery tools are available by default for all types of plans (2Sell, 2Subscribe, 2Monetize).
• 2Recover add-on is available on demand for all types of plans (2Sell, 2Subscribe, 2Monetize).

Basic Revenue Recovery Tools

Basic revenue recovery tools are available for all accounts (2Sell, 2Subscribe, 2Monetize).

Account Updater

Account Updater is a key customer retention tool designed to support seamless updates of credit/debit card account information. 

What is Account Updater Service

Account Updater is a generic term for programs such as Visa's Account Updater or MasterCard Automatic Billing Updater that are offered by the credit card networks to automatically update subscription customer card data when cardholder information changes or goes out of date.

How Does an Account Updater Service Work

This service records changes to credit card account numbers and expiration dates due to mergers, portfolio flips (e.g., Visa to MasterCard), re-issued cards (from loss or security breach) account closures, and product upgrades.

Companies that participate in updater programs have several ways to check the information in their subscriber database: automated nightly updates that check any card you have processed in the past six months, requests for information on specific cards that have been declined and requests for information on a set of cards due for their next billing installment.

Basic Retry Logic

Basic Retry Logic involves the first two (2) renewal authorizations 2Checkout makes to recover expired subscriptions for which the renewal process failed.

Smart Retry Logic

Availability

The smart retry logic is available to all MoR merchants on request. As we are in the early adopter phase, currently building on top of the existing functionality, please contact your account manager or sales representative should you be interested in activating this feature. 

Benefits

• Maximizing authorization rates by adjusting retry logic to local payment behaviors​

• Reduced number of failed payment attempts

Use cases

Adapting the retry scheme to billing length

A company sells both monthly and yearly/bi-yearly subscriptions and has different grace period settings, depending on the billing length. To reduce soft declines due to insufficient funds, the company wants to have different post-expiration retry schemes for monthly and yearly/bi-yearly subscriptions.

Leverage the best days of the month for authorization

A company sells monthly subscriptions in different countries. After an analysis of authorization rates, they realize that for one or more billing countries, the authorization rates are consistently higher in a certain interval of the month. The company wants to leverage that information to drive up its authorization rates.  

Mitigate increased fraud score risk

A company has the maximum number of attempts configured and has seen authorization rates dropping lately. They suspect this is due to the high number of attempts per auto-renewal order that is having a side effect because the processors/issuing banks can view this as a possible fraud. The company would like to make fewer retries for monthly subscriptions and space out attempts for yearly subscriptions to mitigate the risk of having their transactions flagged as potentially fraudulent. 

2Recover Add-on 

The 2Recover add-on is available on-demand as part of the 2Recover add-on. Contact 2Checkout directly for more information. 2Recover add-on includes the basic revenue recovery tools plus: 

• 2Checkout Updater
• Advanced Retry Logic
• Hard Declines Notifications
• Advanced Authorization Report (new acquisition, auto-renewal, manual renewal) 

2Checkout Updater

2Checkout Updater is a key customer retention tool designed to support seamless updates of credit/debit card account information. 

Advanced retry logic

Advanced Retry Logic involves multiple renewal authorizations 2Checkout makes beyond those of Basic Retry Logic.

Hard Declines Notifications

Read more about hard decline notifications here.

Advanced Authorization  Report 

The advanced authorization report section in your Merchant Control Panel includes dedicated sections for each of the extra features in the 2Recover add-on, as well as the ability to display the report for new acquisitions and manual renewals. 

Self-service

Requirements

1. To request the activation of the 2Recover add-on, your account must meet the following criteria:

• Less than 1% chargeback rate over the last 3 months
• Have at least 10 active auto-renewing subscriptions
• Use a 2Sell, 2Subscribe, 2Monetize 2Checkout account

2. If your account meets the requirements above, you can click on Activate Advanced Options in your Merchant Control Panel.

3. Next, you'll be prompted with a message informing you that we will activate the module for your account in 48 hours.

4. As soon as we activate the module, you will receive an email notifying you about the activation.

2Recover Add-on Fees and Revenue

2Recover Add-on Incurred Fees

Commission (net amount, does not include taxes) for the recurring payments 2Checkout recovered when renewing subscriptions using the 2Recover add-on. 2Checkout does not charge fees for basic recovery tools. To calculate the recovered revenue fee, generate the report using the Attempt date selector.

2Checkout keeps the 2Recover add-on fees even in the eventuality of chargebacks or refunds.

Total Earnings from the 2Recover Add-on

Total recurring charges successfully recovered using the 2Recover add-on, reported according to authorization dates, when the 2Checkout system collects funds from your customers.

Invoice for 2recover add-on fees

2Checkout issues an invoice for the advanced recovery fees at the end of each month.

Overview

Add/import subscriptions in the Avangate system. Include card data with your subscription import only if you contacted 2Checkout to enable this functionality for your account. Otherwise, the import process results in a failure. Contact 2Checkout or your account manager directly for more details.

Attributes

Card payment

Add credit/debit card details when importing subscriptions. 2Checkout uses payment information in the recurring billing process. 

For imports of test subscriptions, use the credit card information from this article.

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';
$Code = "Code_12345AB";
try {
    $AssignedProductGroup = $client->unassignProductGroup($sessionID, $ProductCode, $Code);
}

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

var_dump("AssignedProductGroup", $AssignedProductGroup);

?>

Overview

Use the savePrices method to update product prices for a specific pricing configuration.

Parameters

Response

bool(true)

<?php
require ('PATH_TO_AUTH');

/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Dynamic pricing configuration
 *
 * Send two prices, including the required one for the default currency
 * The method will append the prices for the sent entries, without removing the previous values
 *
 * If the quantities intervals were not defined then they will be set.
 * If the quantities overlap with existing defined intervals, an Exception will be thrown.
 */
 
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 140;
$Price->Currency = 'USD';
$Prices[] = $Price;
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 10;
 
$PriceOptions = array();
 
$PricingConfigurationCode = '5553603382';
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);

$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
// will output:
// bool(true)

 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the VOLTAGE pricing option group assigned and marked as required.
 * If prices are sent WITHOUT setting the pricing option group and options will set the price but without setting values for the options prices.
 */
 
// Call the login method for authentication
$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
$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);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
// if PricingOption group is not required, will set price for combination of QuantityInterval - no-pricing-option-value.
$PriceOptions = array();
 
// if PricingOption group is required, then send options by assigning a PriceOptionsAssigned object (group code and options)
// $optionAssigned = new stdClass(); // PriceOptionsAssigned
// $optionAssigned->Code = 'VOLTAGE';
// $optionAssigned->Options = array('220V'); // radio option group
// $PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the COLOR and scalenotmandatory pricing option group assigned and marked as required.
 */
// Call the login method for authentication
$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
$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);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 10;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'COLOR'; // checkbox pricing option group, multiple values are allowed
$optionAssigned->Options = array('cyan', 'magenta');
$PriceOptions = array($optionAssigned);
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'scalenotmandatory'; // interval pricing option group
$optionAssigned->Options = array('scalenotmandatory-1-5');
$PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PriceOptions = array();
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
?>

Overview

Extend the lifetime of a subscription in the 2Checkout system on-demand. Use the extendSubscription method to set a new expiration deadline for a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$days = 5;

try {
    $extendedSubscription = $client->extendSubscription($sessionID, $subscriptionReferenceTest, $days);
}
catch (SoapFault $e) {
    echo "extendedSubscription: " . $e->getMessage();
    exit;
}
var_dump("extendedSubscription", $extendedSubscription);

Overview

Use this object via SOAP API 4.0 to retrieve information about shipping fees. 

Parameters