Overview

Apply discount coupons to products added to the shopping cart.

Requirements

Parameters

Response

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$couponCode = 'YOUR_CUPON_CODE';

try {
    $SetCoupon = $client->setCoupon ($sessionID, $couponCode);
} catch (SoapFault $e) {
    echo "Promotion: " . $e->getMessage();
    exit;
}
var_dump ("Promotion ", $SetCoupon);

Errors

Overview

Use searchShippingMethods to retrieve information on the shipping methods currently defined on your account.

Search filters

Use the parameters below to filter the results of your search for shipping methods.

Sample request

<?php

require ('PATH_TO_AUTH'); // authentication call

$SearchOptions = new \stdClass();
$SearchOptions->Name = 'ShippingMethodName'; // search for a specific shipping method
$SearchOptions->Codes = ['Code1', 'Code2', 'Code3']; // array of shipping method codes
$SearchOptions->Countries = ['US', 'UK', 'AU']; // array of country codes
$SearchOptions->Active = true; // only active shipping methods
$SearchOptions->Pagination = new \stdClass();
$SearchOptions->Pagination->Page = 1; // set display pages
$SearchOptions->Pagination->Limit = 200; // limit the results

try {
    $shippingMethods = $client->searchShippingMethods($sessionID, $SearchOptions);
}
catch (SoapFault $e) {
    echo "shippingMethods: " . $e->getMessage();
    exit;
}
var_dump("shippingMethods", $shippingMethods);

Response

Overview

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

Retrieve a subscription             Search subscriptions            Retrieve customer's subscriptions          Retrieve specific subscriptions

Subscription object

Overview

Use the variables in the list below to customize the Recurring payment failed (dunning notification) shopper email notifications according to your needs.

Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Overview

Use the CrossSellCampaign object to retrieve information about the cross-sell campaigns you configured for your account. 

Parameters

Overview

Use getShippingPrice to retrieve the shipping method and price available, based on a current cart configuration. This API call returns the available shipping methods defined in your Control Panel, together with the fees you configured based on order total amount/weight/country.

Requirements

It's mandatory to have tangible products defined in your Control Panel, to retrieve shipping method and price information.

Parameters

Sample request

<?php

require ('PATH_TO_AUTH'); // authentication call

$cartItems = [];
$cartItem = new stdClass();
$cartItem->Code = 'my_product_code_1'; // product code defined in the Information tab, at product level
$cartItem->Quantity = 2; // quantity that is being purchased
$cartItems[0] = $cartItem;
$billingDetails = new stdClass();
$billingDetails->CountryCode = 'US'; // billing country
$deliveryDetails = new stdClass();
$deliveryDetails->CountryCode = 'AU'; // delivery country

$currency = 'USD'; // purchase currency

$couponCode = ['TANGIBLEPROMO']; // apply discount to promotion

try {
    $shippingPrice = $client->getShippingPrice($sessionID, $cartItems, $billingDetails, $deliveryDetails, $currency);
}
catch (SoapFault $e) {
    echo "ShippingPrice: " . $e->getMessage();
    exit;
}
var_dump("ShippingPrice", $shippingPrice);

Response

Overview

Use the getProductTaxCategories method via SOAP API 6.0 to retrieve the available tax categories and manage them for your catalog products.

Request Parameters

Request Example

<?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 = 'getTaxCategories';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = [];
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ) {
        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, $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);
    }
}

$client = new Client();
$result = $client->call();
var_dump($result);

Response

Overview

For a paused subscription 2Checkout suspends all automatic charges for a predefined time period. When subscribers request to pause a subscription, this remains active until the end of the current billing cycle, at which point the subscription will move into a paused status.

Availability

Available free of charge for the 2Subscribe and 2Monetize accounts as part of the base package. Available for merchants on 2Sell accounts only if they have purchased the 2Bill add-on. Contact 2Checkout to request the activation of this functionality.

Benefits

For your Subscribers

Sometimes, for various reasons, your subscribers might want to interrupt their services for a period rather than just canceling them. By using the pause functionality, subscribers will be able to:

• Pause a subscription to a service they use only infrequently.
• Pause a subscription to a service they won't have access to for an extended period.
• Pause a subscription to a seasonal service and renew it when they need to.
• Pause a subscription to reduce certain costs for a period.

For you (Merchant)

As a merchant, you can benefit in multiple ways by allowing your customers to pause their subscriptions:

• You can reduce churn​. How? Well, considering an important number of subscribers who plan to re-subscribe after canceling a subscription forget to ​do so, having an automated system in place to take care of this mishap ensures a sizable chunk of these sales would be renewed. Also, when given the alternative to pause a subscription, your customers will be less likely to cancel their subscriptions​.
• You can reduce spillage​. You may choose to pause certain subscriptions that have payment issues likely to be resolved. This way you can simply pause the access of your subscribers to a certain service until their payment issues are solved, and thus stop spillage.
• You can get insights on why your customers want to cancel or pause subscriptions and use that reason to offer them customized options for packaging, pricing, promotions, lead management, etc​.
• Last but not least! You can increase customer satisfaction​, as your subscribers will be able to return to the services they like in a more simple and easier way.

Pause a subscription

Via the Merchant Control Panel

