Overview

Use the UpSellSettings object to update the merchant's displayType via SOAP API 6.0. The 2Checkout Public API supports upsell campaigns which means you can invite your customers to purchase upgrades or add-ons from your own product catalog.

Parameters

Overview

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

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXTERNAL_CUSTOMER_REFERENCE'; // Optional, but if you include it it needs to belong to the same customer as the internal Avangate customer reference

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

$existingCustomer = callRPC((Object)$jsonRpcRequest, $host, true);

// Update email
$existingCustomer->Email = 'newemailaddress@email.com';

// New Credit object (optional)
$existingCustomer->Credit = new stdClass();
$existingCustomer->Credit->Limit = 51.0;       // float
$existingCustomer->Credit->Remaining = 21.0;   // float
$existingCustomer->Credit->Currency = 'EUR';   // string

$UpdateEndUserSubscriptions = false; // Optional, but if true the changes made on customer info are pushed to all subscriptions from this customer.

// Send updated customer info
$jsonRpcRequest = array(
    'method' => 'updateCustomerInformation',
    'params' => array($sessionID, $existingCustomer, $UpdateEndUserSubscriptions),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Overview

Use the updateDisplayType method to change the upselling display type for your campaigns between the values "overlay" or "interstitial".

Request parameters

Response

The updateDisplayType method will return the  UpsellingDisplayType value after the update.

Request sample

<?php 

          require ('PATH_TO_AUTH'); 

          $textObj = new stdClass(); 
          $textObj->UpsellingDisplayType = "interstitial"; 

          try { 

            $upSellSettingsResponse = $client->updateDisplayType($sessionID, $textObj); 

          } catch (SoapFault $e) { 

            echo  $e->getMessage(); 

          } 

Overview

Use the updateUpSellCampaign method to update an upsell campaign via SOAP API 6.0.

Request Parameters

Request example

<?php
require ('PATH_TO_AUTH');

$upsell = new \stdClass();

$upsellCode = 'fc580e11-09e4-483f-b73e-cd0f460bcd9d';

$upsell->Name = 'December 2020 upsell campaign’;
$upsell->StartDate = '2020-12-21';
$upsell->EndDate = '2020-12-25';
$upsell->DisplayForManualRenewals = false;

// setup percent discount
$discountPercent = new \stdClass();
$discountPercent->Type = 'PERCENT';
$discountPercent->Value = 5;

// setup fixed discount
$discountFixed = new \stdClass();
$discountFixed->Type = 'FIXED';
$discountValues = [
    'USD' => 10,
    'EUR' => 8,
    'TRY' => 80,
    'RUB' => 1100,
];
$dv = [];
foreach ($discountValues as $curr => $amt) {
    $disc = new \stdClass();
    $disc->Currency = $curr;
    $disc->Amount = $amt;

    $dv[] = $disc;
}
$discountFixed->Values = $dv;

// assign discount
$upsell->Discount = $discountPercent;
# OR
# $upsell->Discount = $discountFixed;


// setup primary product
$primaryProduct = new \stdClass();
$primaryProduct->Code = $productCode;
$primaryProduct->Quantity = 1;
$ppPriceOptionGroup1 = new \stdClass();
$ppPriceOptionGroup1->Code = 'OPTGRP2';
$ppPriceOptionGroup1Option = new \stdClass();
$ppPriceOptionGroup1Option->Code = 'OptGrp2Code2';
$ppPriceOptionGroup1->Options = [$ppPriceOptionGroup1Option];

$ppPriceOptionGroup2 = new \stdClass();
$ppPriceOptionGroup2->Code = 'interval_scale_grp1';
$ppPriceOptionGroup2Option = new \stdClass();
$ppPriceOptionGroup2Option->Code = 'interval_scale_grp1-1-10';
$ppPriceOptionGroup2Option->Value = '6';
$ppPriceOptionGroup2->Options = [$ppPriceOptionGroup2Option];

$primaryProduct->PriceOptions = [$ppPriceOptionGroup1, $ppPriceOptionGroup2];
$upsell->PrimaryProduct = $primaryProduct;

// setup recommended product
$recommProduct = new \stdClass();
$recommProduct->Code = $recProductCode;
$recommProduct->Quantity = 0; // stands for “match quantity” 
$rpPriceOptionGroup1 = new \stdClass();
$rpPriceOptionGroup1->Code = 'CHECKB_LIST';
$rpPriceOptionGroup1Option1 = new \stdClass();
$rpPriceOptionGroup1Option1->Code = 'chk1';
$rpPriceOptionGroup1Option2 = new \stdClass();
$rpPriceOptionGroup1Option2->Code = 'chk3';
$rpPriceOptionGroup1->Options = [$rpPriceOptionGroup1Option1, $rpPriceOptionGroup1Option2];
$recommProduct->PriceOptions = [$rpPriceOptionGroup1];
$upsell->RecommendedProduct = $recommProduct;

$upsell->Enabled = true;

// setup languagte descriptions / texts
$enDescription = new \stdClass();
$enDescription->Language = 'EN';
$enDescription->Text = 'Buy <!--{RECOMMENDED_PRODUCT_NAME}--> for just <!--{RECOMMENDED_PRODUCT_PRICE}--> until Dec 25th';
$upsell->Description = [$enDescription];

try {
    $upsellResponse = $client->updateUpsellCampaign($sessionID, $upsellCode, $upsell);
} catch (SoapFault $e) {
    echo  'SOAP Exception caught: ' . $e->getMessage()
}

Response

Overview

Use the login method for the authentication process in the 2Checkout system.

Parameters

Response

Request

To create the HMAC_SHA256 source string use your merchant code (available here) and the date of the request, prefixing them with the length in bytes of each respective value, along with your account’s secret key (for UTF-8 characters the length in bytes might be longer that the string length). For example:

Request

<?php

/**
 * @throws JsonException
 */
function callRPC($Request, $host) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
    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'));
    $RequestString = json_encode($Request, JSON_THROW_ON_ERROR);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);

    $ResponseString = curl_exec($curl);

    if (!empty($ResponseString)) {
        echo($ResponseString);
        $Response = json_decode($ResponseString, false, 512, JSON_THROW_ON_ERROR);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            echo("Method: {$Request->method}" . PHP_EOL);
            echo("Error: {$Request->error}" . PHP_EOL);
        }
    } else {
        return null;
    }
    return null;
}

