Overview

Restrict access to the Merchant Control Panel only for specific IPs or IP ranges and increase the security of your account. By default, 2Checkout account users can access the Merchant Control Panel from any IP.

Availability

All 2Checkout accounts.

How to restrict access to the Merchant Control Panel

1. Log in to your Merchant Control Panel.
2. Navigate to the Settings cogwheel in the upper right corner and click on User Management.

3. On the User Management page, click on the Restrict access tab.

4. On the Restrict access page, click on the Add IP filter button.

5. Specify a static IP address or a range of IP addresses in the iFrame window.

6. Apply the restriction to all or only to selected Merchant Control Panel users. 

7. Click on the Add filter button to save the setting.

8. On the Restrict access page, click on the Activate button to enable the IP filtering system.

Overview

Use the deletePromotionSources method to define new sources for an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to remove sources from
$promotionCode = '';

// Sources array with the source values 
$sources = ['source1', 'source2'];

try {
    $updatedPromotion = $client->deletePromotionSources($promotionCode,$sources);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

Get information about all the pricing lists available to a specific partner and which can be used for a new purchase.

Requirements

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

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

Errors

Overview

Use the getOrder method to retrieve details on a specific order placed with dynamic product information, or catalog products, using the unique, system generated reference.

Parameters

Response

Request 

<?php

require ('PATH_TO_AUTH');

$orderReference = 'YOUR_ORDER_REFERENCE';

$jsonRpcRequest = array (
'method' => 'getOrder',
'params' => array($sessionID, $orderReference),
'id' => $i++,
'jsonrpc' => '2.0'
);

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

Overview

Set up A/B testing scenarios for up-selling campaigns to identify the most efficient up-selling placement.

Requirements & limitations

1. Up-selling placements applied through the UPSELL_DISPLAY_TYPE parameter directly into the URL are not taken into account in the A/B test.
2. You need to activate the up-selling campaigns before you can use them in the A/B tests.

Important

When shoppers places the orders, the test is considered successful regardless of the order or payment status.

Setup

1. Go to the Upselling page and define the upselling campaigns that you want to test.
2. Activate the up-selling campaigns that you want to use in your test.
3. Navigate to the A/B Testing page and click the Campaigns tab.
4. Scroll to the Up-selling campaign placement section and click Edit Campaign on an inactive campaign.If you don't have any existing campaigns, click the Configure new campaign button.
5. Fill in the details of the new campaign, such as the campaign name, maximum number of tests and the date when the campaign should end. Make sure to select the up-selling campaign to run the tests on from the Up-selling campaign drop-down menu.
6. Create a new scenario by selecting an up-selling placement style. You can choose between Interstitial webpage and Overlay window.
7. Click Add Scenario.
8. Repeat steps 6 and 7 until you have used the entire available traffic.
9. Click Save campaign.
10. Go back to the Campaigns tab and click Start Campaign when you want the campaign to begin.

What up-selling campaigns are being used in my A/B tests?

When you open an up-selling campaign's configuration page, a notification informs you if the campaign is being used in an A/B test at that moment.

Overview

Pay a partner invoice that was set using setProforma. Works in conjunction with setProforma and setPaymentDetails. Call setProforma, then setPaymentDetails and payProforma in this specific order to pay for a partner invoice.

Requirements

This method requires that a specific partner be set using setPartner.

You also need to use setProforma to mark a partner invoice for payment, and specify the payment method with setPaymentDetails.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner
require ('PATH_TO_setProforma'); // setProforma example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/14Billing/00Capture_card_payment/00Set_partner_invoice
require ('PATH_TO_setPaymentDetails'); // setPaymentDetails example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/14Billing/00Capture_card_payment/02Set_partner_invoice_payment_details

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

Errors

Overview

Retrieve the account balance from your current payout period, detailed for each billing currency.

You can also search for the historical transfers issued by 2Checkout for your account, and filter the results based on payment date, method or invoice paid.

Overview

Use the addPromotion method via JSON-RPC API 4.0 to create a new promotion.

Parameters

Response

Request

<?php 

class Client
{
    protected static $merchantCode;
    protected static $loginDate;
    protected static $hash;
    protected static $baseUrl;
    protected static $callCount = 0;
    protected static $sessionId = '';

    protected static $client;

    public static function setCredentials($code, $key)
    {
        static::$merchantCode = $code;
        static::$loginDate = gmdate('Y-m-d H:i:s');
        static::$hash = hash_hmac('md5', strlen($code) . $code . strlen(static::$loginDate) . static::$loginDate, $key);
        static::$sessionId = static::login();
    }

    public static function setBaseUrl($url)
    {
        static::$baseUrl = $url;
    }

    public static function login()
    {
        $client = static::getClient();
        return $client->login(static::$merchantCode, static::$loginDate, static::$hash);
    }

    public static function __callStatic($name, $arguments = array())
    {
        $client = static::getClient();

        array_unshift($arguments, static::$sessionId);
        $response = call_user_func_array(array($client, $name), $arguments);

        return $response;
    }

    protected static function getClient()
    {
        $opts = array(
            'http'=> ['user_agent' => 'PHPSoapClient'],
            'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
            ],
        );

        if (null === static::$client) {
            static::$client = new \SoapClient(static::$baseUrl . '?wsdl', [
                'location' => static::$baseUrl,
                'cache_wsdl' => WSDL_CACHE_NONE,
                'stream_context' => stream_context_create($opts),
            ]);
        }

        return static::$client;
    }
}


