Документация по API

Настройка учетной записи

Для начала работы необходимо заполнить следующую форму в личном кабинете на странице "технические данные"
Необходимые параметры:
Название сайта Отображаемое имя Вашего сайта на странице оплаты
URL сайта URL Вашего сайта
Секретное слово Секретное слово для формирования подписи для формы оплаты
Секретное слово 2 Секретное слово для формирования подписи для проверки данных (которые отправляются на Ваш Result Url) после оплаты
URL оповещения Страница Вашего сайта, на который будут отправлены данные с информацией о платеже
Метод оповещения Здесь и ниже - способ передачи данных на Ваш сайт (GET или POST)
URL возврата в случае успеха На эту страницу будет перенаправлен покупатель в случае успешной оплаты
URL возврата в случае неудачи На эту страницу будет перенаправлен покупатель, если при оплате возникла какая-либо ошибка
Режим интеграции По-умолчанию НЕТ. Режим сделан для упрощения переноса сайта от другого сервиса приема платежей. Подробнее
Кто платит комиссию Выберите, кто платит комиссию при осуществлении платежей
Способы выплат Онлайн - деньги сразу переводятся на Ваши кошельки (доступно не для всех валют).
Вручную - выплату необходимо заказывать

Настройка формы оплаты

Форма оплаты содержит все необходимые данные для оплаты заказа. Передается методом GET на адрес http://www.free-kassa.ru/merchant/cash.php (вы можете использовать протокол https или http)
Необходимые параметры:
m ID Вашего магазина
oa Сумма платежа
o Номер заказа (также это может быть название товара или логин пользователя, для зачисления средств)
s Подпись (методика формирования подписи в платежной форме)
Необязательные параметры:
i Предлагаемая валюта платежа (список валют). Плательщик сможет изменить ее в процессе оплаты.
em Email плательщика
lang Язык интерфейса оплаты (en/ru)
us_key Так же Вы можете передавать свои параметры, которые наш сервер вернет на Ваш URL оповещения. Ключи параметров должны начинаться с us_ и содержать только латинские символы и цифры. Значения параметров могут содержать только латинские буквы, цифры и символы '-', '_'. Например:
<input type="text" name="us_name" value="ivanov">
<input type="text" name="us_login" value="ivanov1971">
Внимание! Для передачи значений параметров на русском языке, необходимо передавать их в кодировке windows-1251

Оповещение о платеже

После успешной оплаты, на Ваш URL оповещения будут отправлены следующие данные
MERCHANT_ID ID Вашего магазина
AMOUNT Сумма заказа
intid Номер операции Free-Kassa
MERCHANT_ORDER_ID Ваш номер заказа
P_EMAIL Email плательщика
P_PHONE Телефон плательщика (если указан)
CUR_ID ID электронной валюты, который был оплачен заказ (список валют)
SIGN Подпись (методика формирования подписи в данных оповещения)
us_key Дополнительные параметры с префиксом us_, переданные в форму оплаты

Подтверждение заявки
Если Вы хотите быть уверены, что подтверждение на URL оповещения дошло успешно и обработано верно, добавьте в скрипт URL оповещения вывод слова YES и обратитесь в техподдержку для включения функции проверки.
После этого наш сервер будет передавать информацию о платеже на ваш URL оповещения до тех пор, пока не получит ответ YES.

Проверка IP
Рекомендуем так же проверять IP сервера отправляющего Вам информацию, наши IP - 136.243.38.147 136.243.38.149 136.243.38.150 136.243.38.151 136.243.38.189
Пример функции на PHP
                    
function getIP() {
if(isset($_SERVER['HTTP_X_REAL_IP'])) return $_SERVER['HTTP_X_REAL_IP'];
   return $_SERVER['REMOTE_ADDR'];
}
if (!in_array(getIP(), array('136.243.38.147', '136.243.38.149', '136.243.38.150', '136.243.38.151', '136.243.38.189'))) {
	die("hacking attempt!");
}
                    


