Overview

Use the getInvoices method to extract shopper invoices from the 2Checkout system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$reference = 'ORDER_REFERENCE';

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

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

Overview

Retrieve information about the upgrade options for a specific subscription.

Overview

Use the updateLead method to update an existing lead and change all current values with new data.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$Lead = new stdClass();

$Lead->CartId = "CartIdValue";
$Lead->Currency = "EUR";
$Lead->Language = "BG";
$Lead->ExternalReference = "REST_API_3CHECKOUT";
$Lead->Source = "testAPI.com";
$Lead->CustomerReference = "asdf1";
$Lead->MachineId = "123asd";

$Lead->Items = [];

$Item = new stdClass();
$Item->Code = "04C26C50F8";
$Item->Quantity = 2;
$Item->IsDynamic = false;
$Item->Tangible = true;
$Item->PurchaseType = "PRODUCT";
$Item->PriceOptions = [];

$priceOption = new stdClass();
$priceOption->Name = "group name 1";
$priceOption->Required = false;
$option = new stdClass();
$option->Name = 'add25';
$option->Value = 'add25';
$option->Surcharge = 100;
$priceOption->Options[] = $option;

$Item->PriceOptions[] = $priceOption;

$recurringOptions = new stdClass();
$recurringOptions->CycleLength = 6;
$recurringOptions->CycleUnit = 'MONTH';
$recurringOptions->CycleAmount = 100;
$recurringOptions->ContractLength = 2;
$recurringOptions->ContractUnit = 'YEAR';
$Item->RecurringOptions = $recurringOptions;

$marketingCampaigns = new stdClass();
$marketingCampaigns->Type = 23;
$marketingCampaigns->ParentCode = "m";
$marketingCampaigns->CampaignCode = 23;
$Item->MarketingCampaigns = $marketingCampaigns;

$Item->Price = new stdClass();
$Item->Price->Amount = 20;
$Item->Price->Type = "CUSTOM";

$additionalFields = [];

$additionalField = new stdClass();
$additionalField->Code = "TestFieldOne";
$additionalField->Text = "test text";
$additionalField->Value = "test value";
$additionalFields[] = $additionalField;
$Item->AdditionalFields = $additionalFields;

$Item->SubscriptionStartDate = date("Y-m-d H:i:s");

$Lead->Items[] = $Item;

$billingDetails = new stdClass();
$billingDetails->FirstName = "Customer";
$billingDetails->LastName = "2Checkout";
$billingDetails->Phone = null;
$billingDetails->Company = null;
$billingDetails->FiscalCode = "32423423";
$billingDetails->Email = "customer@2checkout.com";
$billingDetails->Address1 = "Test Address";
$billingDetails->Address2 = null;
$billingDetails->City = "LA";
$billingDetails->Zip = "12345";
$billingDetails->CountryCode = "RO";
$billingDetails->State = "CA";

$Lead->BillingDetails = $billingDetails;
$Lead->DeliveryDetails = clone($billingDetails);

$Lead->DeliveryInformation = new stdClass();
$Lead->DeliveryInformation->ShippingMethod = new stdClass();
$Lead->DeliveryInformation->ShippingMethod->Code = "sdfsd";

$Lead->PaymentDetails = new stdClass();
$Lead->PaymentDetails->Type = "CC";
$Lead->PaymentDetails->Currency = "EUR";
$Lead->PaymentDetails->PaymentMethod = new stdClass();
$Lead->PaymentDetails->PaymentMethod->RecurringEnabled = false;
$Lead->PaymentDetails->PaymentMethod->CardPayment = new stdClass();
$Lead->PaymentDetails->PaymentMethod->CardPayment->InstallmentsNumber = 23;
$Lead->PaymentDetails->CustomerIP = "1.2.3.4";

$Lead->LocalTime = date("Y-m-d H:i:s");

$jsonRpcRequest = array (
    'method' => 'updateLead',
    'params' => array($sessionID, $Lead, '60E6C4B574'),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response Example

class stdClass#18 (4) {
  public $LeadCode =>
  string(10) "60E6C4B574"
  public $CreatedAt =>
  string(19) "2019-11-05T16:39:36"
  public $UpdatedAt =>
  string(19) "2019-11-05T16:48:31"
  public $Errors =>
  array(0) {
  }
}

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.