Overview

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

Parameters

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 Avangate customer reference

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

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

Response

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

Requirements

To move a subscription from a source customer to a target customer:

• Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
• Customer references must be valid and associated to the target customer entity under which you move the subscription.
• If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$customerReference = CUSTOMER_REFERENCE;

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

Overview

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

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

try {
    $AdditionalFields = $client->getAdditionalFields($sessionID);
}

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

var_dump("AdditionalFields", $AdditionalFields);

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

Requirements

To move a subscription from a source customer to a target customer:

• Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
• Customer references must be valid and associated to the target customer entity under which you move the subscription.
• If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$customerReference = CUSTOMER_REFERENCE;

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

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

Overview

Use the getSubscriptionPaymentInformation method to retrieve information related to the payment made for a subscription.

Parameters

Response

Response sample

{
    "Type": "CC",
    "Currency": "USD",
    "PaymentMethod": {
        "FirstDigits": "4111",
        "LastDigits": "1111",
        "ExpirationMonth": null,
        "ExpirationYear": null,
        "CardUpdated": false,
        "Authorize3DSUrl": null,
        "CardType": "Visa"
    }
}

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'getSubscriptionPaymentInformation';
$jsonRpcRequest->params = array($sessionID, $subscriptionReference);
$jsonRpcRequest->id = $i++;

$paymentInformation = callRPC($jsonRpcRequest, $host);
var_dump($paymentInformation);

Overview

Use the getSubscriptionPaymentInformation method to retrieve information related to the payment made for a subscription.

Parameters

Response

Response sample

{
    "Type": "CC",
    "Currency": "USD",
    "PaymentMethod": {
        "FirstDigits": "4111",
        "LastDigits": "1111",
        "ExpirationMonth": null,
        "ExpirationYear": null,
        "CardUpdated": false,
        "Authorize3DSUrl": null,
        "CardType": "Visa"
    }
}

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

try {
    $paymentInformation = $client->getSubscriptionPaymentInformation($sessionID, $subscriptionReference);
} catch (SoapFault $e) {
    echo  $e->getMessage();
}
var_dump($paymentInformation);

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

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