Overview

Restrict API calls based on request IP address and increase the security of your account by preventing unauthorized API usage. By default, you can call the 2Checkout API from any IP.

Currently, the 2Checkout systems do not support IPv6 for customer IP.

Availability

All 2Checkout accounts.

Set up

1. Navigate to  Settings » Users » Firewall.
2. Specify a static IP address or a range of IP addresses. 
3. In the Selected Users area, apply the restriction to API (Special). 
4. Add the IP filter. 
5. Activate the IP filtering system.

Overview

Set a grace period for your products and enable customers to renew expired subscriptions for a specific number of days after the expiration deadline. For example, for a 7 day grace period, 2Checkout will still accept payments and customers can still renew their subscriptions for up to a week after their subscriptions have expired. The expiration date of a recurring subscription is calculated based on a 'last day of the month' principle. For a subscription that is recurring on a monthly basis, and starts on January 31st, the subscription will expire as follows: in February, this subscription will expire on February 28th (or 29th for leap years). In March, the subscription will expire on the 31st.

Impact

Grace period settings impact subscriptions generated with every sale and are used as attributes of these subscriptions throughout their lifecycle.

Grace period configuration

2Checkout allows you to configure subscription grace period for multiple scenarios.

Account-level grace period

1. Go to Setup -> Renewal -> Global Renewal Settings.
2. Define the grace period length.
3. Click Save.

Apply the global grace period settings to existing subscriptions

