updates RSS feed

Retrieve SKU details by ID

Overview

Use the getSkuDetails method to retrieve SKU details based on its ID.

Parameters

Parameters Type/Description
sessionID Required (string)
  Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
skuCode Required (string)
  Unique identifier of the SKU.

Request Example

<?php
require ('PATH_TO_AUTH');

$sku = 'YOUR_SKU_CODE';

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'getSKUDetails';
$jsonRpcRequest->params = array($sessionID, $sku);
$jsonRpcRequest->id = $i++;

$getOrder = callRPC($jsonRpcRequest, $host);
var_dump($getOrder);

Response Example

{
"PricingConfigurationCode":"{PricingConfigurationCode}",
"ProductCode":"{ProductCode}",
"Currency":"{Currency}",
"PriceOptions":[{PriceOption1},{PriceOption2}],
"PurchaseType":"{PurchaseType}",
"FromQuantity":"{FromQuantity}",
"ToQuantity":"{ToQuantity}"
}

 

Add coupon

Overview

Use the addPromotionCoupon method to add single or multiple coupons to a promotion. Using the addPromotionCoupon for a promotion that is set to apply automatically will change the promotion type to the manual flow, where customers are required to enter the coupon code to receive the discount.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to add coupons to.

promotionCoupon

Required (object)

 

type

Required (string)

 

 

Coupon type. Available values:

  • SINGLE, use in conjunction with Code
  • MULTIPLE, use in conjunction with Codes

 

Code/Codes

Required (string / array of strings)

 

 

Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE).

Response

Parameter Type/Description
promotionCoupon Object

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'addPromotionCoupon',
'params' => array($sessionID, $promotionCode, $promotionCoupon)
);
var_dump (callRPC($jsonRpcRequest, $host));

Enable/Disable products

Overview

Use the setProductStatus method to enable / disable products for your account. 

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

productCode

Required (string)

 

Use this object to configure your subscription plan/products.

 

You can set all Product parameters except AvangateID. The 2Checkout system sets the unique product ID. The AvangateID is not editable.

Status

Required (Boolean)

 

True or False, depending on whether you want to enable or disable a subscription plan/product.

Request

<?php

require ('PATH_TO_AUTH');

$productCode = "YourProductCode";

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'setProductStatus',
'params' => array($sessionID, $productCode, true)
);

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

?>

 

Response

bool(true)

Next renewal price

Overview

Use the methods below to set or retrieve information related to the next renewal price to be charged on a customer's subscription.

 

Add promotion coupon

Overview

Use the addPromotionCoupon method via JSON-RPC API 4.0 to add single or multiple coupons to a promotion.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to add coupons to.

promotionCoupon

Required (object)

 

type

Required (string)

 

 

Coupon type. Available values:

  • SINGLE, use in conjunction with Code
  • MULTIPLE, use in conjunction with Codes

 

Code/Codes

Required (string / array of strings)

 

 

Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE).

Response

Parameter Type/Description
promotionCoupon Object

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    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'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

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

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.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.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $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);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'addPromotionCoupon',
'params' => array($sessionID, $promotionCode, $promotionCoupon)
);
var_dump (callRPC($jsonRpcRequest, $host));

API Authentication

Overview

The 2Checkout API requires you to authenticate for any requests. Follow the steps below to learn how to authenticate in order to use the 2Checkout API.

How to authenticate

This is achieved via digest access authentication, using your Merchant Code & Secret Key. These can be found in your 2Checkout Merchant Control Panel, under Integrations → Webhooks & API.

merchant code_secret Key in control panel.png

To authenticate, you must first generate a hash code that will then be used together with your Merchant Code. The string used in the hash function is generated by concatenating the following values (in this order):

  1. Length of your Merchant Code
  2. Merchant Code
  3. Length of the current DateTime formated as Y-m-d H:i:s
  4. Current DateTime 

For example, for Merchant Code “YOURCODE123“ trying to authenticate on 2020-06-18 08:05:46 GMT, the string that needs to be hashed would look like: “11YOURCODE123192020-06-18 08:05:46”.

Once the string has been generated, this needs to be hashed using the SHA algorithm and the Secret Key available in the 2Checkout Merchant Control Panel. 

Hashing algorithms available

Starting with API 6.0, authentication in the API supports the 256-bit variant of each of the two SHA (Secure Hash Algorithm) families, meaning SHA2 and SHA3.

In PHP, this would look like:

$merchantCode = "YOUR_MERCHANT_CODE";  
$key = "YOUR_SECRET_KEY";  

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');  

$algo = "SHA3-256"; 

$hash = hash_hmac($algo, $string, $key);

Authenticating on REST protocol

