Overview

Stock keeping unit or SKU is a number assigned to a particular product by a digital or physical retail store for easy identification and inventory tracking purposes. The SKU number is a string of alphanumeric characters that uniquely identify details such as price, product options and manufacturer of a particular product or service. SKUs are used in order notifications, electronic delivery, export files, etc.

SKU Management

For companies that manage large product catalogs with defined SKUs and that make regular changes to their prices and products (new versions, new options), the manual process performed in the Merchant Control Panel needs to be supported by an automatic solution as well. By using an automated flow, merchants decrease the time needed for this process, and also reduce the risk of human errors associated with the manual process.

In the 2Checkout platform, SKUs can be associated with a unique combination made up of:

• Product identification element
• Pricing configuration
• Plus minimum one of the following:
  • Currency – defined as applicable to all currencies or only to specific ones
  • Volume Discounts – defined as specific quantity or intervals (applicable only according to the volume discounts that are defined at pricing configuration level)
  • Purchase Types – possible values: new purchase, renewal, upgrade and trial
  • Pricing Options – will be available considering the pricing option groups assigned to the selected pricing configuration

Overview

The object below is returned directly or within a successful response from the following API requests:

Retrieve a subscription                              Search subscriptions

Retrieve customer's subscriptions          Retrieve specific subscriptions

Subscription object

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 than the string length). For example:

Request Example 

<?php

/**
 * @throws JsonException
 */
function callRPC($Request, $hostUrl)
{
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json', 'Accept: application/json']);
    $RequestString = json_encode($Request, JSON_THROW_ON_ERROR);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);

    $ResponseString = curl_exec($curl);

    if (!empty($ResponseString)) {
        $Response = json_decode($ResponseString, false, 512, JSON_THROW_ON_ERROR);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            echo("Method: {$Request->method}" . PHP_EOL);
            echo("Error: {$Request->error}" . PHP_EOL);
        }
    } else {
        return null;
    }

    return null;
}

$host = 'https://api.avangate.com/channel-manager/2.1/rpc/';

$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

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$algo = 'sha256';
$hash = hash_hmac($algo, $string, $key);

$i = 1; // counter for api calls
// call login
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = [$merchantCode, gmdate('Y-m-d H:i:s'), $hash, $algo];
$jsonRpcRequest->id = $i++;

try {
    $sessionID = callRPC($jsonRpcRequest, $host);
    echo("Auth token: {$sessionID}" . PHP_EOL);
} catch (JsonException $e) {
    echo("Error: {$e->getMessage()}" . PHP_EOL);
} 

Errors

Overview

This object is returned directly or within a successful response from the following API requests:

• Retrieve a price option group
• Retrieve assigned price option groups
• Retrieve price option groups

Pricing option group

Overview

Use the updateLead method to update an existing lead and change all current values with new data.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$Lead = new stdClass();

$Lead->CartId = "CartIdValue";
$Lead->Currency = "EUR";
$Lead->Language = "BG";
$Lead->ExternalReference = "REST_API_3CHECKOUT";
$Lead->Source = "testAPI.com";
$Lead->CustomerReference = "asdf1";
$Lead->MachineId = "123asd";

$Lead->Items = [];

$Item = new stdClass();
$Item->Code = "04C26C50F8";
$Item->Quantity = 2;
$Item->IsDynamic = false;
$Item->Tangible = true;
$Item->PurchaseType = "PRODUCT";
$Item->PriceOptions = [];

$priceOption = new stdClass();
$priceOption->Name = "group name 1";
$priceOption->Required = false;
$option = new stdClass();
$option->Name = 'add25';
$option->Value = 'add25';
$option->Surcharge = 100;
$priceOption->Options[] = $option;

$Item->PriceOptions[] = $priceOption;

$recurringOptions = new stdClass();
$recurringOptions->CycleLength = 6;
$recurringOptions->CycleUnit = 'MONTH';
$recurringOptions->CycleAmount = 100;
$recurringOptions->ContractLength = 2;
$recurringOptions->ContractUnit = 'YEAR';
$Item->RecurringOptions = $recurringOptions;

$marketingCampaigns = new stdClass();
$marketingCampaigns->Type = 23;
$marketingCampaigns->ParentCode = "m";
$marketingCampaigns->CampaignCode = 23;
$Item->MarketingCampaigns = $marketingCampaigns;

$Item->Price = new stdClass();
$Item->Price->Amount = 20;
$Item->Price->Type = "CUSTOM";

$additionalFields = [];

$additionalField = new stdClass();
$additionalField->Code = "TestFieldOne";
$additionalField->Text = "test text";
$additionalField->Value = "test value";
$additionalFields[] = $additionalField;
$Item->AdditionalFields = $additionalFields;

$Item->SubscriptionStartDate = date("Y-m-d H:i:s");

$Lead->Items[] = $Item;

$billingDetails = new stdClass();
$billingDetails->FirstName = "Customer";
$billingDetails->LastName = "2Checkout";
$billingDetails->Phone = null;
$billingDetails->Company = null;
$billingDetails->FiscalCode = "32423423";
$billingDetails->Email = "customer@2checkout.com";
$billingDetails->Address1 = "Test Address";
$billingDetails->Address2 = null;
$billingDetails->City = "LA";
$billingDetails->Zip = "12345";
$billingDetails->CountryCode = "RO";
$billingDetails->State = "CA";

$Lead->BillingDetails = $billingDetails;
$Lead->DeliveryDetails = clone($billingDetails);

$Lead->DeliveryInformation = new stdClass();
$Lead->DeliveryInformation->ShippingMethod = new stdClass();
$Lead->DeliveryInformation->ShippingMethod->Code = "sdfsd";

$Lead->PaymentDetails = new stdClass();
$Lead->PaymentDetails->Type = "CC";
$Lead->PaymentDetails->Currency = "EUR";
$Lead->PaymentDetails->PaymentMethod = new stdClass();
$Lead->PaymentDetails->PaymentMethod->RecurringEnabled = false;
$Lead->PaymentDetails->PaymentMethod->CardPayment = new stdClass();
$Lead->PaymentDetails->PaymentMethod->CardPayment->InstallmentsNumber = 23;
$Lead->PaymentDetails->CustomerIP = "1.2.3.4";

$Lead->LocalTime = date("Y-m-d H:i:s");

try {
    $leadData = $client->updateLead($sessionID, $Lead);
} catch (SoapFault $e) {
    echo "updateLead: " . $e->getMessage();
    exit;
}

var_dump("updateLead", $leadData);

Response Example

class stdClass#18 (4) {
  public $LeadCode =>
  string(10) "60E6C4B574"
  public $CreatedAt =>
  string(19) "2019-11-05T16:39:36"
  public $UpdatedAt =>
  string(19) "2019-11-05T16:48:31"
  public $Errors =>
  array(0) {
  }
}

Overview

Use this object to retrieve information about additional order/product fields.

Parameters

Overview

Use this section to handle the management of your subscriptions.

You can enable or disable your existing subscription, or choose to assign them to different customer entities.

Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Overview

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

Parameters

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;
}

$Prices                     = array();
$Prices[0]                  = new stdClass();
$Prices[0]->Currency        = 'USD';
$Prices[0]->Amount          = 999.99;
$Prices[1]                  = new stdClass();
$Prices[1]->Currency        = 'EUR';
$Prices[1]->Amount          = 111.99;
$Quantities                 = new stdClass();
$Quantities->MinQuantity    = 1;
$Quantities->MaxQuantity    = 99999;
$PriceOptions               = null;
/*
$PriceOptions = array();
$PriceOptions[0] = new stdClass();
$PriceOptions[0]->Code = '04WCPNHWQ5';
$PriceOptions[0]->Options = array();
$PriceOptions[0]->Options[0] = 'loqmhwcpwk';
$PriceOptions[0]->Options[1] = 'n7332ux312';
$PriceOptions[1] = new stdClass();
$PriceOptions[1]->Code = '4CU1OVAGAA';
$PriceOptions[1]->Options = array();
$PriceOptions[1]->Options[0] = 'dvk7hv62jg';
$PriceOptions[1]->Options[1] = 'uf1svzaxcd';
*/
$PricingConfig              = new stdClass();
$PricingConfig->ProductCode = 'NewSubscriptionPlan_Code_12345';
$PricingConfig->Country     = null;
$type                       = 'REGULAR';

