API FONDYВерсия 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 FONDY, и вернулся ответ: Invalid signature.
2. Если от сервера FONDY на server_callback_url или response_url вернулся POST ответ, но при попытке сформировать подпись и сравнить ее с параметром signature из POST ответа, подписи не совпадают

Рассмотрим оба случая:

1. Если запрос отправлен на API FONDY, и ответ вернулся вида “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. Если от сервера FONDY на страницы, указанные в параметрах server_callback_url или response_url вернулся POST ответ, но при попытке сформировать подпись и сравнить ее с параметром signature в POST ответе, подписи не совпадают

Пример ответа от FONDY (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

Формирование запроса

Запросы на сервер FONDY можно отправлять 2-мя способами

1. Схема взаимодействия A (с перенаправлением пользователя на платежную страницу) через отправку HTML формы на URL https://pay.fondy.eu/api/checkout/redirect/
2. Схема взаимодействия B (с предварительным host-to-host запросом для получения url платежной страницы) через отправку HTML формы на URL https://pay.fondy.eu/api/checkout/url/

Схема взаимодействия B АПИ поддерживает следующие текстовые форматы запросов: 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.fondy.eu/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.fondy.eu/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.fondy.eu/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.fondy.eu/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.fondy.eu/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.fondy.eu/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