Overview

Use the GetDealInfo method to retrieve information about the existing deal on a given subscription as well as what the subscription will look like with the new proposed deal being applied to it.

Request parameters

Request sample

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = '1234554321';
    public const MERCHANT_KEY = 'D+~=z5R+R4])4D5&p56%';
    public const URL = 'http://api.avangate.local/rpc/6.0';
    public const ACTION = 'getDealInfo';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "Currency": "usd",
  "Country": "us",
  "Language": "ro",
  "CustomerIp": "91.220.121.21",
  "Source": "salesforce_cpq",
  "Items": [
    {
      "DealDate": "2021-09-20 23:59:59",
      "SubscriptionReference": "L10RV2QPFZ",
      "ProductCode": "3EGZDNNRQY",
      "Quantity": 10,
      "DealPriceScenario": "using_last_order_price",
      "DealSubscriptionScenario": "prolong1",
      "Price": {
        "Amount": 200,
        "Type": "CUSTOM",
        "AmountType": "NET"
      },
      "SubscriptionCustomSettings": {
        "CycleLength": 1,
        "CycleUnit": "MONTHS",
        "CycleAmount": 10,
        "CycleAmountType": "NET",
        "ContractLength": 12
      }
    }
  ],
  "BillingDetails": {
    "FirstName": "Oscar",
    "LastName": "McMillan",
    "CountryCode": "ro",
    "State": "Ilios",
    "City": "RE",
    "Address1": "4519 Kovar Road",
    "Zip": "645",
    "Email": "o.mcmillan@integrawealth.net",
    "Phone": "6172938133",
    "Company": "Integra Wealth",
    "FiscalCode": "98414321421"
  },
  "DeliveryDetails": {
    "FirstName": "Maria",
    "LastName": "Frederick",
    "CountryCode": "ro",
    "State": "New York",
    "City": "Buffalo",
    "Address1": "2033 Nuzum Court",
    "Zip": "14216",
    "Email": "m.frederick@integrawealth.net",
    "Phone": "7165708136",
    "Company": "Integra Wealth"
  }
}
JSON;
}
class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        return compact('merchantCode', 'date', 'hash');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $payload = array_filter($payload);
        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response 

Error handling

Overview

Use the assignAdditionalField method to assign additional fields to a product.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductCode = 'YOUR_PRODUCT_CODE';
$FieldCode = 'YOUR_FIELD_CODE';
$Required = true;

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

?>

Overview

Use the getProposalVersion method via SOAP API 6.0 to retrieve a specific proposal version.

Request Parameters

Request Sample

<?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 = 'getProposalVersion';
    public const ADDITIONAL_OPTIONS = null;
    public const PROPOSAL_ID = "7ee02473-b60a-415b-90ae-87c6c443f684";
    public const PROPOSAL_VERSION = 3;
    //array or JSON
    public const PAYLOAD = <<<JSON
    {
    }
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION,
        string $proposalId = Configuration::PROPOSAL_ID,
        int $proposalVersion = Configuration::PROPOSAL_VERSION
    ): ?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, $proposalId, $proposalVersion]);

        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

The getProposalVersion call via SOAP API 6.0 returns the Proposal object.

Overview

One of the options to integrate your platform with the 2Checkout systems is to generate a buy-link that you can then apply to the Buy button on your web store. In this article, we will show you how to create a buy-link both for a single product as well as for multiple selections of different products.

Availability

All merchants (on any type of account) can generate a link from the Merchant Control Panel.

Generate a buy-link for one or more products using the default flows 

Follow the steps below to generate a buy-link for a single product:

1. Log in to your 2Checkout account in the Merchant Control Panel.

2. Navigate to Setup and click on Generate links. 

   • Learn how to manage buy-link behavior by using query parameters. 

   

3. Click on Checkout links and the Default flows cart. Here are the two most popular templates for it:

   • One page checkout without review 
   • One page checkout with review 
   • Learn more about purchase flows/funnels here.

   

4. Select one or more products from the dropdown list.
   If you have more than 2000 products in your product catalog in your 2Checkout account, you can perform multiple selections on the Generate links page, which allows you to select more products at a time instead of using individual search.
   
   
5. After selecting your product, a table will open under the selection field, that will allow you to modify the quantity for your product, its additional pricing options, or remove it from your selection.
   
   
6. The last step is to click on Generate Link to create your buy-link and place it on the call-to-action button on your online store. You can control order interface behavior with the advanced options for checkout.
   

Overview

Retrieve information on the evolution of a subscription in the Avangate system, including details of the initial acquisition and the subsequent renewals and upgrades. Use the getSubscriptionHistory method to retrieve details about a subscription. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Overview

Use the getTimezone method to retrieve information on the time zone used by your account for the 2Checkout API.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

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

Overview