Пример обработчика платежа

$merchant_id = '177';
$merchant_secret = 'supersecret';

function getIP() {
if(isset($_SERVER['HTTP_X_REAL_IP'])) return $_SERVER['HTTP_X_REAL_IP'];
   return $_SERVER['REMOTE_ADDR'];
}
if (!in_array(getIP(), array('136.243.38.147', '136.243.38.149', '136.243.38.150', '136.243.38.151', '136.243.38.189'))) {
    die("hacking attempt!");
}

$sign = md5($merchant_id.':'.$_REQUEST['AMOUNT'].':'.$merchant_secret.':'.$_REQUEST['MERCHANT_ORDER_ID']);

if ($sign != $_REQUEST['SIGN']) {
    die('wrong sign');
}

//Так же, рекомендуется добавить проверку на сумму платежа и не была ли эта заявка уже оплачена или отменена
//Оплата прошла успешно, можно проводить операцию.

die('YES');

                

Интеграция

Если у Вас уже был настроен прием платежей через платежные системы Robokassa, Interkassa или Payeer, то Вы можете с минимальными усилиями переключить прием платежей на наш сервис.
Для этого в личном кабинете на странице "технические данные" выберите в поле "Режим интеграции" свою старую платежную систему и внесите несколько измнений в свои скрипты оплаты:
Robokassa:
URL перехода В платежной форме измените урл перехода, вместо - https://auth.robokassa.ru/Merchant/Index.aspx, надо использовать - http://www.free-kassa.ru/merchant/cash.php
MrchLogin ID Вашего магазина на сервисе Free-kassa.ru
Пароль #1 Секретное слово на сервисе Free-kassa.ru
Пароль #2 Секретное слово 2 на сервисе Free-kassa.ru
Все остальные данные оставьте без изменений
Внимание! Сумму оплаты необходимо передавать (а так же использовать в подписи) без лишних нулей в дробной части. Например: 1 вместо 1.00, 1.1 вместо 1.10
Interkassa:
URL перехода В платежной форме измените урл перехода, вместо - http://www.interkassa.com/lib/payment.php, надо использовать - http://www.free-kassa.ru/merchant/cash.php
ik_co_id ID Вашего магазина на сервисе Free-kassa.ru
ik_pm_no Номер или описание заказа нужно указывать обязательно!
Sign Key Секретное слово на сервисе Free-kassa.ru. Секретное слово 1 и секретное слово 2 на Free-kassa.ru должны быть одинаковы.
Важно! Если Вы не использовали проверку цифровой подписи, ее необходимо настроить, согласно документации Interkassa:

Цифровая подпись формируется путем объединения значений всех параметров формы с префиксом "ik_" в алфавитном порядке их имен (без учета регистра), с добавлением в конец «секретного ключа» кассы. Конкатенация идет через символ ":". Если форма содержит несколько полей с одинаковыми именами, такие поля сортируются в алфавитном порядке их значений.
ksort($dataSet, SORT_STRING);
array_push($dataSet, $key); // добавляем в конец массива "секретный ключ"
$signString = implode(':', $dataSet); // конкатенируем значения через символ ":"
$sign = base64_encode(md5($signString, true)); // берем MD5 хэш в бинарном виде по
Все остальные данные оставьте без изменений
Payeer:
URL перехода В платежной форме измените урл перехода, вместо - http://payeer.com/merchant/, надо использовать - http://www.free-kassa.ru/merchant/cash.php
m_shop ID Вашего магазина на сервисе Free-kassa.ru
m_key Секретное слово на сервисе Free-kassa.ru. Секретное слово 1 и секретное слово 2 на Free-kassa.ru должны быть одинаковы
Все остальные данные оставьте без изменений
InSales:


В разеделе "Оплата", панели управления Вашего магазина, необходимо добавить новый способ оплаты "Внешний способ оплаты" и внести следующие данные
Идентификатор магазина ID Вашего магазина на сервисе Free-kassa.ru
Пароль Секретное слово на сервисе Free-kassa.ru. Секретное слово 1 и секретное слово 2 на Free-kassa.ru должны быть одинаковы
URL внешнего сервиса http://www.free-kassa.ru/merchant/cash.php


Внимание! В личном кабинете http://www.free-kassa.ru/merchant/cabinet/profile/tech.php необходимо внести следующие настройки:



URL оповещения http://ВАШ_САЙТ/payments/external/server
Метод оповещения POST
URL возврата в случае успеха http://ВАШ_САЙТ/payments/external/success
Метод отсылки URL возврата в случае успеха POST
URL возврата в случае неудачи http://ВАШ_САЙТ/payments/external/fail
Метод отсылки URL возврата в случае неудачи GET
Режим интеграции InSales

Формирование подписи в платежной форме

Подпись для платежной формы формируется путем нахождения MD5-хеша от строки
"ID Вашего магазина:Сумма платежа:Секретное слово:Номер заказа", пример на PHP:
md5('7012:100.11:secret:154')
Пример платежной формы:
<?php
$merchant_id = '7012';
$secret_word = 'secret';
$order_id = '154';
$order_amount = '100.11';
$sign = md5($merchant_id.':'.$order_amount.':'.$secret_word.':'.$order_id);

?>

<form method='get' action='http://www.free-kassa.ru/merchant/cash.php'>
    <input type='hidden' name='m' value='<?php=$merchant_id?>'>
    <input type='hidden' name='oa' value='<?php=$order_amount?>'>
    <input type='hidden' name='o' value='<?php=$order_id?>'>
    <input type='hidden' name='s' value='<?php=$sign?>'>
    <input type='hidden' name='i' value='1'>
    <input type='hidden' name='lang' value='ru'>
    <input type='hidden' name='us_login' value='<?php=$user['login']?>'>
    <input type='submit' name='pay' value='Оплатить'>
</form>

Формирование подписи в скрипте оповещения

Подпись для скрипта оповещения формируется путем нахождения MD5-хеша от строки
"ID Вашего магазина:Сумма платежа:Секретное слово 2:Номер заказа", пример на PHP:
md5($_REQUEST['MERCHANT_ID'].':'.$_REQUEST['AMOUNT'].':secret2:'.$_REQUEST['MERCHANT_ORDER_ID'])

Список доступных валют

143 Мобильный Платеж МегаФон Центральный филиал
63 QIWI кошелек
123 QIWI кошелек USD
45 Яндекс.Деньги
94 VISA/MASTERCARD RUB
100 VISA/MASTERCARD USD
124 VISA/MASTERCARD EUR
116 Bitcoin
133 FK WALLET RUB
87 OOOPAY USD
106 OOOPAY RUR
109 OOOPAY EUR
131 WMZ-bill
130 WMR-bill
1 WebMoney WMR
2 WebMoney WMZ
3 WebMoney WME
112 Тинькофф Кредитные Системы
103 Wire Transfer
74 W1 RUR
67 VISA/MASTERCARD UAH
114 PAYEER RUB
115 PAYEER USD
146 BTC-E
64 Perfect Money USD
69 Perfect Money EUR
62 OKPAY USD
60 OKPAY RUB
61 OKPAY EUR
102 Z-Payment
79 Альфа-банк RUR
80 Сбербанк RUR
81 ВТБ24 RUR
110 Промсвязьбанк
113 Русский стандарт
82 Мобильный Платеж Мегафон
84 Мобильный Платеж МТС
132 Мобильный Платеж Tele2
83 Мобильный Платеж Билайн
99 Терминалы России
98 Терминалы Украины
118 Салоны связи
117 Денежные переводы
96 LendСredit.ru
125 Mykassa RUR
136 Paxum USD
137 Мобильный Платеж МегаФон Северо-Западный филиал
138 Мобильный Платеж МегаФон Сибирский филиал
139 Мобильный Платеж МегаФон Кавказский филиал
140 Мобильный Платеж МегаФон Поволжский филиал
141 Мобильный Платеж МегаФон Уральский филиал
142 Мобильный Платеж МегаФон Дальневосточный филиал
147 Litecoin
150 AdvCash