Authentication on REST is done via an X-Avangate-Authentication header provided on all requests. The X-Avangate-Authentication header value contains the Merchant Code, request DateTime, and the hash generated above. 

The format of the header is:

X-Avangate-Authentication: code="{MERCHANT_CODE}" date="{REQUEST_DATE_TIME}" hash="{HASH}" algo="{ALGO}"

Once the hash has been generated, this can be used to authenticate on any of the three protocols.

<?php 
$merchantCode = "YOUR_MERCHANT_CODE"; 
$key = "YOUR_SECRET_KEY"; 
$date = gmdate('Y-m-d H:i:s'); 
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date; 

# sha256 or sha3-256 
$hashAlgorithm = 'sha256'; 
$hash = hash_hmac($hashAlgorithm , $string, $key); 
$payload = ''; 

$ch = curl_init(); 

$headerArray = [ 
"Content-Type: application/json", 
"Accept: application/json", 
"X-Avangate-Authentication: code=\"{$merchantCode}\" date=\"{$date}\" hash=\"{$hash}\" algo=\"{$hashAlgorithm}\"" 
];
 
curl_setopt($ch, CURLOPT_URL, $host); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); 
curl_setopt($ch, CURLOPT_HEADER, FALSE); 
curl_setopt($ch, CURLOPT_POST, FALSE); 
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
curl_setopt($ch, CURLOPT_SSLVERSION, 0); 
curl_setopt($ch, CURLOPT_HTTPHEADER, $headerArray); 

$response = curl_exec($ch);

Authenticating on SOAP protocol

Authentication on SOAP is done via the login method, using the hash generated above. Once the session id is returned by the login method, this will be used in all subsequent API requests.  

A full-working example in PHP for SOAP login looks like:

<?php 
$merchantCode = "YOUR_MERCHANT_CODE"; 
$key = "YOUR_SECRET_KEY"; 
$date = gmdate('Y-m-d H:i:s'); 
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date; 

# sha256 or sha3-256 
$hashAlgorithm = 'sha256'; 
$hash = hash_hmac($hashAlgorithm, $string, $key); 

try { 
    $sessionID = $client->login($merchantCode, $date, $hash, $hashAlgorithm); 
    print_r($sessionID); 
} catch (SoapFault $e) { 
    echo $e->getMessage(); 
}

Authenticating on RPC protocol

Authentication on RPC is done via the login method, using the hash generated above. Once the session id is returned by the login method, this will be used in all subsequent API requests.

A full-working example in PHP for RPC login looks like:

<?php 
$merchantCode = "YOUR_MERCHANT_CODE"; 
$key = "YOUR_SECRET_KEY"; 
$date = gmdate('Y-m-d H:i:s'); 
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date; 
 
# sha256 or sha3-256 
$hashAlgorithm = 'sha256'; 
$hash = hash_hmac($hashAlgorithm , $string, $key); 

$i = 1; 
$jsonRpcRequest = new stdClass(); 
$jsonRpcRequest->jsonrpc = '6.0'; 
$jsonRpcRequest->method = 'login'; 
$jsonRpcRequest->params =[$merchantCode, $date, $hash, $hashAlgorithm]; 
$jsonRpcRequest->id = $i++; 
$sessionID = callRPC($jsonRpcRequest, $host);

SHA Algorithm

Generating the hash needed to authenticate using SHA-2 or SHA-3 is similar to using MD5, with the note that in the list of parameters, the hashing algorithm must be specified (the last parameter in the list). 

REST Example

<?php
$merchantCode = "YOURCODE123";
$key = "SECRET_KEY";

$apiVersion = '6.0';
$resource = 'leads';
$host = "https://api.2checkout.com/rest/".$apiVersion."/".$resource."/"; 

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

$ch = curl_init();

$headerArray = array( 
    "Content-Type: application/json", 
    "Accept: application/json", 
    "X-Avangate-Authentication: code=\"{$merchantCode}\" date=\"{$date}\" hash=\"{$hash}\" algo=\"{$algo}\"" 
);

curl_setopt($ch, CURLOPT_URL, $host); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); 
curl_setopt($ch, CURLOPT_HEADER, FALSE); 
curl_setopt($ch, CURLOPT_POST, FALSE); 
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
curl_setopt($ch, CURLOPT_SSLVERSION, 0); 
curl_setopt($ch, CURLOPT_HTTPHEADER, $headerArray); 
 
$response = curl_exec($ch);

SOAP Example