1. Once the pause feature is enabled for your account, you can pause subscriptions directly from your Merchant Control Panel.
2. Navigate to the subscription page and click on the Pause button next to the Cancel immediately option. The Pause button is displayed only for subscriptions that are eligible to be paused according to the requirements mentioned below. 
3. When clicking the Pause button, a pop-up window opens allowing you to define the pause end date (resume date). The same pop-up notifies you of the interval during which the pause subscription is active, and when the next billing date is.
4. Once the next billing date is reached, the subscription automatically resumes and becomes Active again if billing is successful. If billing is not successful, the status will either be Past-Due or Expired, depending on the previous expiration date, grace period, and resume date.  

Pause periods cannot be greater than 3 years.

Pause subscription events will be logged and displayed in the subscription history section of your Merchant Control Panel.

Via API 6.0

To allow pausing via API, we added the pauseSubscription method, available in the latest API version (6.0) for all protocols (JSON-RPC, SOAP, REST). 

To set pause subscription via API calls, see the following:

• SOAP API 6.0
• JSON-RPC API 6.0
• REST API 6.0

Via Shopper myAccount

Your shoppers can pause their subscriptions by themselves via their shopper MyAccount page as part of the churn prevention campaign flow.

Requirements

The following subscriptions cannot be paused: 

• Inactive, Past-Due, Expired or Canceled subscriptions
• Trial subscriptions
• Lifetime subscriptions
• Channel Manager subscriptions
• Subscriptions set to manually renew
• Subscriptions with usage billing pricing

Resume a subscription

Pauses associated with subscriptions can be canceled and subscriptions can be resumed before the pause starts or while the pause is in effect. When the pause is canceled, the following occurs:

• If the pause is only scheduled, but not in effect
  • If there are other billing attempts scheduled in the time between the cancelation of the pause and the expiration of the subscription (i.e. NOW < Pre-expiration attempt < Expiration), the next billing date is set to the first billing attempt scheduled to happen.
  • If there are no other billing attempts scheduled in the time between the cancelation of the pause and the expiration of the subscription (i.e. Pre-expiration attempt < NOW < Expiration), the next billing date is set to NOW, and a billing attempt is made and the subscription status becomes ACTIVE until the subscription expiration date.
• If the pause is in effect, the next billing date is set to NOW, and a renewal attempt is made. Depending on the success of the attempt one of the following happens:
  
  • If the renewal attempt is successful, the subscription status becomes ACTIVE, and the new expiration date is set to NOW() + Bill cycle length
  • If the renewal attempt is not successful, the subscription status will be based on the previous expiration date and grace period settings, in other words:
    
    • PAST DUE – if the moment the subscription is canceled is less than the previous expiration date + grace period.
    • EXPIRED – if the moment the subscription is canceled is greater than previous expiration date + grace period

Subscription pauses can be canceled as part of the following actions:

• Manually
  • via Merchant Control Panel: Only for test subscriptions, using the Renew Subscription button.
  • via Manual renewal links: Redirecting to shopping cart where shoppers have a Manual renewal link
  • via API: Using the renewSubscription, placeOrder, and cancelPause methods
  • via 2Checkout Customer myAccount: Using the Renew now button and the Change credit card and payment flow.
• Automatically
  
  • At a scheduled date and time – Subscription will resume automatically when the pause end date is reached.

Reporting

Pause subscription events will be logged and displayed in the subscription history section of your Merchant Control Panel. You can see all your paused subscriptions by navigating to your Merchant Control Panel - Orders & customers - Subscriptions and checking the Paused filter in the Subscription status field.

FAQ

1. Can paused subscriptions still be manually renewed?

Yes. There are several ways to manually renew a subscription scheduled to pause.

2. Can I cancel a subscription that is already paused?

Yes. You can always cancel a subscription that is already paused either via your Merchant Control Panel or via API or as part of the Refund/Chargeback process. Canceling the subscription from any of these sources will cause any pauses associated with the subscription to be marked as canceled only after the subscription itself is canceled.

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription. 

Parameters

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

• Manual and automatic renewals
• Upgrades
• Trial conversions

Response

Request

<?php
$host   = "https://api.2checkout.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 = "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;
}
$SubscriptionReferenceTest = '0177AAA92B';
try {
    $retrievedSubscription = $client->getSubscription($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "retrievedSubscription: " . $e->getMessage();
    exit;
}
var_dump("retrievedSubscription", $retrievedSubscription);
var_dump ($retrievedSubscription);
$retrievedSubscription->RecurringEnabled = false;
$retrievedSubscription-> SubscriptionEnabled = true;
$retrievedSubscription->ExpirationDate = '2020-12-12';
try {
    $updatedSubscription = $client->updateSubscription($sessionID, $retrievedSubscription);
}
catch (SoapFault $e) {
    echo "updatedSubscription: " . $e->getMessage();
    exit;
}
var_dump("updatedSubscription", $updatedSubscription);

Overview

Use the assignPricingConfigurationOptionGroup method to assign a PricingOption Group to a PricingConfiguration.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$PricingConfigurationCode = 'YOUR_CODE';
$PriceOptionsGroupAssigned = new stdClass();
$PriceOptionsGroupAssigned->Code = 'USERSUSERS';
$PriceOptionsGroupAssigned->Required = TRUE;

try {
    $AssignedOption = $client-> assignPricingConfigurationOptionGroup ($sessionID, $PricingConfigurationCode, $PriceOptionsGroupAssigned);
}

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

var_dump("Options", $AssignedOption);

?>