Overview

Purchase upgrades in addition to new licenses and subscription renewals. The 2Checkout platform enables you to offer partners upgrades to:

• A different subscription/product;
• A newer version of the current subscription/product;
• A distinct licensing option of the same subscription/product.

Requirements

• It's mandatory to associate upgrades to the same price list as the original products (subscriptions/licenses), and to assign them to partners to provide access. Products that are not part of price lists assigned to partners will not be available as upgrade options.
• Upgrades are only available for active subscriptions/licenses. As long as expired licenses/subscriptions are still in their grace period (featuring the Past due status), upgrading them is a valid option.
• When defining the product which will act as the upgrade make sure to also generate a subscription under the Renewal tab. Products can only be upgraded to offerings for which a subscription was generated, when ordering on behalf of your partners. If the upgrade is not a subscription, select none as the Renewal interval. This creates a lifetime license.

Place partner upgrade orders

1. Go to Orders & customers -> Place partner order.
2. Select the partner for which you're ordering upgrades, 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. Select Upgrade to move to the next stage.
4. Search for subscriptions/licenses you want to upgrade. The results returned for the search include only active, upgradable subscriptions/licenses previously purchased by the selected partner. Expired or disabled subscriptions/licenses, as well as those for which you haven't defined an upgrade, will not be listed here. Upgrades need to be ordered individually, one at a time, unlike prolonging subscriptions, where you can bulk renew a number of selected items. The reason for this is the fact that each product subscription/license can have different upgrade options, requiring you to customize each item individually. However, once you add an upgrade to cart, you can continue doing so for more subscriptions/products. You'll be able to add to cart and order as many upgrades as you wish, but you have to do it one by one. The quantity/number of units of the upgrade is locked and cannot be modified, unlike additional options you configured.
5. Editing functionality for upgrade orders involves options such as adding more upgrades, remove added items one by one or all at once, and communicate with your partner through comments. You can even edit the specific details of a subscription/license already added to cart, if you would like to modify the options selected initially, for example.
6. Step 4: Add extra margin/discount options to decrease the cost of an upgrade for your partner. Extra margins and discounts are entirely optional and completely under your control.
   
   • Discount - Apply a discount to the product(s) value in this order. The discount is deducted from the total price of the products before partner margin is applied.
   • Extra margin - Offer an extra margin to your partner only for this order. The extra margin is deducted from the total price of the products after discount and partner margin are applied.
7. Place the order. Hit the Place order button to place an upgrade order once all the details are final.
8. Order confirmation. Orders placed by you on behalf of your partners are confirmed automatically, regardless of the order confirmation settings of the partner account.
9. Attach end user information. For upgrades, the 2Checkout system is designed to copy the end user information attached to the original subscription/license. However, when such data is not available, you'll need to provide it for the order to move to the delivery/fulfillment stage (if they are required according to the Partner commercial settings). 2Checkout needs at least the email address of partners/shoppers to deliver keys for orders that require end user information.
10. Attach reseller information. Reseller information is also copied automatically from the original subscription/licenses as a part of the upgrade process. Similarly, when such data is not available, you'll need to provide it for the order to move to the delivery/fulfillment stage, if the reseller information is required according to that partner's commercial settings.
11. Pay partner invoices. Partner invoices can be generated manually or automatically, depending on your 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 that gets generated automatically when the order is confirmed, and only then will the process advance to the delivery/fulfillment stage. To manually issue a partner invoice, go to Partner invoices under Orders & customers.
12. Click 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.
13. Click 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.
14. 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.

Error messages

Use the variables in the list below to customize the Electronic delivery and payment receipt shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Overview

Perform easy account management via API Requests. The 2Checkout API portfolio contains extended capabilities that can help you automate processes as creating products or promotions, placing orders (both with catalog and dynamic product information), issuing refunds, retrieving the shipping price for an order, handling subscriptions, and many others.

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'MY_PROMO_CODE_1';

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

$productPromotion = [$newProduct1, $newProduct2];

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

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.