The Google Tag Manager (GTM) is a small piece of JavaScript and non-JavaScript code (a container snippet) that you paste into your pages to configure or enable tags from Google Analytics or third parties. For more information on the Google Tag Manager and how to install it, click here.

Setting the Google Tag Manager (GTM)

To implement Google Tag Manager on your website, follow these steps:

1. Log into your 2Checkout Merchant Control Panel.
2. Navigate to Setup → Interface templates.
3. Click to Edit the template that needs to be tracked. An example is shown in the image below:
   

4. In the Head Information area → Meta & CSS, paste the Google Tag Manager code for your account at the end of the existing code in the section. An example of the Google Tag Manager code is shown below:

   <!-- Google Tag Manager -->
   <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
   new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
   j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
   'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
   })(window,document,'script','dataLayer','GTM-XXXXXX');</script>
   <!-- End Google Tag Manager -->

   Example of GTM code for the <body> tag:

   <!-- Google Tag Manager (noscript) -->
   <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXX"
   height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
   <!-- End Google Tag Manager (noscript) -->

   The GTM code needs to be placed on your own website as well – one snippet of code in the <head> and the other in the <body> tag, if this step has not already been done previously. See the image below for a screenshot of an example code that needs to be added to your own website. More information can be found on this page: https://developers.google.com/tag-manager/quickstart.
   

Sending MyOrder Data to Google Analytics 4

By default, the myOrder object is displayed only for orders with payments authorized instantly (this includes usually credit cards and PayPal), after the payment is complete (transaction needs to be authorized successfully). To have the myOrder object available for all placed orders regardless of the payment status (to send revenue to Google Analytics 4 based on myOrder.TotalPrice, to more offline payment methods orders), follow the steps below:

1. Log in to your Control Panel account.
2. Go to Setup → Ordering Options.
3. Scroll down to the After sale message area and check the checkbox for the Show message for all placed orders option.
   
4. Click Save settings at the bottom of the page.

A JavaScript object called myOrder is available on the Thank you page providing information about the purchased products including ID, quantity, name, price, etc.

To see information about orders in Google Analytics 4, follow these steps:

1. Log in to your Control Panel account.
2. Navigate to Setup → Ordering Options and click on the Analytics tab.
   
3. Scroll down to the Tracking script section and add a code snippet (for example add <div></div>).
4. Apply the code to all languages or to the languages for which you want your template to be tracked.
5. Click Save at the bottom of the page.
   

Google Tag Manager Configuration for Google Analytics 4

Create the Google Tag in Google Tag Manager

If you already have a Google Tag in your container that fires on all pages where the Google Tag Manager code is added, then you do not need to create a new Google Tag specifically for 2Checkout and can proceed directly to the next section.

Follow these steps to create a Google Tag:

1. Select Google Tag from the list of pre-defined tags. In the Tag ID section of the Google Tag Manager, enter the Measurement ID you find in your Google Analytics 4, under Admin → Data Streams.
2. Click on your website property and copy the Measurement ID. In the image below you can see where the Measurement ID is located in the Google Analytics 4 interface:
   
3. Under Fields to set, add the cookie_flags configuration:
   • Under Field Name add cookie_flags
   • Under Value add SameSite=None;Secure
4. For Triggering select All Pages.
   

Send eCommerce information to Google Analytics 4 from the 2Checkout shopping cart

2Checkout shopping carts include a dataLayer with eCommerce information for Google Analytics 4. You can view this information by typing dataLayer into the browser console and under gtag4, you can see the eCommerce information for Google Analytics 4, both at checkout and at purchase on the order Finish page.

To send eCommerce information to GA4 from the 2Checkout shopping cart, follow these steps:

1. Log in to Google Tag Manager.
2. Configure variables in the Google Tag Manager. To capture the eCommerce information from the dataLayer, you will first need to configure certain dataLayer variables in the Google Tag Manager.

3. Create a new User-Defined variable, called gtag4.event, in the Google Tag Manager.

   • Name your variable gtag4.event to track it easier.
   • For Variable Type, select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name, type gtag4.event.
   • Under Data Layer Version, select Version 2.

   
   

4. Create a new User-Defined variable called gtag4.currency in the Google Tag Manager.

   • Name your variable gtag4.currency to track it easier.
   • For Variable Type select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name type gtag4.currency.
   • Under Data Layer Version select Version 2.

   

5. Create a new User-Defined variable called gtag4.items in the Google Tag Manager.

   • Name your variable gtag4.items to keep track of it easier.
   • As Variable Type select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name type gtag4.items.
   • Under Data Layer Version select Version 2.

   

6. Create a new User-Defined variable called gtag4.tax in the Google Tag Manager.

   • Name your variable gtag4.tax to keep track of it easier.
   • For Variable Type select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name type gtag4.tax.
   • Under Data Layer Version select Version 2.

   