try {
    $NewPrice = $client->savePrices($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfig, $type);
}

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

var_dump("NewPrice", $NewPrice);


?>

Overview

2Checkout automatically sends out the Invoice email to business customers providing full details on their purchase and finalized transaction.

As of August 31, 2016, you can use a redesigned template complete with fresh content (sample below). The new template has replaced the previous Invoice email, but any customization you have in place, either in terms of styling or content, continues to be available.

Availability

All 2Checkout accounts.

What is the purpose of this email?

2Checkout sends out this email to provide business customers with the invoice in PDF format.

Email content

The email includes the following:

1. Card statement details.
2. PDF with the invoice.
3. Order details including reference, payment method, and total transaction value.

Sample

Preview and test email

Navigate to the Email template manager section to:

• Preview and test current templates for emails sent to your shoppers
• Customize the header and the footer sections by creating custom templates you can assign to your emails

Access the Invoice email under the Order section.

Why don't I see the new template for this email?

The redesigned template for the Invoice email has automatically replaced default templates.

If your preview of Invoice email does not show the new template, you are most probably using a customized version that includes content and/or styling your company requested at a certain point in time.

You can compare the above sample to your current template and send us an email if you decide the new one suits your business needs better. We will work with you on the switch.

Overview

Customize the out-of-the-box shopping cart templates offered by 2Checkout and create completely personalized designs of the interface your customers use during their purchase.

Saved template customizations have an immediate effect on the shopping cart design.  When clearing the cache/cookies of the current session, even if an interface template is assigned, it is possible that the default cart will load.

Availability

All 2Checkout accounts.

How to add a cart/checkout template

1. Log into your Merchant Control Panel.
2. Go to Setup → Interface templates.
3. Scroll down to the Template Gallery and click Add to drafts on the template that you want to use.

Customize a cart/checkout template

1. Identify the cart template you want to customize from those added to the Draft templates area.
2. Click Edit. 
3. After implementing your changes, you can preview your new customized cart template.

Template localization

By default, the English template is used for all languages if you did not define any localized templates. You can change this in two ways:

1. Click the links available for each language and add/edit the template for that specific language.
2. Check the checkboxes next to the languages you want to save a copy of the default template for. Subsequently, you can click on each language and edit the specific copy of the default template for that language as a standalone item.

Use a custom template on a different website

If you generate sales from a different website and you want to include that address in the emails the 2Checkout system sends to the shoppers, enable the Define the URL to be included in the notifications to customers as the sale source option and enter the address of the website in the dedicated field.

External JavaScript and CSS files

As an alternative to using 2Checkout’s templates, you can add your own JavaScript and CSS files to fully customize your customers’ experience. Keep in mind, though, that changing these files is an advanced operation best handled by experienced programmers.

To change the external JavaScript and CSS files, go to Media Center and upload your files. 2Checkout will automatically merge the files with the built-in interface files. Unless you upload your custom CSS and JS files to a secure 2Checkout server, 2Checkout cannot establish a secure connection (SSL) for your customers.

You can upload one or more CSS and JavaScript files according to your needs. When you upload multiple CSS or JS files, the last ones added will take precedence over previous ones. Custom CSS and JS files override the default ones. 2Checkout recommends that you use only a single .CSS file and a single .JS file in order to optimize page load time.

Once you upload the CSS and JS files, you can see them in the External JavaScript and CSS files section of the custom template Edit page. You can also implement full or partial advanced personalization by using custom templates.

HEAD Information

In addition to customizing the CSS and JS files, you can also edit the following:

• Doctype declaration
• Page title
• META & CSS
• HTML code
• JavaScript code

Click Save after you’re done making inline changes

Scroll down to the bottom of the page and click the Save button. The Save with comments button is designed to allow you to add observations to a custom template.

BODY Information

The BODY Information section allows you to modify the HTML code for the body of the page as well as the JavaScript code.

Click Save after you’re done making changes