API hutko

Signature validation example of response_url and server_callback_url  POST response

function getSignature( $merchant_id , $password , $params = array() ){
 $params['merchant_id'] = $merchant_id;
 $params = array_filter($params,'strlen');
 ksort($params);
 $params = array_values($params);
 array_unshift( $params , $password );
 $params = join('|',$params);
 return(sha1($params));
}

Example file Signature.php

 
namespace Ipsp;
/**
 * Class Signature
 * @package Ipsp
 */
class Signature {
    /**
     * @var
     */
    private static $password;
    /**
     * @var
     */
    private static $merchant;
    /**
     * Set merchant password
     * @param String $password
     * @return mixed
     */
    public static function password($password){
        self::$password = $password;
    }
    /**
     * Set merchant id
     * @param String $merchant
     * @return mixed
     */
    public static function merchant( $merchant ){
        self::$merchant = $merchant;
    }
    /**
     * Generate request params signature
     * @param array $params
     * @return string
     */
    public static function generate(Array $params){
        $params['merchant_id'] = self::$merchant;
        $params = array_filter($params,'strlen');
        ksort($params);
        $params = array_values($params);
        array_unshift( $params , self::$password );
        $params = join('|',$params);
        return(sha1($params));
    }
    /**
     * Sign params with signature
     * @param array $params
     * @return array
     */
    public static function sign(Array $params){
        if(array_key_exists('signature',$params)) return $params;
        $params['signature'] = self::generate($params);
        return $params;
    }
    /**
     * Clean array params
     * @param array $data
     * @return array
     */
    public static function clean(Array $data){
        if( array_key_exists('response_signature_string',$data) )
            unset( $data['response_signature_string'] );
        unset( $data['signature'] );
        return $data;
    }
    /**
     * Check response params signature
     * @param array $response
     * @return bool
     */
    public static function check(Array $response){
        if(!array_key_exists('signature',$response)) return FALSE;
        $signature = $response['signature'];
        $response  = self::clean($response);
        return $signature == self::generate($response);
    }
}

Signature verification with class Signature

require_once 'Signature.php';
# import Signature class from namespace
use Ipsp\Signature;
# setup merchant id and password
Signature::merchant(1700002);
Signature::password('test');
if(Signature::check($response)){
    echo 'signature is valid. Now we can complete purchase';
} else{
    echo 'bad signature throw error'
}

Solving problems with signature parameter generation and validation

There are two typical situations when the signature parameter verification error occurs. 

1. If the request for the purchase/recurring payment, reverse/status or any other request with the parameter signature is sent from merchant to the hutko API, and the response is returned: Invalid signature.
2. If the hutko server returned a POST response or callback to server_callback_url or response_url, but when you try to generate a signature and compare it with the signature parameter from the POST response, the signatures do not match

Consider both cases:

1. If the request is sent to the hutko API, and the response is returned as “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1700002|demo order 789|Demo123456`”, perform the following checks:
   • check that you used the correct payment key from the Technical Settings in the Merchant Portal
   • if the request contains non-Latin encoding, then it is sent in encoding UTF-8
   • make sure that a parameter with a value of 0 is not null by your programming language
   • log the line in the program code to which you apply SHA1 during the generation of the signature parameter. Compare it with the string that returned in the error text (marked in red): “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1700002|demo order 789|Demo123456`“. Note that in the text of the error the merchant’s payment key will be masked by *
   • check if you send empty parameters in the API request. If yes, then in the line that participates in the signature, the | separator symbol for each such empty parameter does not need to be included
   • if you are developing in the PHP programming language, use the example function getSignature:

     function getSignature( $merchant_id , $password , $params = array() ){
      $params['merchant_id'] = $merchant_id;
      $params = array_filter($params,'strlen');
      ksort($params);
      $params = array_values($params);
      array_unshift( $params , $password );
      $params = join('|',$params);
      return(sha1($params));
     }
     

   • make sure that the result of the SHA1 function is lowercase. Correct: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Incorrect: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA
   • make sure that the signature parameter is not included in your signature calculation
   • make sure that if you use the API endpoint /api/recurring, then you only include the necessary parameters in the signature, but not those from the /api/redirect endpoint