<?php
$host  = "https://api.2checkout.com";
$soapClient = new SoapClient($host . "/soap/6.0/?wsdl", array(
    'location' => $host . "/soap/6.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

$merchantCode = "YOURCODE123";
$key = "SECRET_KEY";
$now = gmdate('Y-m-d H:i:s');

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hash_hmac($algo, $string, $key);

try {
    $sessionID = $soapClient->login($merchantCode, $now, $hash);
}

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

JSON-RPC Example

<?php 
$host = 'https://api.2checkout.com/rpc/6.0/'; 

function callRPC($Request, $host, $Debug = true) { 
    $curl = curl_init($host); 
    curl_setopt($curl, CURLOPT_POST, 1); 
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); 
    curl_setopt($curl, CURLOPT_VERBOSE, true); 
    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')); 
    $RequestString = json_encode($Request); 
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString); 
    if ($Debug) {
        $RequestString; 
    } 
    $ResponseString = curl_exec($curl); 
    if ($Debug) { 
        $ResponseString; 
    } 
    if (!empty($ResponseString)) { 
        var_dump($ResponseString); 
        $Response = json_decode($ResponseString); 
        if (isset($Response->result)) { 
            return $Response->result; 
        } 
        if (!is_null($Response->error)) { 
            var_dump($Request->method, $Response->error); 
        } 
    } else { 
        return null; 
    }
}

$merchantCode = "YOURCODE123";  
$key = "SECRET_KEY";  
$date = gmdate('Y-m-d H:i:s'); 

$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date; 
$hash = hash_hmac($algo, $string, $key); 

$i = 1;

$jsonRpcRequest = new stdClass(); 
$jsonRpcRequest->jsonrpc = '2.0'; 
$jsonRpcRequest->method = 'login'; 
$jsonRpcRequest->params = array($merchantCode, $date, $hash, $algo); 
$jsonRpcRequest->id = $i++;


$sessionID = callRPC($jsonRpcRequest, $host);

Integration test cases

Testing your integration should be straightforward:

  • For SOAP and JSON-RPC, run a request on the login method and check if you are getting a successful result with an alphanumeric session id.
  • For REST, run a GET call or search request against a simple resource like payouts or leads. While the result may be empty if you do not have any activity yet, the HTTP response should be 200 OK, letting you know that the authentication was successful.

Testing your API with Postman

   You can test your API using Postman only with the SHA256 version of the algorithm, as Postman does not support SHA3.

Postman example

Postman 2 example

Retrieve order status information

Overview

Get information about an existing order.

Requirements

Parameters

Parameters Type/Description
sessionID Required (String)
  Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
refNo Required (String)
  The unique, system-generated identifier of a partner order.

Response

Parameters Type/Description
Order Object

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

$refNo = 'YOUR_ORDER_REFERENCE_NUMBER';

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

Errors

Error Description

INVALID_PARTNER

No partner is set.

INVALID_REFERENCE

The provided order reference is invalid.

 

Remove product from cart

Overview

Use this method to remove a product that was added to the shopping cart, during the current session.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
productId Required (Integer)
  Unique product identifier from the Avangate system.
priceOptions Optional (StringArray)
 

Array of price options codes. These identifiers mark the individual options inside pricing options configuration groups.

This parameter must match exactly the pricing option combination of the product added to the cart in order for the product to be removed.

 

Partner orders can involve the same product, bot ordered in multiple instances, each with different pricing options.

 

Can be NULL.
quantity Optional (Integer)
  Defines the number of product units added to cart that should be removed. If no quantity info is provided, the product is completely removed from cart. Can be NULL.

Response

Parameters Type/Description
Result Boolean
  True or false

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

$productId = 'PRODUCT_ID_TO_REMOVE';
$quantity = QUANTITY_TO_REMOVE;
$priceOptions = array(
'YOUR_PRICE_OPTIONS',
);

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'deleteProduct',
'params' => array($sessionID, $productId, $quantity, $priceOptions)
);

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

Errors

Error Description

EMPTY_CART

The shopping cart is empty.

PRODUCT_ERROR

There is no product with the specified settings in cart.

 

Top 5 affiliate program pillars for success

How do you build a successful affiliate program? What do you need to do that? Well, we cannot cover in one webinar the whole process, but you should definitely keep your eyes on some pillars around which you can elaborate.



Julie Avila, VP of Client Services at Schaaf-PartnerCentric, and Cristian Miculi, Senior Manager of Alliances for 2Checkout share more on 5 of the most important pillars of building and optimizing an affiliate program.

You'll find out more about:

  • Getting a technical integration done right
  • What to look at when approving affiliates
  • How to structure your payouts scheme in order to best motivate affiliates
  • What to watch out for when it comes for affiliates fraud
  • How to optimize your affiliate program from a business perspective
 Top 5 Affiliate Program Pillars for Success

 

Retrieve account's time zone

Overview

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

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.

Response

Parameters Type/Description

Timezone

String

 

The time zone you selected or the default GMT+02:00 time zone of the 2Checkout system.

Request

<?php

require ('PATH_TO_AUTH');

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

 

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo