Overview

Use the createUpSellCampaign method to create an upsell campaign via JSON-RPC API 6.0.

Request parameters

Response parameters

Request sample

<?php
require ('PATH_TO_AUTH');

$upsell = new \stdClass();

$upsell->Name = 'December 2020 upsell campaign’;
$upsell->StartDate = '2020-12-21';
$upsell->EndDate = '2020-12-25';
$upsell->DisplayForManualRenewals = false;

// setup percent discount
$discountPercent = new \stdClass();
$discountPercent->Type = 'PERCENT';
$discountPercent->Value = 5;

// setup fixed discount
$discountFixed = new \stdClass();
$discountFixed->Type = 'FIXED';
$discountValues = [
    'USD' => 10,
    'EUR' => 8,
    'TRY' => 80,
    'RUB' => 1100,
];
$dv = [];
foreach ($discountValues as $curr => $amt) {
    $disc = new \stdClass();
    $disc->Currency = $curr;
    $disc->Amount = $amt;

    $dv[] = $disc;
}
$discountFixed->Values = $dv;

// assign discount
$upsell->Discount = $discountPercent;
# OR
# $upsell->Discount = $discountFixed;


// setup primary product
$primaryProduct = new \stdClass();
$primaryProduct->Code = $productCode;
$primaryProduct->Quantity = 1;
$ppPriceOptionGroup1 = new \stdClass();
$ppPriceOptionGroup1->Code = 'OPTGRP2';
$ppPriceOptionGroup1Option = new \stdClass();
$ppPriceOptionGroup1Option->Code = 'OptGrp2Code2';
$ppPriceOptionGroup1->Options = [$ppPriceOptionGroup1Option];

$ppPriceOptionGroup2 = new \stdClass();
$ppPriceOptionGroup2->Code = 'interval_scale_grp1';
$ppPriceOptionGroup2Option = new \stdClass();
$ppPriceOptionGroup2Option->Code = 'interval_scale_grp1-1-10';
$ppPriceOptionGroup2Option->Value = '6';
$ppPriceOptionGroup2->Options = [$ppPriceOptionGroup2Option];

$primaryProduct->PriceOptions = [$ppPriceOptionGroup1, $ppPriceOptionGroup2];
$upsell->PrimaryProduct = $primaryProduct;

// setup recommended product
$recommProduct = new \stdClass();
$recommProduct->Code = $recProductCode;
$recommProduct->Quantity = 0; // stands for “match quantity” 
$rpPriceOptionGroup1 = new \stdClass();
$rpPriceOptionGroup1->Code = 'CHECKB_LIST';
$rpPriceOptionGroup1Option1 = new \stdClass();
$rpPriceOptionGroup1Option1->Code = 'chk1';
$rpPriceOptionGroup1Option2 = new \stdClass();
$rpPriceOptionGroup1Option2->Code = 'chk3';
$rpPriceOptionGroup1->Options = [$rpPriceOptionGroup1Option1, $rpPriceOptionGroup1Option2];
$recommProduct->PriceOptions = [$rpPriceOptionGroup1];
$upsell->RecommendedProduct = $recommProduct;

$upsell->Enabled = true;

// setup languagte descriptions / texts
$enDescription = new \stdClass();
$enDescription->Language = 'EN';
$enDescription->Text = 'Buy <!--{RECOMMENDED_PRODUCT_NAME}--> for just <!--{RECOMMENDED_PRODUCT_PRICE}--> until Dec 25th';
$upsell->Description = [$enDescription];

$jsonRpcRequest = new \stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'createUpsellCampaign';
$jsonRpcRequest->params = [$sessionID, $upsell];
$jsonRpcRequest->id = $i++;

$upsellResponse = callRPC($jsonRpcRequest, $host);

Overview

You can generate links for dynamic products outside the Merchant Control Panel, using the ConvertPlus parameters explained in this article. Some of the ConvertPlus buy-link parameters require a signature, to prevent any interference in the ordering process. Optional parameters also require a signature if they are included in the generated buy-link.

ConvertPlus parameters that require a signature

ConvertPlus parameters to be included in the signature - general rules

1. General parameters included in the signature, regardless of the type of checkout (catalog products, dynamic products, renewal, unfinished payment): return-url, return-type, expiration, order-ext-ref, customer-ref, customer-ext-ref.
2. Parameters to be included in the signature for dynamic products buy-links: currency, prod, price, qty, type, opt, description, recurrence, duration, renewal-price,  item-ext-ref.
3. Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
4. Parameters to be included for on-the-fly pricing for catalog products: prod, price, qty, opt, coupon.
5. The parameter to be included in order to lock the cart for catalog products: lock.
6. Parameters to be included when an approved URL is set: in this case, all parameters will be included in the signature, when redirected after successful completion of a sale.

Build the ConvertPlus signature

To sign a ConvertPlus buy-link, you need to follow these steps:

1. Sort the parameters that require a signature alphabetically.
2. Serialize the parameters and append to them the length of their values.
3. Concatenate the resulting values.
4. The serialized value is then encrypted with your Buy Link Secret Word using the HMAC method (algorithm sha256).
5. The resulting value is added to the buy link under the signature parameter

Example

Let's consider the following parameters:

•     merchant = 'MCODE'
•     dynamic = '1'
•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

The regular buy-link will have the following structure:

https://www.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10currency=USD&qty=1&type=digital&expiration=1893456000 

This link is missing one last parameter, a signature.

Let's take a look at the list of parameters that require a signature:

•     merchant = '2COLRNC'
•     dynamic = '1'
•     prod = 'Software' <-- SIGNATURE REQUIRED
•     price = 10        <-- SIGNATURE REQUIRED
•     currency = 'USD'        <-- SIGNATURE REQUIRED
•     qty = 1             <-- SIGNATURE REQUIRED
•     type = 'digital'         <-- SIGNATURE REQUIRED
•     expiration = '1893456000' <-- SIGNATURE REQUIRED

We extract only those parameters:

•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

Sort the parameters alphabetically

•     currency = 'USD'
•     expiration = 1893456000
•     price = 10
•     prod = 'Software'
•     qty = 1
•     type = 'digital'

Serialize the values

To serialize a value, you need to prepend to it the number of letters or digits a value has. For example, the currency parameter has the 'USD' value that will be serialized as '3USD', where 3 is the number of letters that make up the value. The value of the price parameter is '10', so the serialized value will be '210', where 2 is the number of digits that make up the value.

In case a value uses special characters, to serialize it, you need to prepend to it the number of bytes in the string, also known as the UTF-8 string length. To count the bytes in the string, you can use an online bytes counter. For example, if the prod parameter has the 'ελληνικά' value, this will be serialized as '16ελληνικά' and not as '8ελληνικά', due to the use of special characters, where '16' is the number of bytes in the string.

•     currency = '3USD'
•     expiration = 101893456000  
•     price = 210
•     prod = '8Software'
•     qty = 11
•     type = '7digital'

Concatenate the values

    '3USD1018934560002108Software117digital'

Encrypt using your Secret Word

The serialized value is then encrypted using the HMAC method.

    - the algorithm used is sha256

    - the key used when encrypting is the merchant secret word (in this example, the secret word is 'secret_wordbuylink')

This outputs a 64 character string:

c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762

Add the string in the buy-link

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10&currency=USD&qty=1&type=digital&expiration=1893456000&signature=c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762

Overview

Use the setSubscriptionGracePeriod method to set a custom grace period for an Active or Past Due subscription. This method changes per-subscription end user data and not customer details.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$gracePeriod = YOUR_GRACE_PERIOD;

