Creating the SOAP HEADER in the query

To create the SOAP HEADER:

  1. Add a new header entitled shopId with a value equal to the shop ID.
    Its value is available in your Merchant Back Office by selecting the Settings > Shop > Keys tab.
  2. Add a new header entitled timestamp

    Its value specifies the numerical representation of the date and time of the query in the ISO 8601 format - W3C and UTC.

    Example of code in PHP:
    $timestamp = gmdate("Y-m-d\TH:i:s\Z");
    Result: 2014-10-31T16:38:19Z
  3. Add a new header entitled mode.
    Its value allows to define the transaction type. The attribute value can be set to TEST (for a test transaction) or PRODUCTION (for a real transaction).
  4. Add a new header entitled requestId.

    The requestId attribute is an UUID (Universal Unique IDentifier). Its value allows to compute the authentication token.

    The requestId attribute must be generated by the merchant website. Its format must respect the following syntax: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx (where M=1,2,3,4,5 and N=8,9,A,B).

    • Example of code in JAVA:
      java.util.UUID.randomUUID().toString();
    • Example of code in PHP:
      function gen_uuid() {
      	if (function_exists('random_bytes')) {
      		// PHP 7
      		$data = random_bytes(16);
      	} elseif (function_exists('openssl_random_pseudo_bytes')) {
      		// PHP 5.3, Open SSL required
      		$data = openssl_random_pseudo_bytes(16);
      	} else {	
      		return sprintf(
      			'%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
      			mt_rand(0, 0xffff),
      			mt_rand(0, 0xffff),
      			mt_rand(0, 0xffff),
      			mt_rand(0, 0x0fff) | 0x4000,
      			mt_rand(0, 0x3fff) | 0x8000,
      			mt_rand(0, 0xffff),
      			mt_rand(0, 0xffff),
      			mt_rand(0, 0xffff)
      		);
      	}
      	
      	$data[6] = chr(ord($data[6]) & 0x0f | 0x40); // set version to 100
      	$data[8] = chr(ord($data[8]) & 0x3f | 0x80); // set bits 6 & 7 to 10
      	
      	return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
      }
    • Example of code in ASP.NET:
      System.Guid.NewGuid().toString();
  5. Add a new header entitled authToken
    To obtain its value:
    1. Concatenate the requestId and timestamp attributes without a separator.

      Example of concatenation with:

      • requestId = 04967dae-af01-43ff-a7d8-f3f228b9b1c2
      • timestamp = 2014-10-31T16:38:19Z
        "04967dae-af01-43ff-a7d8-f3f228b9b1c22014-10-31T16:38:19Z"
    2. Apply the HMAC_SHA256 algorithm to the obtained string using the value of the test or production key (depending on the value of mode) as shared key.

    3. Encode the result in Base64.
    • Example of implementation in JAVA 7:
    public String hmacsha256(String stringToSign , String key ){
    	try {            
    		byte[] bytes = encode256 ( key .getBytes( "UTF-8" ), stringToSign .getBytes( "UTF-8" ));
    		return Base64.encodeBase64String( bytes );
    	} catch (Exception  e ){
    		throw new RuntimeException( e );
    	} 
    }    
    private static byte[] encode256(byte[]keyBytes, byte[] text ) throws NoSuchAlgorithmException, InvalidKeyException {
    	Mac  hmacSha1 ;
    	try {
    		hmacSha1 = Mac.getInstance ( "HmacSHA256" );
    	} catch (NoSuchAlgorithmException  nsae ){
    		hmacSha1 = Mac.getInstance ( "HMAC-SHA-256" );
    	}
    	SecretKeySpec macKey = new SecretKeySpec( keyBytes, "RAW" );
         hmacSha1.init( macKey );
    	return hmacSha1 .doFinal( text );  
    }

    Note: the implementation is based on the Mac class of the javax.crypto package.

    Example of call in JAVA:

    hmacsha256("04967dae-af01-43ff-a7d8-f3f228b9b1c22014-10-31T16:38:19Z", "1234567887654321")

    • Example of implementation in PHP:
    //$data est la concaténation des attributs requestId et timestamp
    //$shopKey est la valeur de la clé
    
    <?php $authToken = base64_encode(hash_hmac('sha256',$data, $shopKey, true));?>

    • Example of implementation in ASP.NET:
    private static byte[] StringEncode (string text)
    {
    	var encoding = new ASCIIEncoding();
    	return encoding.GetBytes(text);
    }
    private static string HashEncode(byte[] hash)
    {
    	return System.Convert.ToBase64String(hash)
    }
    private static byte[] HashHMAC (byte[] key, byte[] message)
    {
    	var hash = new HMACSHA256(key);
    	return hash.ComputeHash(message);
    }
    public String HmacSha256(String stringToSign, String key)
    {
    	return HashEncode(HashHMAC(StringEncode(key), StringEncode(stringToSign)));
    }
    Example of call in ASP.NET:
    HmacSha256("RF5GJlpZwcra2N7Ie/04Xn/SxFVnqy/61Yr6F6lFrHo=", "1234567887654321")
    Result:
    <soapHeader:authToken>NxoFUSsTqmMjwaDzTXyCN4nNpMOVJKb5UxHdS9TBuTg=</soapHeader:authToken>