$host = 'https://api.avangate.com/rpc/3.0/';

$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

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$algo = "sha256";
$hash = hash_hmac($algo, $string, $key);

$i = 1;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash, $algo);
$jsonRpcRequest->id = $i++;

try {
    $sessionID = callRPC($jsonRpcRequest, $host);
    echo("Auth token: {$sessionID}" . PHP_EOL);
} catch (JsonException $e) {
    echo("Error: {$e->getMessage()}" . PHP_EOL);
}

Overview

Use the deleteUpSellCampaign method via SOAP API 6.0 to permanently delete an upsell campaign in any status (active, disabled, expired).

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 = 'deleteUpsellCampaign';
    public const ADDITIONAL_OPTIONS = null;
    public const PAYLOAD = "f4b76ac3-6b2e-492f-a468-b34103876470";
}

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

• 204 - 'No content' if SUCCESS
• 4xx if FAILED with distinct error messages

Error handling

Overview

Use the setSku method to create a valid combination of elements (code) for a specific product. 

In case there is an active SKU schema available for that Product Code and Pricing Configuration Code, when setting new SKUs the entire existing schema will be overwritten with the new values. The same validations that are applied to the CSV file import in the Merchant Control Panel are applicable to the API as well.

Product SKUs created via API will also be available in the Merchant Control Panel for manual update (Dashboard → Setup → Products → Edit product → Information → SKU Manager (SKU list Tab).

Request

<?php

require ('PATH_TO_AUTH');

$product = new \stdClass();
$product->ProductCode = "6B3CB17DDA_COPY1";

$skuPricingOption1 = new \stdClass();
$skuPricingOption1->Code = "E684EC99B0";

$skuDetail1 = new \stdClass();
$skuDetail1->ProductSKU = "Product_Test_SKU_001022";
$skuDetail1->Currency = "USD";
$skuDetail1->FromQty = 1;
$skuDetail1->ToQty = 3
$skuDetail1->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 1";
$skuGroupOption->Value = "option_code_1";

$skuGroup->Options = [$skuGroupOption];

$skuDetail1->Groups = [$skuGroup];
$skuDetail1->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrlXauuZOojh8cww==";

$skuDetail2 = new \stdClass();
$skuDetail2->ProductSKU = "Product_Test_SKU_001023";
$skuDetail2->Currency = "USD";
$skuDetail2->FromQty = 1;
$skuDetail2->ToQty = 3
$skuDetail2->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 2";
$skuGroupOption->Value = "option_code_2";

$skuGroup->Options = [$skuGroupOption];

$skuDetail2->Groups = [$skuGroup];
$skuDetail2->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrmXauuZOojjccxw==";

$skuPricingOption1->Details = [$skuDetail1, $skuDetail2];

$product->SkuPricingOptions = [$skuPricingOption1];

$jsonRpcRequest = array (
    'method' => 'setSku',
    'params' => array($sessionID, [$product]),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response

class stdClass#7 (3) {
  public $ProductCode =>
  string(16) "6B3CB17DDA_COPY1"
  public $PricingConfigurations =>
  array(1) {
    [0] =>
    class stdClass#8 (6) {
      public $Code =>
      string(10) "E684EC99B0"
      public $Currencies =>
      array(1) {
        [0] =>
        class stdClass#9 (1) {
          public $Code =>
          string(3) "EUR"
        }
      }
      public $PurchaseTypes =>
      array(1) {
        [0] =>
        class stdClass#10 (1) {
          public $Code =>
          string(7) "RENEWAL"
        }
      }
      public $QuantityIntervals =>
      array(0) {
      }
      public $PriceOptionGroups =>
      array(0) {
      }
      public $SkuCollection =>
      array(1) {
        [0] =>
        class stdClass#11 (2) {
          public $ProductCode =>
          string(16) "6B3CB17DDA_COPY1"
          public $SkuPricingOptions =>
          array(1) {
            [0] =>
            class stdClass#12 (3) {
              public $Code =>
              string(10) "E684EC99B0"
              public $Details =>
              array(8) {
                [0] =>
                class stdClass#13 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008899"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#14 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#15 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78164;}}"
                }
                [1] =>
                class stdClass#16 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008902"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#17 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#18 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(6) "a:0:{}"
                }
                [2] =>
                class stdClass#19 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008900"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#20 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#21 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78165;}}"
                }
                [3] =>
                class stdClass#22 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008901"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#23 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#24 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78166;}}"
                }
                [4] =>
                class stdClass#25 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008907"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#26 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#27 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78164;}}"
                }
                [5] =>
                class stdClass#28 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008910"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#29 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#30 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(6) "a:0:{}"
                }
                [6] =>
                class stdClass#31 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008908"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#32 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#33 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78165;}}"
                }
                [7] =>
                class stdClass#34 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008909"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#35 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#36 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78166;}}"
                }
              }
              public $Errors =>
              array(0) {
              }
            }
          }
        }
      }
    }
  }
  public $Errors =>
  array(0) {
  }
}