2. If the server hutko returned a POST response to the pages specified in the server_callback_url or response_url parameters, but when you try to generate a signature and compare it with the signature parameter in the POST response, the signature does not match

Response example from hutko (JSON):

{
 "rrn": "429417347068",
 "masked_card": "444455XXXXXX6666",
 "sender_cell_phone": "",
 "response_signature_string": "**********|3324000|EUR|3324000|027440|444455|VISA|EUR|444455XXXXXX6666|1700002|
  14#1500639628|approved|21.07.2017 15:20:27|51247263|card|success|0|429417347068|test@example.com|0|purchase",
 "response_status": "success",
 "sender_account": "",
 "fee": "",
 "rectoken_lifetime": "",
 "reversal_amount": "0",
 "settlement_amount": "0",
 "actual_amount": "3324000",
 "order_status": "approved",
 "response_description": "",
 "verification_status": "",
 "order_time": "21.07.2017 15:20:27",
 "actual_currency": "EUR",
 "order_id": "14#1500639628",
 "parent_order_id": "",
 "merchant_data": "",
 "tran_type": "purchase",
 "eci": "",
 "settlement_date": "",
 "payment_system": "card",
 "rectoken": "",
 "approval_code": "027440",
 "merchant_id": 1700002,
 "settlement_currency": "",
 "payment_id": 51247263,
 "product_id": "",
 "currency": "EUR",
 "card_bin": 444455,
 "response_code": "",
 "card_type": "VISA",
 "amount": "3324000",
 "sender_email": "test@example.com",
 "signature": "47bdcaf61b99edd31e3ec7913225a14d2ce07575"
}

To diagnose the cause of a signature mismatch, follow these steps:

• make sure that the parameter with a value of 0 is not brought to empty or null in your programming language
• make sure that the response_signature_string and signature parameters are not included in the signature calculation (the response_signature_string parameter is returned only if the merchant is in test mode and contains hint how the signature was formed in response)
• if the request contains non-Latin letters, then it is sent in UTF-8
• in the program code, pledge a line to which you apply SHA1 during the formation of the signature parameter. Compare it with the string that returned in the response_signature_string

parameter

• Check if empty parameters are returned in the response. If yes, then in the string which participates in the signature, it is not necessary to include the symbol separator | for each empty parameter
• If you are developing in the PHP programming language, use the getSignature function:

  function getSignature( $merchant_id , $password , $params = array() ){
   $params['merchant_id'] = $merchant_id;
   $params = array_filter($params,'strlen');
   ksort($params);
   $params = array_values($params);
   array_unshift( $params , $password );
   $params = join('|',$params);
   return(sha1($params));
  }
  

• make sure that the result of the SHA1 function is lowercase. Correct: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Incorrect: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA

Request generation

Request to hutko payment gateway can be sent in several methods

1. Interaction scheme A  (most common)
   Merchant builds order HTML form on its website and POSTs it from merchant page to payment gateway hosted page using browser redirection
   Endpoint: https://pay.hutko.org/api/checkout/redirect/
   It is the most simple way to integrate your site. So if you do not know which scheme to use – then use scheme A

   Example for interaction scheme A

   <!DOCTYPE html>
   <html>
     <head>
       <meta charset="utf-8">
     </head>
     <body>
       <form name="tocheckout" method="POST" action="https://pay.hutko.org/api/checkout/redirect/">
         <input type="text" name="server_callback_url" value="https://site.com/callback/">
         <input type="text" name="response_url" value="https://site.com/responsepage/">
         <input type="text" name="order_id" value="test4207135583">
         <input type="text" name="order_desc" value="Test payment">
         <input type="text" name="currency" value="UAH">
         <input type="text" name="amount" value="100">
         <input type="text" name="signature" value="1773cf135bd89656131134b98637894dad42f808">
         <input type="text" name="merchant_id" value="1">
         <input type="submit">
       </form>
     </body>
   </html>
   

