API FONDYВерсия 1.0


Параметры запроса

ПараметрТипОписаниеПример передаваемого мерчантом значения
order_idstring(1024)Идентификатор заказа, назначаемый мерчантом.
обязательный
ID1234
merchant_idinteger(12)Уникальный идентификатор мерчанта. Выдается торговцу после регистрации.
обязательный
1
order_descstring(1024)Описание заказа. Передается мерчантом всегда в кодировке UTF-8
обязательный
Покупка ЖД билета на поезд №1234 Киев — Львов
signaturestring(40)Подпись заказа. Служит для проверки целостности и подлинности запроса от мерчанта на стороне сервера платежного шлюза. Алгоритм формирования подписи см. Формирование подписи запроса и ответа
обязательный
1773cf135bd89656131134b98637894dad42f808
amountinteger(12)Сумма заказа в копейках/центах без разделителей
обязательный
1020 (USD) — означает 10 долларов 20 центов
currencystring(3)Валюта заказа. Допустимые значения:
UAH — украинская гривна
RUB — российский рубль
USD — доллар США
EUR — евро
GBP — фунт стерлингов обязательный
CZK — чешские кроны
USD
versionstring(10)Версия протокола.
Значение по-умолчанию: 1.0
1.0
response_urlstring(2048)URL страницы мерчанта, на которую будет перенаправлен клиент в браузере после завершения оплаты
Значание по-умолчанию: https://api.fondy.eu/checkout/responsepage
http://site.com/responseurl
server_callback_urlstring(2048)URL страницы мерчанта, на которую будет отправлен ответ о результате оплаты через сервер-сервер соединение
http://site.com/callbackurl
payment_systemsstring(1024)Список платежных систем, доступных клиенту при выборе способа оплаты на странице FONDY. Системы должны быть разделены запятой или точкой с запятой.
Допустимые значения: см. Поддерживаемые платежные системы
По-умолчанию: берется из настроек мерчанта
qiwi,yandex,webmoney,card,p24
default_payment_systemstring(25)Платежная система, которая первой отобразится плательщику на платежной странице.
Допустимые значения: см. Поддерживаемые платежные системы
card
lifetimeinteger(6)Время жизни заказа в секундах. По истечении этого времени, заказу будет присвоен статус ‘expired’ если клиент его не оплатил
Значение по-умолчанию: 36000
600
merchant_datastring(2048)Любой произвольный набор данных, который мерчант хочет получить обратно в ответе на response_url и/или server_callback_url, а также в отчетах 
preauthstring(1)Параметр применяется только при оплате картой Visa/MasterCard
N — сумма списывается с карты клиента сразу и возмещается на счет мерчанта в соответствии с регламентом зачисления.
Y — сумма блокируется на карте клиента и не списывается до тех пор, пока мерчант на пришлет запрос capture для подтверждения списания
Значение по-умолчанию: N
N
sender_emailstring(254)Email плательщика 
delayedstring(1)Признак отложенного платежа.
Y — позволить клиенту оплатить платеж позже в пределах лимита времени, указанного в параметре lifetime. Торговец должен быть готов к получению нескольких колбеков и редиректов с результатом оплаты для одного и того же платежа. Клиенту будет разрешено повторить попытку оплаты одного и того же order_id, если предыдущая попытка была не успешная
N — при попытке оплатить платеж с одним и тем же order_id повторно, клиент будет получать ошибку с просьбой перейти на сайт торговца и создать платеж заново. В этом случае будет только один колбек на server_callback_url
Значение по-умолчанию: Y
 
langstring(2)Язык платежной страницы. Доступные значения:
ru — русский
uk — украинский
en — английский
lv — латышский
fr — французский
 
product_idstring(1024)Идентификатор оплачиваемого товара/услуги 
required_rectokenstring(1)Флаг, указывающий на необходимость возвращать токен карты — токен, по которому можно списывать средства с карты без дальнейшего участия клиента
Значение по-умолчанию: N
Y
verificationstring(1)Y — будет сделан автоматический реверс платежа системой FONDY, если платеж успешный
Значение по-умолчанию: N
Y
verification_typestring(25)amount — на карте блокируется указанная сумма без дополнительных проверок
code — на карте блокируется указанная сумма, с случайным 4-х символьным кодом, который клиент должен ввести для завершения верификации
Значение по-умолчанию: amount
Y
rectokenstring(40)Токен карты, по которому можно списывать средства с карты без дальнейшего участия клиента
544d3f86237886b6404d8b000f6a7d71c45410b7
receiver_rectokenstring(40)Токен карты, по которому можно кредитовать карту, не передавая полный номер карты
544d3f86237886b6404d8b000f6a7d71c45410b7
design_idinteger(6)ID дизайна, настроенного в мерчант-портале
123
subscriptionstring(1)Y — активировать регулярные платежи (по календарю)
N — значение по умолчанию, деактивировать регулярные платежи
Y/N
subscription_callback_urlstring(2048)URL страницы мерчанта, на которую будет отправлен ответ о результате запланированной оплаты через сервер-сервер соединение 


Параметры финального ответа

ПараметрТипОписаниеПример ответа
order_idstring(1024)Идентификатор заказа. Назначается мерчантом. 
merchant_idinteger(12)Уникальный идентификатор мерчанта. Выдается торговцу после регистрации.1
amountinteger(12)Сумма заказа в копейках/центах без разделителей1020 (USD) — означает 10 долларов 20 центов
currencystring(3)Валюта заказа. Допустимые значения:
UAH — украинская гривна
RUB — российский рубль
USD — доллар США
GBP — фунт стерлингов
EUR — евро
 
order_statusstring(50)Статус обработки заказа. Может содержать следующие значения:
created — заказ был создан, но клиент еще не ввел платежные реквизиты; необходимо продолжать опрашивать статус заказа
processing — заказ все еще находится в процессе обработки платежным шлюзом; необходимо продолжать опрашивать статус заказа
declined — заказ отклонен платежным шлюзом FONDY, внешней платежной системой или банком-эквайером
approved — заказ успешно совершен, средства заблокированы на счету плательщика и вскоре будут зачислены мерчанту; мерчант может оказывать услугу или “отгружать” товар
expired — время жизни заказа, указанное в параметре lifetime, истекло.
reversed — ранее успешная транзакция была полностью или частично отменена. В таком случае параметр reversal_amount имеет не нулевое значение
 
response_statusstring(50)Статус обработки запроса. Если возникла ошибка при валидации передаваемых параметров, то возвращается failure, иначе success 
signaturestring(40)Подпись заказа. Служит для проверки мерчантом целостности и подлинности ответа от сервера платежного шлюза. Алгоритм формирования подписи см. Формирование подписи запроса и ответа
1773cf135bd89656131134b98637894dad42f808
tran_typestring(50)Допустимые значения:
purchase — покупка
reverse — отмена/возврат
 
sender_cell_phonestring(16)Мобильный телефон плательщика 
sender_accountstring(50)Номер счета плательщика (кошелек Yandex, Webmoney, Qiwi и пр.) 
masked_cardstring(19)Маскированный номер карты444444XXXXXX5555
card_bininteger(6)Бин карты — как правило первые 6 цифр номера карты444444
card_typestring(50)Допустимые значения:
VISA, MasterCard
 
rrnstring(50)В общем случае не уникальный идентификатор транзакции, присвоенный банком-эквайером. 
approval_codestring(6)В общем случае не уникальны код авторизации, присвоенный банком-эмитентом 
response_codeinteger(4)Код отклонения заказа. Допустимые коды см. в Коды отказов 
response_descriptionstring(1024)Описание кода отклонения заказа. См. Коды отказов 
reversal_amountinteger(12)Сумма всех реверсов по данному заказу 
settlement_amountinteger(12)Сумма возмещенных средств по данному мерчанту 
settlement_currencystring(3)Валюта возмещения мерчанту 
order_timestring(19)Дата создания заказа в формате ДД.ММ.ГГГГ чч:мм:сс21.12.2014 11:21:30
settlement_datestring(10)Дата возмещения на счет мерчанта в формате ДД.ММ.ГГГГ21.12.2014
eciinteger(2)Ecommerce Indicator — параметр, указывающий на то, была ли 3dsecure аутентификация держателя карты или нет. Допустимые значения:
5 — была проведена полная аутентификация кардхолдера
6 — мерчант поддерживает 3dsecure, но банк-эмитент не поддерживает
7 — ни мерчант ни банк-эмитент не поддерживают 3dsecure
 
