Overview

Retrieve information about a subscription's history. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Use the API methods displayed below to extend or renew a subscription.

Overview

Use the addProduct method to create subscription plans/products for your 2Checkout account. 

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 = 'addProduct';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "AvangateId": null,
  "Enabled": true,
  "GeneratesSubscription": true,
  "GiftOption": false,
  "LongDescription": "Some long description",
  "ProductCode": "API_Imported_Product_1",
  "ProductGroupCode": "9652CDA441",
  "TaxCategory": "5db74b57-98a5-4fc1-b559-aee8eba3f046",
  "Tangible": 0,
  "Fulfillment": "",
  "Platforms": [
    {
      "Category": "Mobile",
      "IdPlatform": "23",
      "PlatformName": "Android"
    },
    {
      "Category": "Mobile",
      "IdPlatform": "20",
      "PlatformName": "iPhone"
    },
    {
      "Category": "Desktop",
      "IdPlatform": "32",
      "PlatformName": "Windows 10"
    }
  ],
  "Prices": [],
  "PricingConfigurations": [
    {
      "BillingCountries": [],
      "Code": "54DCBC3DC8",
      "Default": true,
      "DefaultCurrency": "USD",
      "Name": "2Checkout Subscription's Price Configuration Marius",
      "PriceOptions": [
        {
          "Code": "SUPPORT",
          "Required": true
        },
        {
          "Code": "USERS",
          "Required": true
        },
        {
          "Code": "BACKUP",
          "Required": false
        }
      ],
      "PriceType": "NET",
      "Prices": {
        "Regular": [
          {
            "Amount": 99,
            "Currency": "USD",
            "MaxQuantity": "99999",
            "MinQuantity": "1",
            "OptionCodes": []
          },
          {
            "Amount": 0,
            "Currency": "EUR",
            "MaxQuantity": "99999",
            "MinQuantity": "1",
            "OptionCodes": []
          }
        ],
        "Renewal": []
      },
      "PricingSchema": "DYNAMIC"
    }
  ],
  "ProductCategory": "Audio & Video",
  "ProductImages": [
    {
      "Default": true,
      "URL": "https://store.avancart.com/images/merchant/ef0b9a69f90b1ab0228784ccc7d52136/products/box-2.jpg"
    }
  ],
  "ProductName": "Product Name 01",
  "ProductType": "REGULAR",
  "ProductVersion": "1.0",
  "PurchaseMultipleUnits": true,

  "ShortDescription": "some short description",
  "SubscriptionInformation": {
    "BillingCycle": "1",
    "BillingCycleUnits": "M",
    "BundleRenewalManagement": "GLOBAL",
    "ContractPeriod": {
      "Action": "RESTART",
      "EmailsDuringContract": true,
      "IsUnlimited": true,
      "Period": -1,
      "PeriodUnits": "D"
    },
    "DeprecatedProducts": [],
    "GracePeriod": {
      "IsUnlimited": false,
      "Period": "7",
      "PeriodUnits": "D",
      "Type": "CUSTOM"
    },
    "IsOneTimeFee": false,
    "RenewalEmails": {
      "Settings": {
        "AutomaticRenewal": {
          "After15Days": false,
          "After5Days": false,
          "Before15Days": false,
          "Before1Day": false,
          "Before30Days": false,
          "Before7Days": true,
          "OnExpirationDate": true
        },
        "ManualRenewal": {
          "After15Days": false,
          "After5Days": false,
          "Before15Days": false,
          "Before1Day": false,
          "Before30Days": false,
          "Before7Days": true,
          "OnExpirationDate": true
        }
      },
      "Type": "CUSTOM"
    },
    "UsageBilling": 0
  },
  "SystemRequirements": "",
  "Translations": [
    {
      "Description": "some description",
      "Language": "ZH",
      "LongDescription": "some long description",
      "Name": "some name",
      "SystemRequirements": "",
      "TrialUrl": "url",
      "TrialDescription": "TrialDescription"
    }
  ],
  "TrialDescription": "",
  "TrialUrl": ""
}
JSON;
}

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

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Response 

bool(true)

Overview

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

Retrieve next renewal price

Next renewal price object

Overview

Use this guide to prepare and migrate your 2Checkout API implementation from version 1.0 to 3.0. This document features deprecations, updates and enhancements, providing guidance on how to upgrade your implementation to the latest version of the 2Checkout API. 

API 1.0 discontinuation

2Checkout plans to discontinue API 1.0 as of the end of February 2017. The end-of-support date implies ceasing all development of bug fixes and patches for API 1.0. 

API 3.0 availability

Version 3.0 of the 2Checkout API is available as of June, 2016, following an extensive public testing phase started in November 2015. 2Checkout recommends that you migrate to the latest version of the API (v3.0) to enjoy support for your implementation.

API 3.0 what’s new and benefits

1. Full REST support for existing platform functionalities in addition to SOAP and JSON-RPC.
2. Simplify interactions with single-entry point (one endpoint, one client, single-authentication).
3. Centralized all previous functionality under 3.0 (plus new capabilities).