2. Interaction scheme B
   Merchant builds POST parameters on the server side and directly POSTs it from merchant server to payment gateway server, for example with curl
   Endpoint: https://pay.hutko.org/api/checkout/url/
   

   Interaction scheme B API supports following text transfer protocols: URL encoded, JSON. Best cases to use this method are:

   • generating a request from the merchant server to make POST parameters more secured and prevent them from disclosure
   • generating an invoice for a customer by sending payment page url via email, social networks, SMS

   Example host-to-host for interaction scheme B (JSON)

   Request

   curl -i -X POST \
    -H "Content-Type:application/json" \
    -d \
   '{
    "request": {
    "server_callback_url": "http://myshop/callback/",
    "order_id": "TestOrder2",
    "currency": "UAH",
    "merchant_id": 1700002,
    "order_desc": "Test payment",
    "amount": 1000,
    "signature": "91ea7da493a8367410fe3d7f877fb5e0ed666490"
    }
   }' \
    'https://pay.hutko.org/api/checkout/url'

   Normal response

   {
     "response":{
       "response_status":"success",
       "checkout_url":"https://pay.hutko.org/checkout?token=afcb21aef707b1fea2565b66bac7dc41d7833390"
     }
   }
   

   Response in case of error

   {
     "response":{
     "response_status":"failure",
     "error_message":"Parameter `amount` is mandatory",
     "error_code":"1008"
     }
   }
   

   Example host-to-host for interaction scheme B (URL encoded form)

   Request

   curl -i -X POST \
    -H "Content-Type:application/x-www-form-urlencoded" \
    -d 'response_url=http://myshop/callback/&order_id=TestOrderURLEncode211&order_desc=Test payment&currency=USD&amount=100&signature=b7acb85c7f02882049c9e19813025f27cb09ad63&merchant_id=1700002' \
   'https://pay.hutko.org/api/checkout/url'

   Normal response

   response_status=success&checkout_url=http%3A%2F%2Flocalhost%2Fcheckout%3Ftoken%3D643f3cea682e066f142099a76b0fa9d1613969dc

   Response in case of error

   response_status=failure&error_message=Parameter%20%60amount%60%20is%20mandatory&error_code=1008

3. Interaction scheme C
   This scheme is used mostly for JavaScript SDK  
   This scheme is similar to scheme B. The difference is in response: instead of checkout_url, parameters token will be returned.
   Endpoint: https://pay.hutko.org/api/checkout/token

   Request

   curl -i -X POST \
    -H "Content-Type:application/json" \
    -d \
   '{
    "request": {
    "server_callback_url": "http://myshop/callback/",
    "order_id": "TestOrder2",
    "currency": "UAH",
    "merchant_id": 1700002,
    "order_desc": "Test payment",
    "amount": 1000,
    "signature": "91ea7da493a8367410fe3d7f877fb5e0ed666490"
    }
   }' \
    'https://pay.hutko.org/api/checkout/token'

   Normal response:

   {
     "response":{
       "response_status":"success",
       "token":"afcb21aef707b1fea2565b66bac7dc41d7833390"
     }
   }

   Response in case of error

   {
     "response":{
     "response_status":"failure",
     "error_message":"Parameter `amount` is mandatory",
     "error_code":"1008"
     }
   }

   This token is used in JavaScript SDK which allows to embed credit card form in your site and make a customized checkout page.

Response is always returned in request context in the same content-type. So if request is sent in JSON, response will be sent in JSON format too. Response for such request will be interim and will contain URL where customer must be redirected to payment page.

Sending request in interaction scheme A does not assume getting response in request context. The final response will be returned to merchant URL, specified in response_url and server_callback_url parameters.