Экспорт заказов в XML

Для получения списка заказов, необходимо отправить запрос на URL http://www.free-kassa.ru/export.php со следующими параметрами:
Обязательные параметры:
merchant_id ID Вашего магазина на сервисе Free-kassa.ru
s Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 2, например
md5('7012'.'secret')
action get_orders
Дополнительные параметры:
date_from С какой даты показать результаты, в формате гггг-мм-дд
date_to До какой даты, в формате гггг-мм-дд
status Статус заявки, new - новые, paid - оплаченные, completed - выполненные, all - все
limit Сколько результатов показать (максимум 100)
offset С какой позиции показывать заявки

Пример запроса
http://www.free-kassa.ru/export.php?merchant_id=7012&s=c4ca4238a0b923820dcc509a6f75849b&action=get_orders&date_from=2014-01-01&limit=100&offset=100&status=completed

Пример ответа:
<?xml version="1.0" encoding="UTF-8" ?>
    <root>
        <answer>info</answer>
        <desc>Orders list</desc>
        <action_data>
            <item>
                <intid>1863442123</intid>
                <id>1384336695</id>
                <status>completed</status>
                <date>2014-01-01 04:32:41</date>
                <amount>200</amount>
                <description>Оплата заявки</description>
                <email>mail@yandex.ru</email>
            </item>
        </action_data>
    </root>

Проверка баланса

Для получения баланса, необходимо отправить запрос на URL http://www.free-kassa.ru/api.php со следующими параметрами:
Обязательные параметры:
merchant_id ID Вашего магазина на сервисе Free-kassa.ru
s Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 2, например
md5('7012'.'secret')
action get_balance

Пример запроса
http://www.free-kassa.ru/api.php?merchant_id=7012&s=c4ca4238a0b923820dcc509a6f75849b&action=get_balance

Пример ответа:
<?xml version="1.0" encoding="UTF-8" ?>
    <root>
        <answer>info</answer>
        <desc>Merchant balance</desc>
        <balance>12.73</balance>
    </root>

Проверка заказа

Для получения информации о заказе, необходимо отправить запрос на URL http://www.free-kassa.ru/api.php со следующими параметрами:
Обязательные параметры:
merchant_id ID Вашего магазина на сервисе Free-kassa.ru
s Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 2, например
md5('7012'.'secret')
intid Номер заказа на сервисе Free-kassa.ru (необходимо использовать или intid или order_id)
order_id Номер заказа магазина (необходимо использовать или intid или order_id)
action check_order_status

Пример запроса
http://www.free-kassa.ru/api.php?merchant_id=7012&s=c4ca4238a0b923820dcc509a6f75849b&action=check_order_status&order_id=123

Пример ответа:
<?xml version="1.0" encoding="UTF-8" ?>
    <root>
        <answer>info</answer>
        <desc>Order Inf</desc>
        <status>completed</status>
        <intid>165354</intid>
        <id>123</id>
        <date>2015-03-10 16:08:32</date>
        <amount>37</amount>
        <description>Payment #123</description>
        <email>user@email.ru</email>
    </root>

Вывод средств

Для вывода средств, необходимо отправить запрос на URL http://www.free-kassa.ru/api.php со следующими параметрами:
Обязательные параметры:
merchant_id ID Вашего магазина на сервисе Free-kassa.ru
currency Тип кошелька, варианты: ooopay, yandex, qiwi, payeer, card (VISA/MASTERCARD), wmr, wmz, w1, fkw (Free-kassa Wallet)
amount Сумма платежа
s Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 2, например
md5('7012'.'secret')
action payment

