Skip to main content
knowledgecenter.2checkout.com

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

In order 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 MD5 algorithm and the Secret Key available in the 2Checkout Merchant Control Panel.

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');
$hash = hash_hmac('md5', $string, $key);

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

Authenticating on REST protocol

Authentication on REST is done via a 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}"

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

<?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('md5', $string, $key);
$payload = '';

$ch = curl_init();

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

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

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 = "YOURCODE123"; 
$key = "SECRET_KEY"; 
$now = gmdate('Y-m-d H:i:s'); 

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

try {
    $sessionID = $soapClient->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}

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
$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('md5', $string, $key);

$i = 1;

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


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

Alternative 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 addition to the existing HMAC_MD5.

In order to start using SHA2 and SHA3 hashing algorithms, contact Merchant support for activation.

Generating the hash needed to authenticate using SHA2 or SHA3 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) - either sha256 or sha3-256.

REST Example

$date = gmdate('Y-m-d H:i:s');
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hashAlgorithm = 'sha256';
$hash = hash_hmac($hashAlgorithm , $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=\"{$hashAlgorithm}\"",
    'Cookie: XDEBUG_SESSION=PHPSTORM'
);

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

JSON-RPC Example

$merchantCode = "YOUR_MERCHANT_CODE";
$key = "YOUR_SECRET_KEY";
$date = gmdate('Y-m-d H:i:s');
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('sha256', $string, $key);
$i = 1;
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '6.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, $date, $hash, 'sha256');//gmdate('Y-m-d H:i:s')
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);

SOAP Example

$merchantCode = "YOUR_MERCHANT_CODE";
$key = "YOUR_SECRET_KEY";
$date = gmdate('Y-m-d H:i:s');
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('sha256', $string, $key);
try {
$sessionID = $client->login($merchantCode, $date, $hash, 'sha256');
print_r($sessionID);
} catch (SoapFault $e) {
echo $e->getMessage();
}
$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.
  • Was this article helpful?