Overview

Use the addSubscriptionUsage method via JSON-RPC API 6.0 to update specific usage easier, to add one usage line at a time, without having to create a file to do so, or to add multiple usages at the same time. 

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = 'B7D8E72224';
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'method' => 'addSubscriptionUsage',
    'params' => array($sessionID, $SubscriptionReference, array(array("OptionCode" => "MeteredPricing", "UsageStart" => "2020-02-22 15:40:00", "UsageEnd" => "2020-03-22 15:40:00","Units" => 10))),
    'id' => $i++
);
var_dump ("addSubscriptionUsage", callRPC((Object)$jsonRpcRequest, $host));

Response 

The successful addSubscriptionUsage call via JSON-RPC APIv6 returns the Usage object.

{
"jsonrpc": "2.0",
"id": 260,
"result": [
{
"UsageReference": "120011112631",
"SubscriptionReference": "67F3AD6A32",
"OptionCode": "USG_MN",
"UsageStart": "2020-07-06 12:00:00",
"UsageEnd": "2020-07-07 12:00:00",
"Units": 10,
"Description": "",
"RenewalOrderReference": 0
}
]
}

Error handling

Overview

A cookie is a small text file that a website places on a user’s computer (including smartphones, tablets, or other connected devices) to store information about the user’s activity. Throughout the world, regulating entities see cookies as a “persistent identifier”, thus falling under the rules applied to protect Internet users' personal information.

Regulatory entities:

• For California – CCPA
• For EU – GDPR, ePrivacy Directive, Cookies and other tracking technologies
• National regulations (per country) on privacy and protection of personal information

Availability

All merchants have access to Merchant Control Panel. Consequently, all of them will be seeing the cookie consent displayed (in one form or another, depending on where they are located when they access the portal. See more details below).

Cookie Management in the Merchant Control Panel

For merchants in California (USA), the European Union, and the rest of the world (ROW), 2Checkout uses three types of cookies:

• Security (mandatory) - These cookies help protect merchants' data available during and after logging into their 2Checkout account and cannot be disabled.
• Preference (optional) - These cookies are used to remember customers’ choices during navigation through their 2Checkout accounts, such as pagination selection or list types.
• Statistics (optional) - These cookies help 2Checkout understand the merchants' interaction with their Merchant Control Panel so that our system can identify issues and continuously improve the overall experience merchants have. Data is collected and reported anonymously.

2Checkout collects consent upon the merchants' first access in the Merchant Control Panel through a link at the bottom of the landing page, where the user can:

• Accept all cookies - This will check all the above 3 types of cookies (Security, Preference, Statistics)
• Customize settings/Do not sell my info (for California users only) - This will enable the user to check any cookies other than the mandatory ones
• Access the 2Checkout cookie policy.

For US users with unidentified state locations, 2Checkout will display the rules applied for California users. For ROW users with unidentified state location 2Checkout will display the rules applied for EU users.

Cookie Module Display Based on Merchant Location

The Cookie module will be displayed differently depending on merchants' locations.

Cookie module displayed for merchants in the European Union

By clicking on the Customize settings button, the user will be prompted with a separate window where they can choose their preferred settings.

Once the merchant performs an action on the Cookie Settings link in the footer, this will not be shown during any other subsequent accessing of the portal (for a one-year period). A link to Cookie settings will be available (bottom right corner), where the user will be able to change options for the optional types of cookies at any time. After one year, the merchant will be once again prompted with the collect consent for the placed cookies.

Cookie module displayed for merchants in California

For merchants in California, the cookie module will display the Do not sell my information button. Once merchants click on it they will be prompted with the Cookies Management Center window, where they can enable their preferred cookies.

Cookie module displayed for merchants in the Rest of the World, including the US (non-EU, non-California)

Overview

Use the addPromotion method to create a new promotion.

Parameters

Response

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    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.1/';

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.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.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;

$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);