$jsonRpcRequest = array (
'method' => 'setSubscriptionGracePeriod',
'params' => array($sessionID, $subscriptionReference, $gracePeriod),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Use the getAdditionalOrderFields method to extract information about additional fields you set up for your account.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

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

?>

Response

Prevent Payment Failures

Intelligent Payment Routing enables you to match or route card transactions to the payment gateways best equipped to handle them and retry authorizations using a failover or back-up gateway. We recommend taking advantage of this feature to:

• Provide automatic support for switching and optimization between multiple payment processors around the world.
• Increase conversion rates.
• Reduce the volume of unfinished payments.
• Shift riskier transactions to secondary gateways to protect relationships with primary providers.

Analyzing a sample of 2Checkout vendors, we have seen an average uplift between 2% and 5% in their authorization rates using this fallback system.

An equally important aspect is routing transactions to local payment processors in countries such as the USA, Brazil or Turkey.

After using local payment processing, many of our vendors have seen up to 40% increase in authorization rates in the aforementioned markets.

Ensure Billing Continuity

The best way to handle the incoming wave of account number changes is to use an Account Updater.

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 exchange updated credit card account information between participating issuers, acquirers, and merchants.

The programs record 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.
• Requests for information on a set of cards due for their next billing installment.

The 2Checkout Account Updater has so far helped our vendors grow their recurring revenue in multiple ways:

• Salvage over 90% of otherwise unusable cards used for recurring billing.
• Seamlessly update state (out of date) credit/card accounts.
• Increase retention by up to 40%.
• Increase customer loyalty by eliminating service disruption.

Increase Authorization Rates for Expired Cards

Credit cards in your database slip past their expiration date on a monthly basis. The account number hasn't changed, and the subscriber still wants to receive your service, but when you attempt to bill that card, the payment is declined -- or your gateway won't let you submit it at all -- because the card is expired.

2Checkout allows you to identify expired cards and update them on file (standard banking procedures to prolong expiration dates), so that stale expiration dates don't deny you revenues or threaten your relationship with a perfectly happy subscriber. You can retry those payments and recover up to 90% of payments that initially had been declined due to expired cards.

We also recommend you create a report to track each retry attempt and its results. That way, you'll be able to see how many payments you're recovering at each step and notice any changes in the trend.

For instance, adding three years to the date tends to recover a higher percentage of payments now, but in the past adding two years was slightly more successful. The optimal approach is always a moving target, but with good tracking, you'll be able to adapt to the changes.

We’ve seen an average authorization rate uplift of 4% after some of our vendors started taking advantage of this mechanism.

Increase Recovery Rate and Minimize Payment Failures

Configurable Retry Logic enables you to automatically recover payments for soft card declines. Soft declines refer to temporary issues, with a high probability that a subsequent try would be successful.

We recommend that you adapt the number of retries and retention strategy to your business and customer base, and we can provide guidance on optimizing conversion rates.

Soft decline reasons include:

• Insufficient funds
• Card activity limit exceeded
• Processing failures due to system, technical or infrastructure issues
• Expired cards

2Checkout’s Retry Logic proved to successfully recover up to 20% of failed transactions due to soft declines.

More extreme situations may result in hard declines, due to stolen/lost cards and/or invalid card data. We no longer attempt authorizations for subscriptions for which the initial card charge results in a hard decline. Unless you target those customers with your own retention strategies, such subscriptions expire.

Reduce Churn and Recapture Revenue

Use our Authorization and Revenue Recovery Dashboard to monitor the impact of your recovery strategies and use the insight to adjust and optimize your tactics to reduce churn and recapture more revenue.

• Gain unmatched transparency and visibility into subscription renewals and recurring billing.
• Access extensive authorization data to optimize retention strategies.
• Gain granular-level insight at the subscription level into the activities of the Retry Logic and Account Updater tools.
• Take advantage of data portability to support third-party marketing and retention campaigns.

Around 16% of successful automatic renewals registered by 2Checkout are currently recovered through our auto-renewal enrollment and churn prevention campaigns.

Recover Revenue from Unfinished Payments

Dunning is the process of methodically communicating with customers to ensure the collection of accounts receivable. Our dunning management tools help you reduce customer churn and recover lost revenue from failed authorizations. We notify customers via email about failed renewals, helping them update their payment information in myAccount.

We automatically attempt to authorize a recurring charge for a subscription according to its renewal deadline. If the authorization process fails with a hard decline - a permanent error from the payment processor/gateway indicating that any further authorizations would also be unsuccessful – then the dunning management tools come into play.

We send a single dunning management email immediately after each failed automatic authorization attempt made for subscriptions with the auto-renewal system enabled. As soon as the shoppers update their payment information, we automatically attempt to authorize the payment and renew the subscription.

2Checkout’s dunning management tools led to an average of 1% increase in authorization rates.

Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference

$jsonRpcRequest = array (
'method' => 'getCustomerInformation',
'params' => array($sessionID, $customerReference, $externalCustomerReference),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Use setPromotionDiscount to set a fixed promotion discount.

Parameters

Response

Request

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'setPromotionDiscount';
    public const ADDITIONAL_OPTIONS = null;
    public const PROMOTION_CODE = "AB3WMME0UA";
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "Type": "FIXED",
  "DefaultCurrency": "USD",
  "Values": [
    {
        "Currency": "USD",
        "Amount": 10
    },
    {
        "Currency": "EUR",
        "Amount": 10
    }
  ]
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION,
        string $promotionCode = Configuration::PROMOTION_CODE
    ): ?object {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $promotionCode, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url.'?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Set LCN triggers and contents 

In your Control Panel account, navigate to Dashboard → Integrations → Webhooks and API and click on the LCN Settings tab. In the General LCN Settings section, under Triggers, select the events for which 2Checkout sends notifications.

License Change Notification (LCN) provides automatic notifications for orders from the 2Checkout system, based on the below list of triggers you control.

LCN Triggers 

Here's a list of the events for which you can trigger notifications. from Control Panel. You can set the triggers (when the notification will be sent) and what tags (parameters) will be included in the response from Control Panel. Find further information on LCN parameters here.

LCN triggers - API calls