Пример запроса
http://www.free-kassa.ru/api.php?currency=yandex&merchant_id=7012&s=c4ca4238a0b923820dcc509a6f75849b&action=payment&amount=12

Пример ответа:
<?xml version="1.0" encoding="UTF-8" ?>
    <root>
        <answer>info</answer>
        <desc>Заявка отправлена</desc>
        <PaymentId>473632</balance>
    </root>

Выставление счета

Для выставления счета необходимо отправить запрос на URL http://www.free-kassa.ru/api.php со следующими параметрами:
Обязательные параметры:
merchant_id ID Вашего магазина на сервисе Free-kassa.ru
email Email получателя счета (если отправляете GET запрос, не забудьте выполнить url encode)
amount Сумма платежа
desc Номер заказа или описание платежа (если отправляете GET запрос, не забудьте выполнить url encode)
s Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 2, например
md5('7012'.'secret')
action payment

Пример запроса
http://www.free-kassa.ru/api.php?merchant_id=7012&s=c4ca4238a0b923820dcc509a6f75849b&action=create_bill&amount=12&email=user@site.ru&desc=11

Пример ответа:
<?xml version="1.0" encoding="UTF-8" ?>
    <root>
        <answer>info</answer>
        <desc>Success</desc>
    </root>

Генерация ссылки на оплату онлайн и тестирование оплаты

Для использования данной функции необходимо выполнить вход в систему

API для работы с кошельком

Для работы с API кошелька необходимо сгенерировать ключ для доступа на странице https://wallet.free-kassa.ru/settings/

Все запросы отправляются методом POST на URL https://wallet.free-kassa.ru/api_v1.php, ответ в формате JSON

Получение баланса кошелька

Обязательные параметры:
wallet_id Ваш номер кошелька
sign Контрольная подпись MD5, формируется из вашего wallet_id и API ключа, например
md5('F123456789'.'JG68NC68DJC8S0DCH6')
action get_balance