feeinteger(12)Комиссия, удержанная с суммы заказа платежным шлюзом FONDY 
payment_systemstring(50)Платежная система, через которую был осуществлен платеж. Список допустимых платежных систем см. Поддерживаемые платежные системыQiwi
sender_emailstring(254)Email плательщика 
payment_idinteger(19)Уникальный идентификатор платежа, присвоенный платежным шлюзом FONDY 
actual_amountinteger(12)Фактическая сумма заказа, после всех реверсов. 
actual_currencystring(3)Фактическая валюта заказа 
product_idstring(1024)Идентификатор оплачиваемого товара/услуги 
merchant_datastring(2048)Любой произвольный набор данных, который мерчант передал в запросе 
verification_statusstring(50)Результат проверки кода при верификации карты
Допустимые значения:
verified — карта успешно верифицирована по коду
incorrect — введен неверный код верификации, но еще не исчерпан лимит попыток
failed — исчерпан лимит неверных попыток ввода проверочного кода
created — проверочный код создан, но не вводился клиентом
 
rectokenstring(40)Токен карты — токен, по которому можно списывать средства с карты без дальнейшего участия клиента
da39a3ee5e6b4b0d3255bfef95601890afd80709
rectoken_lifetimestring(19)Время жизни токена в формате ДД.ММ.ГГГГ чч:мм:сс
01.01.2018 00:00:00

Параметры промежуточного ответа

ПараметрТипОписаниеПример возвращаемого значения
response_statusstring(50)если не было ошибки, всегда возвращается successsuccess
checkout_urlstring(20)48URL страницы, на которую мерчант должен перенаправить клиента для дальнейшего ввода платежных реквизитов
https://api.fondy.eu/checkout?token=e0a5d4f331806d1e2feb80353b4c44bf6751fc8c
payment_idinteger(19)Уникальный идентификатор платежа, присвоенный платежным шлюзом FONDY 

Параметры ответа в случае ошибки

ПараметрТипОписаниеПример возвращаемого значения
response_statusstring(50)всегда возвращается failurefailure
error_codeinteger(4)Код отклонения заказа. Допустимые значения описаны в Коды отказов 
error_messagestring(1024)Описание кода отклонения заказа. См. Коды отказов 

Формирование подписи запроса и ответа (параметр signature)

Подпись формируется путем применения функции SHA1 к строке, состоящей из пароля мерчанта и всех параметров, приконкатенированных к нему в алфавитном порядке и разделенных символом вертикальной черты |

Пример:

Запрос от мерчанта:

{
  "request":{
    "order_id":"test123456",
    "order_desc":"test order",
    "currency":"USD",
    "amount":"125",
    "signature":"f0ee6288b9295d3b808bcd8d720211c7201245e1",
    "merchant_id":"1396424"
  }
}

строка, использованная для формирования подписи:

test|125|USD|1396424|test order|test123456

Если параметр пустой и не содержит данных, то присоединять вертикальную черту не нужно.


Пример кода проверки подписи на страницах указанных в параметрах 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));
}

Также хороший пример описан по ссылке https://ipsp-php.com/docs/4.generate-signature.html

Вспомогательный файл с примерами функций для работы с подписью 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`”, выполните следующие проверки:

    • проверьте, что вы использовали корректный пароль из Технических настроек мерчанта в Мерчант-портале:

      payment_key

    • если запрос содержит кириллические или другие не латинские буквы, то он отправлен в кодирорке 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|RUB|3324000|027440|444455|VISA|RUB|444455XXXXXX6666|1396424|
  14#1500639628|approved|21.07.2017 15:20:27|51247263|card|success|0|429417347068|test@fondy.eu|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": "RUB",
 "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": "RUB",
 "card_bin": 444455,
 "response_code": "",
 "card_type": "VISA",
 "amount": "3324000",
 "sender_email": "test@fondy.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://api.fondy.eu/api/checkout/redirect/
  2. Схема взаимодействия B (с предварительным host-to-host запросом для получения url платежной страницы) через отправку HTML формы на URL https://api.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://api.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="RUB">
      <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://api.fondy.eu/responsepage/",
    "order_id": "test8037875286",
    "order_desc": "Test payment",
    "currency": "RUB",
    "amount": "100",
    "signature": "07bc309047a56275f8d89ae222e2af0ceb94fe79",
    "merchant_id": "1"
  }
}

Нормальный промежуточный ответ

{
  "response":{
    "response_status":"success",
    "checkout_url":"https://api.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://api.fondy.eu/responsepage/</response_url>
  <order_id>test622138965</order_id>
  <order_desc>Test payment</order_desc>
  <currency>RUB</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://api.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://api.fondy.eu/responsepage/&order_id=test3600040034
&order_desc=Test payment&currency=RUB&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