$promotionObject = new stdClass;
$promotionObject->Name = 'YOUR_PROMOTION_TITLE';
$promotionObject->Description = 'YOUR_PROMOTION_DESCRIPTION';
$promotionObject->StartDate = date('Y-m-d', strtotime('1 month ago'));
$promotionObject->EndDate = date('Y-m-d', strtotime('+1 month'));
$promotionObject->Type = 'REGULAR';
$promotionObject->Enabled = 1;
$promotionObject->MaximumOrdersNumber = 0;
$promotionObject->MaximumQuantity = 0;
$promotionObject->InstantDiscount = false;
$promotionObject->ChannelType = 'ECOMMERCE';
$promotionObject->ApplyRecurring = 'NONE';
$promotionObject->RecurringChargesNumber = 3;
$promotionObject->PublishToAffiliatesNetwork = 0;
$promotionObject->AutoApply = 0;

$couponObject = new stdClass;
$couponObject->Type = 'SINGLE';
$couponObject->Code = 'single_code';
$promotionObject->Coupon = $couponObject;

$discountObj = new stdClass;
$discountObj->Type = 'PERCENT';
$discountObj->Value = 80;
$promotionObject->Discount = $discountObj;
$promotionObject->Products = [$productsObj1, $productsObj2, $productsObj3];
$promotionObject->Translations = [$translation1, $translation2];