Пример запроса:
                    $data = array(
                        'wallet_id'=>'F123456789',
                        'sign'=>md5('F123456789'.'JG68NC68DJC8S0DCH6'),
                        'action'=>'get_balance',
                    );
                    $ch = curl_init();
                    curl_setopt($ch, CURLOPT_URL, 'https://wallet.free-kassa.ru/api_v1.php');
                    curl_setopt($ch, CURLOPT_HEADER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
                    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                    curl_setopt($ch, CURLOPT_POST, 1);
                    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
                    $result = trim(curl_exec($ch));
                    $c_errors = curl_error($ch);
                    curl_close($ch);
                

Пример ответа:
    {"status":"info","desc":"Wallet balance","data":{"RUR":"50.00","USD":"0.00","EUR":"0.00"}}

Вывод средств из кошелька

Обязательные параметры:
wallet_id Ваш номер кошелька
purse Кошелек для вывода
amount Сумма вывода
desc Примечание
currency Валюта для вывода
sign Контрольная подпись MD5, формируется из параметров wallet_id, currency, amount, purse и API ключа, например
md5('F123456789'.'64'.'10.23'.'79111111111'.'JG68NC68DJC8S0DCH6')
action cashout

Пример запроса:
                    $data = array(
                        'wallet_id'=>'F123456789',
                        'purse'=>'79111111111',
                        'amount'=>10.23,
                        'desc'=>'Test payment',
                        'currency'=>64,
                        'sign'=>md5('F123456789'.'64'.'10.23'.'79111111111'.'JG68NC68DJC8S0DCH6'),
                        'action'=>cashout',
                    );
                    $ch = curl_init();
                    curl_setopt($ch, CURLOPT_URL, 'https://wallet.free-kassa.ru/api_v1.php');
                    curl_setopt($ch, CURLOPT_HEADER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
                    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                    curl_setopt($ch, CURLOPT_POST, 1);
                    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
                    $result = trim(curl_exec($ch));
                    $c_errors = curl_error($ch);
                    curl_close($ch);
                

Пример ответа:
    {"status":"info","desc":"Payment send","data":{"payment_id":"543273"}}

Список доступных валют

143 Мобильный Платеж МегаФон Центральный филиал (комиссия 1.50%)
63 QIWI кошелек (комиссия 4.00%)
45 Яндекс.Деньги (комиссия 0.00%)
94 VISA/MASTERCARD RUB (комиссия 4.00%)
116 Bitcoin (комиссия 3.00%)
133 FK WALLET RUB (комиссия 0.00%)
87 OOOPAY USD (комиссия 1.00%)
106 OOOPAY RUR (комиссия 1.00%)
109 OOOPAY EUR (комиссия 1.00%)
1 WebMoney WMR (комиссия 4.50%)
2 WebMoney WMZ (комиссия 4.50%)
67 VISA/MASTERCARD UAH (комиссия 3.50%)
64 Perfect Money USD (комиссия 2.50%)
69 Perfect Money EUR (комиссия 2.50%)
82 Мобильный Платеж Мегафон (комиссия 1.50%)
84 Мобильный Платеж МТС (комиссия 1.50%)
132 Мобильный Платеж Tele2 (комиссия 1.50%)
83 Мобильный Платеж Билайн (комиссия 1.50%)
137 Мобильный Платеж МегаФон Северо-Западный филиал (комиссия 1.50%)
138 Мобильный Платеж МегаФон Сибирский филиал (комиссия 1.50%)
139 Мобильный Платеж МегаФон Кавказский филиал (комиссия 1.50%)
140 Мобильный Платеж МегаФон Поволжский филиал (комиссия 1.50%)
141 Мобильный Платеж МегаФон Уральский филиал (комиссия 1.50%)
142 Мобильный Платеж МегаФон Дальневосточный филиал (комиссия 1.50%)

Перевод на другой кошелек

Обязательные параметры:
wallet_id Ваш номер кошелька
purse Кошелек для перевода
amount Сумма перевода
sign Контрольная подпись MD5, формируется из параметров wallet_id, purse, amount и API ключа, например
md5('F123456789'.'10.23'.'F123456710'.'JG68NC68DJC8S0DCH6')
action transfer

Пример запроса:
                    $data = array(
                        'wallet_id'=>'F123456789',
                        'purse'=>'F123456710',
                        'amount'=>10.23,
                        'sign'=>md5('F123456789'.'10.23'.'F123456710'.'JG68NC68DJC8S0DCH6'),
                        'action'=>transfer',
                    );
                    $ch = curl_init();
                    curl_setopt($ch, CURLOPT_URL, 'https://wallet.free-kassa.ru/api_v1.php');
                    curl_setopt($ch, CURLOPT_HEADER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
                    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
                    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                    curl_setopt($ch, CURLOPT_POST, 1);
                    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
                    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
                    $result = trim(curl_exec($ch));
                    $c_errors = curl_error($ch);
                    curl_close($ch);
                

Пример ответа:
    {"status":"info","desc":"Payment send"}

Форма оплаты

Чтобы разместить форму оплаты, вставьте на страницу следующий код
<a href="#" onclick="load_form()">Оплатить</a>
<script src="//www.free-kassa.ru/widget/w.js"></script>

<script type="text/javascript">
    function load_form() {
        var form = new FK();
        form.loadWidget({
            merchant_id: 'MERCHANT_ID',
            amount: 'AMOUNT',
            order_id: 'ORDER_ID',
            email: 'EMAIL',
            phone: 'PHONE',
            sign: 'SIGN',
        });
    }
</script>

                
Обязательные параметры:
MERCHANT_ID ID Вашего магазина на сервисе Free-kassa.ru
AMOUNT Сумма оплаты
ORDER_ID Номер заказа
sign Контрольная подпись MD5, формируется из вашего Merchant ID и Секретного слова 1, например
md5('1011'.'SECRETWORD')
Необязательные параметры:
EMAIL Email клиента
PHONE Телефон клиента