1. Go to Setup -> Renewal -> Global Renewal Settings.
2. Define the grace period length.
3. Apply the settings to different types of existing subscriptions:
   
   • Expired (will apply the new settings to subscriptions for the product you're editing sold to your customers that expired - the number of expired subscriptions impacted is enclosed in parenthesis).
   • Past due (will apply the new settings to subscriptions for the product you're editing sold to your customers that are currently in the grace period - the number of subscriptions in their grace period impacted is enclosed in parenthesis).
   • Active (will apply the new settings to subscriptions for the product you're editing sold to your customers that are still active -  the number of active subscriptions impacted is enclosed in parenthesis).
4. Click Save.

Product-level grace period

1. Go to Setup -> Products.
2. Click Edit on the product that you want to configure the grace period for.
3. Go to the Renewal tab and select the Set custom grace period for this product option.
4. Define the grace period length.
5. Click Save.

Overwrite product-level grace period for existing subscriptions

Subscription sold for products with product-level grace period settings inherit the custom renewal configurations and not the global renewal setup.

1. Go to Setup -> Renewal -> Global Renewal Settings.
2. Define the grace period length.
3. Apply the settings to different types of existing subscriptions:
   
   • Expired (will apply the new settings to subscriptions for the product you're editing sold to your customers that expired - the number of expired subscriptions impacted is enclosed in parenthesis).
   • Past due (will apply the new settings to subscriptions for the product you're editing sold to your customers that are currently in the grace period - the number of subscriptions in their grace period impacted is enclosed in parenthesis).
   • Active (will apply the new settings to subscriptions for the product you're editing sold to your customers that are still active -  the number of active subscriptions impacted is enclosed in parenthesis).
4. Check the Apply to subscriptions with grace periods set at product-level option. This overwrites only the inherited grace period for existing subscriptions and not the custom grace period settings set at product-level.
5. Click Save.

Usage scenarios

Prolonging the grace period for expired subscriptions

1. The interval increase doesn't push the grace period beyond the current date when the change is operated. As a result, expired subscriptions will maintain their Expired status.
   

   Subscription 1
   Recurring billing	1 month
   Lifecycle	May 1 - May31
   Grace period	5 days
   Current date	June 12
   Current status	Expired
   Update grace period to	7 days
   Impact on subscription	New 7 day long grace period
   Impact on status	None
   Comment	Because the prolonged grace period doesn't include the current date when the change is operated, the status of the subscription remains unchanged, in this case, Expired.

2. The interval increase pushes the grace period beyond the current date when the change is operated. As a result, expired subscriptions will re-enter their grace period (Past Due status) allowing customers to renew them through manual payments.
   

   Subscription 1
   Recurring billing	1 month
   Lifecycle	May 1 - May31
   Grace period	5 days
   Current date	June 12
   Current status	Expired
   Update grace period to	14 days
   Impact on subscription	New 14 day long grace period and subscription is returned to its grace period
   Impact on status	Switched from Expired to Past Due
   Comment	Because the prolonged grace period includes the current date when the change is operated, the status of the subscription is changed from Expired to Past Due. Customers will now be able to once again renew their subscriptions through manual payments (buy links previously sent in manual renewal email notification will work as the status is changed).

Prolonging the grace period for Past Due subscriptions

1. The interval change doesn't reduce the grace period to a previous date compared to the current date when the change is operated. As a result, subscriptions in their grace period will maintain their Past Due status.
   

   Subscription 2
   Recurring billing	1 month
   Lifecycle	May 1 - May31
   Grace period	14 days
   Current date	June 12
   Current status	Past Due
   Update grace period to	13 days
   Impact on subscription	New 13 day long grace period
   Impact on status	None
   Comment	Because the update doesn't shorten the grace period to an interval preceding the current date when the change is operated, the status of the subscription remains unchanged, in this case, Past Due.

2. The interval change reduces the grace period to a previous date compared to the current date when the change is operated. As a result, subscriptions in their grace period will expire.
   

   Subscription 1
   Recurring billing	1 month
   Lifecycle	May 1 - May31
   Grace period	14 days
   Current date	June 12
   Current status	Past Due
   Update grace period to	7 days
   Impact on subscription	New 7 day long grace period and subscription expires
   Impact on status	Switched from Past Due to Expired
   Comment	Because the update shortens the grace period to an interval preceding the current date when the change is operated, the subscription expires, and its status switches from Past Due to Expired.

License Change Notifications (LCN)

When you modify the grace period of subscriptions, the 2Checkout system will automatically send out License Change Notifications (LCNs) reflecting the update you made.

LCN corner cases

1. You set a 1 day grace period for a subscription that's no more than 24 hours after its' expiration deadline and that did not feature a grace period previously. In this case, the 2Checkout system will send out 2 notifications:
   
   • 1 LCN reflecting the grace period change.
   • 1 LCN reflecting the Past Due status of the subscription.
2. You decrease the grace period of a subscription that's less than 24 hours from the grace period deadline by 1 day. In this case, the 2Checkout system will send out 2 notifications:
   
   • 1 LCN reflecting the grace period change.
   • 1 LCN reflecting the expiration of the subscription.

F.A.Q.

1. What happens if the grace period expires?
   
   • 2Checkout will no longer accept payments and customers will not be able to renew their expired subscriptions.
2. Does grace period offer extra usage?
   
   • No. Configuring a grace period for subscriptions does not influence the recurring billing process. Grace periods provide an interval of time, after the expiration of a subscription, in which shoppers can order a renewal. After the grace period, if any, runs out for expired subscriptions, customers will have to purchase a new offering. Expirations deadlines are calculated in accordance to purchase dates and converted to the 2Checkout local time zone.
3. Does 2Checkout send LCNs for grace period updates?
   
   • Yes. 2Checkout sends out LCN notifications for each change you perform per subscription that results in an update of the grace period.

Overview

Use the getOrder method to retrieve details on a specific order using its unique, system generated reference.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/6.0/?wsdl", array(
    'location' => $host . "/soap/6.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 = "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
$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;
}
$orderReference = '43403739';
try {
    $fullOrderDetails = $client->getOrder    ($sessionID, $orderReference);
}
catch (SoapFault $e) {
    echo "fullOrderDetails: " . $e->getMessage();
    exit;
}
var_dump("fullOrderDetails", $fullOrderDetails);
?>

Overview

Use the setRenewalNotificationStatus method to subscribe or unsubscribe shoppers from subscription renewal notifications.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$status = false;

try {
    $Notifications = $client->setRenewalNotificationStatus($sessionID, $subscriptionReference, $status);
}
catch (SoapFault $e) {
    echo "Notifications: " . $e->getMessage();
    exit;
}
var_dump("Notifications", $Notifications);

Overview

If you enable the Requires delivery confirmation option for 2Checkout delivery, the order processing is put on hold until you manually confirm the delivery of the order. 

For orders you fulfill using your own platform or resources (Fulfillment made by you), you need to confirm the delivery of all the products in the orders, to finalize the payment process. Only after you provide fulfillment confirmation will 2Checkout mark orders as completed and update their status to Finished. Fulfillment confirmations can be accomplished either manually or automatically, depending on the fulfillment type and automation level that you implement.

Confirm fulfillment

Confirm fulfillment for each order having the "In progress" status:

• Select the order(s) in the Fulfillment Confirmations section by ticking the corresponding boxes.
• Click Confirm fulfillment.
• You can also send an automatic delivery confirmation, IDN, to 2Checkout in the form of an HTTP POST.

Please note that only after receiving the fulfillment confirmation for the order, 2Checkout can execute the money transfer from the customer's account.

FAQ

1. Are there any restrictions on the characters that can be used in the Static Lists?
   
   • Only printable characters can be used in the static list.
2. What is the format for a static list file?
   
   • Each line in the static list will be considered as one code to be delivered. The newline character can have any style: Windows, Mac or Linux.
3. Can a subscription key/code be presented to the user as two lines by embedding a new line character in the key text? 
   
   • No, embedding a new line character in the key text will make it part of the code to be sent to the customer, thus breaking the desired output. To deliver codes on multiple lines, dynamic lists should be used instead, where more than one line of codes can be sent using the XML schema.

Overview

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

Retrieve subscription history

Subscription history object

Overview

Use the updateProduct method to update the configuration of a subscription plan/product you already configured for your account.

Parameters

When updating a subscription plan/product, you also update its PricingConfigurations. However, you cannot modify:

• The pricing configuration CODE.
• The PricingSchema from DYNAMIC to FLAT or vice versa.

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

$ProductCode = 'NewSubscriptionPlan_Code_12345';

try {
    $ProdbyCode = $client->getProductByCode($sessionID, $ProductCode);
}

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

var_dump("ProductInfo", $ProdbyCode);

$ProdbyCode->ProductName = 'NewSubscriptionPlan_Name_2.0';

try {
    $NewSubscriptionPlan = $client->updateProduct($sessionID, $ProdbyCode);
}

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

var_dump("UpdatedProductInfo", $NewSubscriptionPlan);

?>

Overview

Use the searchProducts method to extract information about the subscription plan/products you configured for your account.

Pagination

Use pagination to decrease the request loading time, while better handling the returning responses.

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$SearchOptions = new stdClass();
$SearchOptions->Name = '2Checkout Subscription'; //Product name
$SearchOptions->Types = array ('REGULAR', 'BUNDLE'); //product type (standalone), regular or bundle
$SearchOptions->Enabled = True;
//$SearchOptions->GroupName = '';
$SearchOptions->Limit = '10';
$SearchOptions->Page = '10';

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

?>

Response

Overview

2Checkout automatically sends out the Follow-up unfinished Instant payment methods email as part of the overall strategy to increase the conversion rate for new purchases. Shoppers receive unfinished payment follow-up messages if they place orders, but 2Checkout cannot successfully complete transactions and collect funds. This notification makes it easy for customers to return to the shopping cart and finalize a purchase without having to go back through the ordering process.

Availability

The lead management set of tools is available for 2Monetize accounts (merchants on the Reseller business model).

Follow-up emails

2Checkout sends out follow-up messages for unfinished payments made using one of the following payment methods:

1. Instant payment methods (Visa/MasterCard/Eurocard, American Express, Diners Club, JCB, PayPal, Discover/Novus, Chinese Debit Card, 支付宝 (Alipay), iDEAL).
2. Online direct debit.

Failed transactions can happen because of various reasons, such as expired cards, insufficient funds, authorization declined, etc.

You can add follow-ups, up to a maximum of 15 notification emails.

Email content

The email includes:

1. Link to the shopping cart for the retry.
2. Alternative payment methods to finalize the purchase.
3. Order, product, and subscription details.

Sample emails

Preview and test the 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 Follow-up unfinished Instant payment methods email under the Follow-Up section.

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

The redesigned template for this email has automatically replaced default templates.

If your preview of the follow-up notification 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.