Overview

Use the getAvailableCurrencies method via SOAP API 6.0 to get the list of available currencies. If the countryCode parameter is added, the paymentMethod parameter also becomes mandatory (you need to use both parameters or none).

Request Parameters

Request Example

<?php

$apiVersion = '6.0';
$host = "http://api.avangate.local:8081/soap/".$apiVersion."/";

$client = new SoapClient($host."?wsdl", array('location' => $host, 'cache_wsdl' => WSDL_CACHE_NONE));
$client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

$merchantCode = "124231873235";
$key = "%&7+J[Q7T!B!1(z1e7&a";

$date = gmdate('Y-m-d H:i:s');
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);

try {
    echo "login \r\n";
    $sessionID = $client->login($merchantCode, $date, $hash);
} catch (SoapFault $e) {
    echo  $e->getMessage();
}

print_r("session: ". $sessionID);

$countryCode = 'ro';
$paymentMethod = 'CC';

try {
//    $response = $client->getAvailableCurrencies($sessionID);
    $response = $client->getAvailableCurrencies($sessionID, $countryCode, $paymentMethod);
}

catch (SoapFault $e) {
    echo "VendorSettingsController.php: " . $e->getMessage();
    exit;
}
var_dump($response);

Response

Response Example

[
  {
      "Code":"USD",
      "ISO3DigitCode":"840",
      "Label":"United States Dollar",
      "Symbol":"$",
      "SymbolPosition":"left",
      "DecimalSeparator":".",
      "UnitSeparator":",",
      "Decimals":"2"
   }
] 

Overview

Retrieve the current cart session content, and learn insights about your customers actions in cart.

You can obtain the VAT or sales TAX based on current cart items, prefill the customer information based on the subscription reference, or get the price applied in cart by using the API method from below.