API FONDYВерсия 1.0

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

Параметр version необходимо передавать со значением 1.0.1

ПараметрТипОписаниеПример передаваемого мерчантом значения
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 — украинская гривна
USD — доллар США
EUR — евро
GBP — фунт стерлингов обязательный

CZK — чешские кроны
USD
versionstring(10)Версия протокола.

Значение по умолчанию: 1.0.1
Версия 1.0 — устарела
1.0.1
response_urlstring(2048)URL страницы мерчанта, на которую будет перенаправлен клиент в браузере после завершения оплаты

Значение по умолчанию: https://pay.fondy.eu/checkout/responsepage
http://site.com/responseurl
server_callback_urlstring(2048)URL страницы мерчанта, на которую будет отправлен ответ о результате оплаты через сервер-сервер соединение. Детальнее про серверные колбеки см. п. Получение Callback
http://site.com/callbackurl
payment_systemsstring(1024)Список платежных систем, доступных клиенту при выборе способа оплаты на странице FONDY. Системы должны быть разделены запятой или точкой с запятой.
Допустимые значения: см. Поддерживаемые платежные системы

По умолчанию: берется из настроек мерчанта
card
payment_methodstring(1024)Платежный метод, который необходимо отобразить плательщику на платежной странице по умолчанию. Например monobank_ua

По умолчанию: берется из настроек мерчанта
card
default_payment_systemstring(25)Платежная система, которая первой отобразится плательщику на платежной странице.
Допустимые значения: см. Поддерживаемые платежные системы
card
lifetimeinteger(9)Время жизни заказа в секундах. По истечении этого времени, заказу будет присвоен статус ‘expired’ если клиент его не оплатил

Значение по умолчанию: 36000
Максимально-допустимое значение: 69120000
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 — французский
cs — чешский
ro — румынский
it — итальянский
sk — словацкий
pl — польский
es — испанский
hu — венгерский
de — немецкий
 
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 — украинская гривна
USD — доллар США
GBP — фунт стерлингов
EUR — евро
 
order_statusstring(50)Статус обработки заказа. Может содержать следующие значения:
created — заказ был создан, но клиент еще не ввел платежные реквизиты; необходимо продолжать опрашивать статус заказа
processing — заказ все еще находится в процессе обработки платежным шлюзом; необходимо продолжать опрашивать статус заказа
declined — заказ отклонен платежным шлюзом FONDY, внешней платежной системой или банком-эквайером
approved — заказ успешно совершен, средства заблокированы на счету плательщика и вскоре будут зачислены мерчанту; мерчант может оказывать услугу или “отгружать” товар
expired — время жизни заказа, указанное в параметре lifetime, истекло.
reversed — ранее успешная транзакция была полностью отменена. В таком случае параметр reversal_amount будет эквивалентно actual_amount
 
response_statusstring(50)Статус обработки запроса. Если возникла ошибка при валидации передаваемых параметров, то возвращается failure, иначе success 
signaturestring(40)Подпись заказа. Служит для проверки мерчантом целостности и подлинности ответа от сервера платежного шлюза. Алгоритм формирования подписи см. Формирование подписи запроса и ответа
1773cf135bd89656131134b98637894dad42f808
tran_typestring(50)Допустимые значения:
purchase — покупка
reverse — отмена/возврат
 
sender_cell_phonestring(16)Мобильный телефон плательщика 
sender_accountstring(50)Номер счета плательщика 
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)Платежная система, через которую был осуществлен платеж. Список допустимых платежных систем см. Поддерживаемые платежные системыCard
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
additional_infostring(20480)Дополнительные данные в формате JSON
{
"bank_name": "Some bank in US country",
"bank_country": "US",
"bank_response_code": "decln_1000",
"card_product": "DEBIT",
"card_category": "CLASSIC",
"settlement_fee": 0.2,
"capture_status": "captured",
"client_fee": 0.3,
"ipaddress_v4": "8.8.8.8",
"capture_amount": 200,
"card_type": "VISA",
"reservation_data": null,
"bank_response_description": "General decline",
"transaction_id": 1058755083,
"timeend":"10.01.2018 11:21:30"
"card_number": "4444555566661111"
"payment_method": "apple" or "googlepay" or "card"
}

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

ПараметрТипОписаниеПример возвращаемого значения
response_statusstring(50)если не было ошибки, всегда возвращается successsuccess
checkout_urlstring(20)48URL страницы, на которую мерчант должен перенаправить клиента для дальнейшего ввода платежных реквизитов
https://pay.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));
}

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

Хочу принимать платежи со всего мира!