API hutkoВерсия 1.0

Приклад коду перевірки підпису на сторінках, зазначених у параметрах response_url або server_callback_url, з використанням PHP SDK:

<?php
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));
}

Допоміжний файл із прикладами функцій для роботи з підписом 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

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

Розв’язання проблем із генерацією та валідацією параметра signature

Існує дві типові ситуації, коли виникає помилка перевірки параметра signature. 

1. Якщо запит на купівлю / рекурентний платіж / реверс / статусу або будь-який інший запит із параметром signature надіслано на API hutko, і повернулася відповідь: Invalid signature.
2. Якщо від сервера hutko на server_callback_url або response_url, повернулася POST-відповідь, але під час спроби сформувати підпис і порівняти його з параметром signature з POST-відповіді підписи, не збігаються

Розглянемо обидва випадки:

1. Якщо запит відправлено на API hutko, і відповідь повернулася у вигляді “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1396424|demo order 789|Demo123456`”, виконайте такі перевірки:
   • переконайтесь, що ви використовували коректний пароль із технічних налаштувань мерчанта в мерчант-порталі:
   • якщо запит містить кириличні або інші нелатинські літери, то його відправлено в кодуванні UTF-8
   • переконайтеся, що параметр зі значенням 0 не приводиться вашою мовою програмування до порожнього значення
   • залогуйте в програмному коді рядок, до якого ви застосовуєте SHA1 під час формування параметра signature. Порівняйте його з рядком, який повернувся в тексті помилки (відзначено червоним кольором): “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1396424|demo order 789|Demo123456`“. Врахуйте, що в тексті помилки фраза-пароль мерчанта буде замаскована знаком *
   • перевірте, чи передаєте ви в запиті до API порожні параметри. Якщо так, то в самому рядку, який бере участь у підписі, символ роздільник || для кожного такого порожнього параметра включати не потрібно
   • якщо ви розробляєте мовою програмування PHP, скористайтеся прикладом функції getSignature:

     <?php
     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));
     }

   • переконайтеся, що результат функції SHA1 приведений до нижнього регістру. Правильно: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Неправильно: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA
   • переконайтеся, що параметр signature не включений вами в розрахунок підпису
   • переконайтеся, що якщо ви використовуєте точку API /api/recurring , то вами в підпис включено тільки необхідні параметри 
2. Якщо від сервера hutko на сторінки, зазначені в параметрах server_callback_url або response_url повернулася POST відповідь, але при спробі сформувати підпис і порівняти його з параметром signature в POST відповіді, підписи не збігаються

Приклад відповіді від hutko (JSON):

{
 "rrn": "429417347068",
 "masked_card": "444455XXXXXX6666",
 "sender_cell_phone": "",
 "response_signature_string": "**********|3324000|UAH|3324000|027440|444455|VISA|UAH|444455XXXXXX6666|1396424|
  14#1500639628|approved|21.07.2017 15:20:27|51247263|card|success|0|429417347068|test@taskombank.ua|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": "UAH",
 "order_id": "14#1500639628",
 "parent_order_id": "",
 "merchant_data": "",
 "tran_type": "purchase",
 "eci": "",
 "settlement_date": "",
 "payment_system": "card",
 "rectoken": "",
 "approval_code": "027440",
 "merchant_id": 1396424,
 "settlement_currency": "",
 "payment_id": 51247263,
 "product_id": "",
 "currency": "UAH",
 "card_bin": 444455,
 "response_code": "",
 "card_type": "VISA",
 "amount": "3324000",
 "sender_email": "test@taskombank.eu",
 "signature": "47bdcaf61b99edd31e3ec7913225a14d2ce07575"
}

Щоб діагностувати причину розбіжності підпису, виконайте такі дії:

• переконайтеся, що параметр зі значенням 0 не приводиться вашою мовою програмування до порожнього значення
• переконайтеся, що параметри response_signature_string і signature не включені вами в розрахунок підпису (параметр response_signature_string повертається, лише якщо мерчант перебуває у тестовому режимі, та містить підказку, як було сформовано підпис у відповідь)
• якщо запит містить кириличні або інші нелатинські літери, то його відправлено в кодуванні UTF-8
• залогуйте в програмному коді рядок, до якого ви застосовуєте SHA1 під час формування параметра signature. Порівняйте його з рядком, який повернувся в параметрі response_signature_string
• перевірте, чи повернулися у відповіді порожні параметри. Якщо так, то в самому рядку, який бере участь у підписі, символ роздільник | для кожного такого порожнього параметра вмикати не потрібно
• якщо ви розробляєте мовою програмування PHP, скористайтеся функцією getSignature:

  <?php
  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));
  }

• переконайтеся, що результат функції SHA1 приведений до нижнього регістру. Правильно: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Неправильно: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA

Формування запиту

Запити на сервер hutko можна надсилати 2-ма способами

1. Схема взаємодії A (з перенаправленням користувача на платіжну сторінку) через надсилання HTML форми на URL https://pay.hutko.org/api/checkout/redirect/
2. Схема взаємодії B (з попереднім host-to-host запитом для отримання url платіжної сторінки) через надсилання HTML форми на URL https://pay.hutko.org/api/checkout/url/

Схема взаємодії B API підтримує такі текстові формати запитів: HTML FORM, XML, JSON. Цей варіант зручно використовувати для:

• формування запиту з сайту мерчанта в браузері клієнта через AJAX
• формування запиту від мерчант-сервера.
• виставлення рахунків / інвойсів клієнту на пошту, в месенджері, в соціальних мережах

У контексті запиту завжди повертається відповідь у тому ж форматі, що й запит. Тобто якщо запит був у форматі JSON, то і відповідь повернеться у форматі JSON. Відповідь на такий запит є проміжною і містить URL, на який необхідно перенаправити клієнта для введення реквізитів платежу.

Надсилання запиту за схемою взаємодії A не передбачає проміжної відповіді в контексті запиту. Фінальна відповідь буде повернута на URL мерчанта, вказаний у параметрах response_url і server_callback_url.

Приклад для схеми взаємодії 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>

Приклад host-to-host для схеми взаємодії B (JSON)

Content Type: application/json

Запит

{
  "request": {
    "response_url": "https://pay.hutko.org/responsepage/",
    "order_id": "test8037875286",
    "order_desc": "Test payment",
    "currency": "UAH",
    "amount": "100",
    "signature": "07bc309047a56275f8d89ae222e2af0ceb94fe79",
    "merchant_id": "1"
  }
}

Нормальна проміжна відповідь

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

Відповідь у разі помилки

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

Приклад host-to-host для схеми взаємодії B (XML)

Content Type: application/xml

Запит

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <response_url>https://pay.hutko.org/responsepage/</response_url>
  <order_id>test622138965</order_id>
  <order_desc>Test payment</order_desc>
  <currency>UAH</currency>
  <amount>100</amount>
  <signature>fad685643ed5375d6d08c27f4f600e848549b0c5</signature>
  <merchant_id>1</merchant_id>
</request>

Нормальна проміжна відповідь

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <response_status>success</response_status>
  <checkout_url>https://pay.hutko.org/checkout?token=6c67efad5fd68921f58836cabc2a3d27c5f02b23</checkout_url>
</response>

Відповідь у разі помилки

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <response_status>failure</response_status>
  <error_message>Parameter `amount` is mandatory</error_message>
  <error_code>1008</error_code>
</response>

Приклад host-to-host для схеми взаємодії B (HTML form)

Content Type: application/x-www-form-urlencoded

Запит

response_url=https://pay.hutko.org/responsepage/&order_id=test3600040034
&order_desc=Test payment&currency=UAH&amount=100&merchant_id=1
&signature=ea326b841f9a1e2e90fb392392d3ed6255a6698d

Нормальна проміжна відповідь

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

Відповідь у разі помилки

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