Client::setBaseUrl('https://api.2checkout.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();
$response = Client::addPromotion($promotionObject);
var_dump($response);

Overview

Set up subscription plans and offer shoppers:

• Free and paid trials
• Evergreen (one time fee) products/subscriptions
• Renewing subscriptions
• Subscriptions with metered billing

Availability

All 2Checkout accounts. 

Requirements

Make sure to have the mandatory product info on hand. 

Set up a subscription plan

1. Navigate to Products, create a new item, and go through the initial stages of product setup. You'll be able to configure a billing cycle and recurring costs immediately, and you can fine-tune the setting with the advanced options for subscription pricing and renewal. 
2. Configure recurring and manual charges, local pricing and currencies, pricing options, and renewal discounts,  under the Pricing tab. 
3. Set up billing cycles, contracts, and renewal notifications under the Renewal tab.

Renewal/Recurring pricing

Set up different renewal prices for subscriptions and configure recurring charges.

Products with a base price

Access guidance on configuring custom recurring charges. 

A number of options are available, including matching the costs of renewals to those of the initial purchases and configuring a renewal base price independent of the price first paid by subscribers. You can define individual prices for each currency and option, not necessarily based on a formula. For subscriptions sold initially based on a base price, when setting a renewal base price, 2Checkout applies all active pricing options to the new base price.

Products without base price

Access guidance on configuring custom recurring charges. 

Matching the costs of renewals to those of the initial purchases is an option that's also available for products without a base price. In addition, you get the possibility to also set renewal prices manually, according to the overall pricing strategy associated with the subscription.

Promotions for subscriptions

Discount the costs of subscriptions both on the initial purchase and for every subsequent charge be it recurring or not. 

Renewal discounts

Navigate to Subscriptions under Setup, and select the Renewal Discounts tab.

1. Enter a promotion title (will be visible to shoppers during the purchase process) and a description.
2. Discount code: enter the coupon value.
3. Set the discount either as a percentage or a fixed amount.
4. Edit the settings of the product for which you're discounting subscription charges and assign the promotion to the plan under the Pricing Tab. Provided that you have defined at least one promotion, you can apply a discount to both manual and automatic renewals (recurring charges).

• For products with a base price (dynamic), discounts can be applied in the Renewal Price area of the pricing configuration page.
• For products without a base price (flat), discounts can be added by navigating to the Prices area on the pricing configuration page and then selecting the Renewal tab.

Promotions for recurring orders

Use Apply to recurring charges to easily extend the benefits of promotions for subscriptions you offer customers well beyond the first transaction, by applying them not only to the initial purchase but also to as many subsequent charges as you wish. 

Billing cycle 

Control individual billing cycle settings right from the Renewal area of the Control Panel when editing a product.

The billing cycle defines the time interval between the initial billing date and the renewal charge. Options available: 

• Renewal interval in days - supported values from 7 to 1095 days. The minimum subscription lifecycle is 7 days. Please contact 2Checkout directly if this feature is not available for your account.
• Monthly from one (1) month to three (3) years (36 months).
• One time fee to set up the duration for the subscription as non-renewing (lifetime).

Changing the billing cycle for a subscription plan comes into effect only after existing, active subscriptions renew. 

Subscription billing cycle workflow

Following the initial acquisitions, at the end of the billing cycle, the 2Checkout system can:

• Convert all trials for which shoppers supplied payment information such as the credit card unless they opted out during the trial period. 
• Automatically renew the subscription generated for the purchased product if shoppers enabled recurring billing. 
• Send manual renewal links to the shoppers who opted out of recurring billing. 

Manage subscriptions for bundled products

Subscription management for bundle products comes with two different options:

• Create subscription settings for bundle product
• Use the subscription settings of each product in the bundle

It's up to you to decide whether to generate a global subscription for all the products in a bundle, overwriting per-product specific renewal configurations, or whether to define individual renewal settings for each standalone product part of the bundle.

Renewal notification emails

The 2Checkout system notifies your shoppers when their subscription is close to expiration via email. You can opt to:

• Send emails according to the global renewal notification settings
• Create individual renewal notification settings for this product

Both options enable you to control the number of notification messages sent to customers, as well as when they should receive them. Whether their subscription is set to manual payment or automatic renewal, shoppers can get email notifications:

• 30 days before the subscription expiration date
• 15 days before the subscription expiration date
• 7 days before the subscription expiration date
• 1 day before the subscription expiration date (only available if your account supports setting renewal intervals in days. Contact 2Checkout directly if you'd like to take advantage of this feature.)
• on the expiration date
• 5 days after the subscription expiration date
• 15 days after the subscription expiration date

Renewal with a new product version

Ensure smooth upgrades from deprecated versions of a product to the latest release. 2Checkout offers shoppers the option to replace their old version of a subscription with the latest one, provided that you configure Renewal with a new product version settings. Essentially, this enables customers to upgrade older versions of offerings they purchased from you as a part of the renewal process.

1. When setting up the subscription, check the box which specifies that the product is a newer version of other items.
2. Next, access the list with existing products, and select the deprecated items you want to be replaced by the subscription you're creating, during the renewal process.
3. Choose to replace as many old versions of the deprecated product with the new one as you want.

Global renewal settings

Select the Renewal Settings tab under Setup->Renewal and set the global renewal options to apply to all the products for which 2Checkout generates subscriptions.

When customers buy a subscription, they will be able to activate auto-renewals and, thus, agree to automated future charges for that subscription. To do that, they need to provide express consent and opt-in for automatic renewal, during the purchase process. When selecting the Enable auto-renewal option during the purchase process, shoppers enroll in the automatic renewal system, enabling 2Checkout to set in place a recurring charge schedule for their subscription based on the billing cycle setup.

Shoppers have the option to cancel automatic renewals by accessing their 2Checkout myAccount.

If shoppers decide not to enroll in the automatic renewal system, 2Checkout sends out email notifications when subscriptions are about to expire. These email notifications inform shoppers that they need to purchase subscription renewals.

The 2Checkout system allows you to control the intervals of time when expiration notifications will be sent out to customers, both per-product, and via the Global Renewal Settings. Any changes of the Global Renewal Setting will impact all offerings that have the Renewal status enabled, but will be overridden by per-product subscription settings:

Grace period 

Enable shoppers to purchase renewals even after subscriptions expire, while their old subscriptions are still in the grace period. Subscriptions that are not renewed ahead of the expiration deadline that enter the grace period feature the Past due status.

Grace period options available include:

• 0 days
• 5 days
• 15 days
• 30 days
• 60 days
• Unlimited

When the unlimited option is selected, customers can renew their subscription regardless of the amount of time that passes after the expiration mark.

• Subscription validity after renewal starts on - you can choose to have the new subscription start on the same day when the previous subscription expires, or on the renewal day.
• Send renewal emails - to all subscription renewals or only to renewals of 6 months (or more). This setting suppresses all emails sent when renewing subscriptions with billing cycles shorter than 6 months, except for the emails sent 7 days before the subscription expiration date.

Email template manager - renewal notifications

Personalization of notification content emailed to subscribers comes to complement the customization capabilities of renewal settings in the 2Checkout system. By controlling the messages shoppers receive you maximize chances of successful renewals.

Navigate to Email template manager under Marketing tools, and expand the Renewal area on the custom HTML email templates page. You can add custom text to auto and manual payment notification emails, and preview all messages, including Trial automatic purchase notifications.

Two email formats are available, HTML and Text. When selecting the first, you'll also be able to choose an HTML template, either by opting for the default one or by adding custom designs.

Overview

Use the placeOrder method to create an order and collect the payment.

Supported payment methods 

Credit/Debit cards: Visa and MasterCard local Brazilian cards.

Parameters 

Requirements

1. Payment methods: Visa, MasterCard or AMEX
2. Country: Brazil
3. Currency BRL
4. Specified number of installments under the PaymentMethod object. (Minimum installment threshold is 5 BRL.)
   
   • Phone number
   • Fiscal code (CPF/CNPJ)
5. Mandatory billing information must include:
6. Transaction: non-recurring
7. Installments are available only for:
   
   • Brazilian customers
   • Local Visa, MasterCard and AMEX cards
   • Non-recurring transactions

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;

$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;


try {
    $OrderInstallments = $client->getInstallments($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "Order_Installments: " . $e->getMessage();
    exit;
}
var_dump("Order_Installments", $OrderInstallments);

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->InstallmentsNumber = 2;
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}
var_dump("newOrder", $newOrder);