4. Unified WSDL for Order, Subscription, and Product scenarios.

Serializations 1.0 vs. 3.0

Single API URL per serialization format

• https://api.avangate.com/rpc/3.0/
• https://api.avangate.com/soap/3.0/
• https://api.avangate.com/rest/3.0/
• https://api.avangate.com/3.0/ redirects to  https://api.avangate.com/rest/3.0/ by default

WSDL 1.0 vs. 3.0

When you migrate from API 1.0 to 3.0, stop using https://secure.2checkout.com/api/merchant/?wsdl in favor of https://api.2checkout.com/soap/3.0/?wsdl.

Methods 1.0 vs. 3.0

New use cases API 3.0 

​

​

Overview

Use the JavaScript Affiliate Checker to keep track of sales generated by members of the 2Checkout Affiliate Network for services/products that you sell using a third-party eCommerce platform.

• 3rd party eCommerce provider -> JAVASCRIPT affiliate checker -> detects 2Checkout cookie -> 2Checkout buy-links
• 3rd party eCommerce provider -> JAVASCRIPT affiliate checker -> does not detect 2Checkout cookie -> 3rd party buy links

Requirements

In order to use JavaScript Affiliate Checker, the following requirements must be met:

• The 2Checkout Affiliate Network is enabled for your account.
• Products sold through a third-party platform and available to 2Checkout Affiliates must be configured within the 2Checkout platform as well, and need to be assigned to commissions lists associated with 2Checkout Affiliates. Make sure to specify a commission you're willing to pay for affiliate referrals.

How does the JavaScript Affiliate Checker work?

Take advantage of the JavaScript Affiliate Checker to customize the content of your online store for those shoppers that feature the 2Checkout affiliate cookie.

Installing the JavaScript Affiliate Checker

To install, copy and customize the 2Checkout Affiliate Checker JavaScript code and place the code between the <head></head> tags on your site.

<script language="JavaScript">
var vId = 'UNIQUE CODE FOR YOUR ACCOUNT';
var scriptSRC = '/check_affiliate_v2.js';
var protocol = window.location.protocol;
if (protocol.indexOf("https") === 0) document.write(unescape("%3Cscript src='https://secure.2Checkout.com/content" + scriptSRC + "' type='text/javascript'%3E%3C/script%3E"));
else document.write(unescape("%3Cscript src='http://content.2Checkout.com" + scriptSRC + "' type='text/javascript'%3E%3C/script%3E"));
</script>
<script language="JavaScript">
var avgParams = _checkAvgParams();
var alreadyChecked = false;
if (avgParams != null) {
_AVGSetCookie('_avgCheck', avgParams);
alreadyChecked = true;
}
var avgProds = _avgProds(_AVGGetCookie('_avgCheck'), alreadyChecked, vId); //redirect
var AVG_AFF = false;var AVG_PRODS = new Array();
if (avgProds != "-") {
AVG_AFF = true;
if(avgProds != 'all') {AVG_PRODS = avgProds.split(',');}
}
</script>

The JavaScript code inserted into your site will help check and identify shoppers that feature the 2Checkout affiliate cookie and will return a set of results (response JavaScript variables):

• AVG_AFF - boolean - having the following possible values
  
  • true - the customer has an active tracking cookie
  • false - the customer does not have an active tracking cookie
• AVG_PRODS - JavaScript array - an associative array with all products that are tracked by 2Checkout or empty value is a general referral cookie is set.

• AVG_SET_DATE – delivers the date when the cookie was set in the user’s browser
  
  • Format: YYYY-MM-DDTHH:MM:SS (E.G: 2019-10-18T15:27:54)

Use the results to:

• Build efficient landing pages for your affiliates;
• Display custom information on your pages;
• Prevent affiliate leaks by displaying the correct buy buttons;
• Get extra information about your affiliate activity.

You will need to use the responses returned by the script in order to redirect shoppers to either the 2Checkout shopping cart, if a 2Checkout affiliate ID is detected, meaning they there were redirected to your website from a 2Checkout affiliate; or to the third-party shopper platform of your choice.

When redirecting customers to the 2Checkout shopping cart, use Buy Links generated via the Control Panel.

Orders placed by shoppers that used the Buy Links from 2Checkout affiliates will immediately be visible in the Order search area of the Control Panel.

Overview

Add/import subscriptions in the Avangate system. Include card data with your subscription import only if you contacted Avangate to enable this functionality for your account. Otherwise, the import process results in a failure. Contact Avangate or your account manager directly for more details.

Attributes

Card payment

Add credit/debit card details when importing subscriptions. Avangate uses payment information in the recurring billing process. 

For imports of test subscriptions, use the credit card information from this article.

Use the variables in the list below to customize the Offline payments guidance 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

Refund a sale made in 2Checkout via the issueRefund API method. You can issue a refund for only a sale line item, issue a partial refund on the total amount, or refund the entire order amount.

Requirements

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

Parameters