Overview

Retrieve information and manage subscriptions for your account. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Object parameters

Overview

When placing an order on behalf of your partners, you can purchase new products in addition to upgrades and subscription renewals.

Requirements

• It's mandatory to associate products to price lists. Do this by connecting a single or multiple pricing configurations of the items you sell through 2Checkout with a price list. You also have to assign price lists to the partners that you want to be able to access your offerings. Products that are not part of price lists assigned to partners will not be available for purchase.
• The new purchase option is only available for active subscriptions/licenses, and not for disabled products.

Place new partner orders

1. Go to Orders & customers -> Place partner order.
2. Select the partner for which you're placing the order, either by typing the name in the Select partner box, or by using the drop down menu available. Alternatively, provided that you already placed orders on behalf of your partners, a list of Last used partners will be available in this area, and clicking on a name will automatically select it.
3. You'll now get the possibility to order a new license, a renewal or an upgrade.
4. Select the desired price list under the New license area.
5. On the next page, choose the product for your order from the drop down menu. You will now be able to customize your order using values such as quantity, and additional settings (if available). Once finished, click the Add to cart button.
6. Click Add more products to be redirected to the Edit Order screen where you can select additional products from the same pricing list as the last added to chart.
7. Click the Change link to add products from different pricing lists.
8. Click Add to cart.
9. When you place orders on behalf of your partners, their value will automatically be deducted from the amount of available credit you awarded them with, provided that you configured a Credit limit for partner accounts.
10. View Shopping Cart - You can now introduce an External Reference No. / PO, remove some or all items in the cart, change quantity details, add more products, and even leave a comment for the order that your partners will be able to read, by editing orders that haven't been placed. The Comments field supports direct communication with your partner. Any comments added will become part of the order information once you hit the Place order button. If the partner posts a reply, then a new comment is added and will be available in this area. Additional comments can be introduced by editing orders once they have been placed. Make sure to also enter a value for the External Reference No. / PO, if you want your order to have one. The parameter you introduce in this field will be visible both to you and to the partner, and synchronized across both Control Panels.
11. Add extra margin / discount: To edit the discount details of a partner order you need to select Order search in the left hand side pane of the Vendor Control Panel, click on Partner orders and filter existing items to show only those with the Pending approval status. You can always also just search for a partner order, if you have specific details on hand. Once you identified the order you'd like to refresh, click View and then Edit Order. Additional information is available here.
12. Attach end user information - Please read Require end user information for partner (reseller) orders for guidance and Require end user information before placing the order for the steps detailing the process.
13. Place Order - click on the Place Order button once all the details of your order are finalized.
14. Order confirmation - orders placed by you on the behalf of your partners are approved automatically.
15. Attach end user information - Please read Require end user information for partner (reseller) orders for guidance and Require end user information after placing the order for the steps detailing the process.
16. Partners have to provide the necessary details to push the order to the delivery/fulfillment stage, but you can also provide the details if you have them.
    
    • Alternatively, fulfillment be done exclusively to partners, leaving them to deal with their customers, and in this case, no additional info is required.
    • When the system configuration is set to distribute products/keys to end users, customers are required to first register ahead of delivery/fulfillment.
17. Attach reseller information - You'll need to provide reseller information for the order to move to the delivery/fulfillment stage, if the reseller information is required according to the Partner's commercial settings. Partners are required to enter the necessary information to push the order to the delivery/fulfillment stage, but you can also provide the details if you have them.
18. You can view and search through the full list of your partner resellers by clicking the View partner resellers button at the bottom of the Partners page.
19. Partner invoices - Partner invoices can be generated manually or automatically, depending on partner account settings. If the order is placed without any available credit, or your partners do not enjoy a credit limit, they will first need to pay the partner invoice and only then will the process advance to the delivery/fulfillment stage. To manually issue a partner invoice, navigate to Partner partner invoices under Orders & customers.
20. Click on the item in the list of available orders on the left hand side of the page to add them to the partner invoice you're generating, and click Preview.
21. Hit Save to create the partner partner invoice. On the next screen you'll have the option to notify your partner of the newly generated partner invoice or to cancel it if necessary.
22. Delivery/fulfillment. When delivery/fulfillment is handled by 2Checkout, not required or has been confirmed by you, the system will give green light to deliveries immediately for order that are paid in full or placed within available credit. Fulfillment for partner orders guidance is available here.
23. Cancelling an order: To cancel an order make your way to Partner orders under Order search and identify the item you'd like to call off. Click to view the order, and get access to the Cancel button on the next screen. Cancelling orders automatically disables all associated licenses.

FAQ

• Can I edit pricing details for placed orders?

Yes. If no partner was generated then you'll be able to add extra margin and to increase the discount. When the partner was already issued you'll need to first cancel it to edit the order's extra margin and discount.

• How is the upgrade price calculated?

The upgrade price is calculated according to the upgrade settings and then applied to the upgrade promotion on the resulted price.

• How is the price calculated when applying an extra promotion?

Applying an extra promotion to the final price of a product in the Channel Manager shopping cart will discount the price further.

• What happens when you add extra margin?

Adding extra margin means that a particular partner will benefit from an extra discount applied to an order. The extra margin can be cumulated with an extra discount.

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


?>