7. Create a new User-Defined variable called gtag4.transaction_id in the Google Tag Manager.

   • Name your variable gtag4.transaction_id to keep track of it easier.
   • For Variable Type select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name type gtag4.transaction_id.
   • Under Data Layer Version select Version 2.

   

8. Create a new User-Defined variable called gtag4.value in the Google Tag Manager to capture the total value of the order, including tax.

   • Name your variable gtag4.value to keep track of it easier.
   • For Variable Type select Data Layer Variable from the options provided by Google.
   • Under Data Layer Variable Name type gtag4.value.
   • Under Data Layer Version select Version 2.

   

To create a tag in your Google Tag Manager to send eCommerce information to Google Analytics 4, follow these steps:

1. Create a new tag called Google Analytics GA4 – 2 checkout event.

   • For Tag Type, select Google Analytics: GA4 event from the options provided by Google.
   • Under Measurement ID, add the measurement ID from the Google Analytics 4 property to which you want to send data. This is normally the same measurement ID that you have in your Google Tag. Once you add the measurement ID from your Google Tag, you will see the message Google Tag found in this container.
   • Under Event Name, select the previously configured variable gtag4.event (between double curly brackets {}), as shown in the image below.
   • Under Event Parameters, add the parameters items, currency, transaction_id, value, and tax.
   • Assign a value for each of them by adding the corresponding previously configured variable, as shown in the screenshot below. For example, for the value of the event parameter name items, add the previously configured data layer variable gtag4.items (between double curly brackets {}), as shown in the image below.

   

2. Under Triggering, create a trigger called 2checkout Event for the Google Analytics GA4 – 2 checkout event tag.

   • For Trigger Type select Custom Event from the options provided by Google.
   • As Event name type 2checkout event.
   • Under This trigger fires on, select All Custom Events.

   
   

3. Click Save and then Submit to Publish your settings.

Test your integration

To check a purchase in Google Analytics 4, follow the steps below:

1. Place an order in the 2Checkout shopping cart, using the template that has your Google Tag Manager code.
2. Log in to your Google Analytics 4 account.
3. Navigate to Monetization → Ecommerce purchases.
   
4. You will be able to see the number of purchases for your products and the revenue from your purchases.
   ​​​​​​

Overview

Use the updateCustomerInformation method to update the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.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;
}
$customerReference = 298084139;
$externalCustomerReference = 'Apitest123456'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference
try {
    $customerInfo = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}
catch (SoapFault $e) {
    echo "customerInfo: " . $e->getMessage();
    exit;
}
$customerInfo->Email = 'newemailaddressupdated@email.com';
try {
    $updatedCustomerInfo = $client->updateCustomerInformation($sessionID, $customerInfo);
}
catch (SoapFault $e) {
    echo "updatedCustomerInfo: " . $e->getMessage();
    exit;
}
var_dump("updatedCustomerInfo", $updatedCustomerInfo);

Overview

Reimbursing customers by issuing Total or Partial refunds for their orders is available via API. 

Issuing refunds can be done on the REST protocol via a POST request to /orders/{RefNo}/refund/ and on SOAP and JSON-RPC protocols via the issueRefund method.

Availability

Refunding an order via API is available for all accounts.

Requirements

• Order must be in status COMPLETE
• Order must not be older than 3 months
• The refunded amount must not be higher than the total amount of the order

Request Object

RefundItem Object

Request example

REST

{
  "amount": 23,
  "items": [
    {
      "LineItemReference": "my_product_1",
      "Quantity": 1
    }
  ],
  "comment": "requested by shopper",
  "reason": "CUSTOM_REASON"
}

SOAP and JSON-RPC Example

For the SOAP and JSON-RPC protocols, the issueRefund method needs to be called with the components of the requests in the parameter list. 

More information about issuing refunds can be found here (for JSON-RPC) and here (for SOAP).

The JSON-RPC object that needs to be sent would look like

{
   "jsonrpc":"2.0",
   "method":"issueRefund",
   "params":[
      "om7sb5uob2p2g9r321iif2v3hd7p5gkn", //session id
      "11370513",                         //orderRef
      "25.39",                           //amount 
      {
         "Quantity":1,                   //quantity of product refunded
         "Amount":25.39                  //amount of product refunded
      },
      "This is a comment",               //comment
      "Duplicate purchase"               //reason
   ],
   "id":2
}

 For SOAP requests, the following parameters need to be added to the SOAP request:

$refundedOrder = $client->issueRefund($sessionID, $orderReference, $amount, $items, $comment, $reason);

Response

The API will return a Boolean when issuing refunds. A true response means that the refund was registered successfully.

Error handling

A full list of errors returned by the issueRefund API method can be found here.

Overview

Use this method to attach a comment when placing a partner order.

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
require ('PATH_TO_ADD_PRODUCT'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/08Place_an_order/00Add_product_to_cart

$comment = 'YOUR_COMMENT';

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

require ('PATH_TO_PLACE_ORDER');

Errors