promotionObject = new stdClass;
$promotionObject->Name = 'YOUR_PROMOTION_TITLE';
$promotionObject->Description = 'YOUR_PROMOTION_DESCRIPTION';
$promotionObject->StartDate = date('Y-m-d', strtotime('1 month ago'));
$promotionObject->EndDate = date('Y-m-d', strtotime('+1 month'));
$promotionObject->Type = 'REGULAR';
$promotionObject->Enabled = 1;
$promotionObject->MaximumOrdersNumber = 0;
$promotionObject->MaximumQuantity = 0;
$promotionObject->InstantDiscount = false;
$promotionObject->ChannelType = 'ECOMMERCE';
$promotionObject->ApplyRecurring = 'NONE';
$promotionObject->RecurringChargesNumber = 3;
$promotionObject->PublishToAffiliatesNetwork = 0;
$promotionObject->InstantDiscount = 0;

$couponObject = new stdClass;
$couponObject->Type = 'SINGLE';
$couponObject->Code = 'single_code';
$promotionObject->Coupon = $couponObject;

$discountObj = new stdClass;
$discountObj->Type = 'PERCENT';
$discountObj->Value = 30;
$promotionObject->Discount = $discountObj;
$promotionObject->Products = [$productsObj1, $productsObj2, $productsObj3];
$promotionObject->Translations = [$translation1, $translation2];

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

$result = callRPC((object)$jsonRpcRequest, $host);
var_dump($result);

Overview

Use the login method for the authentication process in the 2Checkout system.

Parameters

Response

Request

To create the HMAC_SHA256 source string use your merchant code (available here) and the date of the request, prefixing them with the length in bytes of each respective value, along with your account’s secret key (for UTF-8 characters the length in bytes might be longer that the string length). For example:

Request example

<?php

$host   = "https://api.2checkout.com";

$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'); //GMT date format)
$algo = "sha256";
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash = hash_hmac($algo, $string, $key);

try {
    $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
            )
        ))
    ));
    $sessionID = $client->login($merchantCode, $now, $hash, $algo);
    echo("Auth token: {$sessionID}" . PHP_EOL);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage() . PHP_EOL;
    exit;
}

Overview

Use the markLeads method to mark a lead as used and/or stop follow-ups.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$markLead = [
    'LeadCode' => '60E6C4B574',
    'StopFollowups' => false,
    'Used' => true
];

$jsonRpcRequest = array (
    'method' => 'markLeads',
    'params' => array($sessionID, [$markLead]),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response Parameters

Response Example

class stdClass#18 (2) {
  public $Response =>
  string(37) "1 leads have been marked successfully"
  public $Errors =>
  array(0) {
  }
}

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// 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 = [''];

$promotionProducts = [$newProduct1, $newProduct2];

try {
    $updatedPromotion = $client->deletePromotionProducts ($promotionCode, $promotionProducts);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

This is a summary of the objects/classes and methods available.

Overview

Use the updateSubscriptionUsage method via SOAP API 6.0 to update a specific usage entry.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$subscriptionReference = '4A1D733696';
$usageReference = 120010776516;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->Units = 123;
    $subscriptionUsageRequest->Description = 'Units 123';
    $response = $client->updateSubscriptionUsage($sessionID, $subscriptionReference, $usageReference, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;

Response 

The updateSubscriptionUsage method via SOAP APIv6 returns the Usage object if successful.

class stdClass#3 (8) {
      public $UsageReference =>
      120011112631
      public $SubscriptionReference =>
      "67F3AD6A32"
      public $OptionCode =>
      "USG_MN"
      public $UsageStart =>
      "2020-07-06 12:00:00"
      public $UsageEnd =>
      "2020-07-07 12:00:00"
      public $Units =>
      69
      public $Description =>
      ""
      public $RenewalOrderReference =>
      0
    }

Error Handling

If unsuccessful, the updateSubscriptionUsage method via SOAP APIv6 will return the error below.