Документация Free-kassa Api (1.0.0)

SCI

1. Введение

1.1. Что такое SCI?

SCI (Shop Cart Interface) — это программный интерфейс, который позволяет любому мерчанту автоматически принимать платежи в режиме онлайн.

страницы приема платежей

Демонстрация - https://pay.free-kassa.org/?bill_id=b999a12ebb6938fff283b9d609f0f8c1

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

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

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

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

Форма оплаты содержит все необходимые данные для оплаты заказа. Передается методом GET на адрес https://pay.free-kassa.org/

Параметр
Примечание
ОБЯЗАТЕЛЬНЫЕ
m ID Вашего магазина
oa Сумма платежа
o Номер заказа (также это может быть название товара или логин пользователя, для зачисления средств)
s Подпись методика формирования подписи в платежной форме
ДОПОЛНИТЕЛЬНЫЕ
i Предлагаемая валюта платежа список валют. Плательщик сможет изменить ее в процессе оплаты.
phone Телефон плательщика
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">

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

После успешной оплаты, на Ваш 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, 136.243.38.108

Пример функции на 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', '136.243.38.108'))) 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', '136.243.38.108'))) die("hacking attempt!");

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

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

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

  //Оплата прошла успешно, можно проводить операцию.

  die('YES');

1.5. Интеграция

Если у Вас уже был настроен прием платежей через платежные системы Robokassa, Interkassa или Payeer, то Вы можете с минимальными усилиями переключить прием платежей на наш сервис. Для этого в личном кабинете на странице технические данные выберите в поле "Режим интеграции" свою старую платежную систему и внесите несколько измнений в свои скрипты оплаты:

1.5.1. Robokassa

Параметр
Примечание
URL перехода В платежной форме измените урл перехода, вместо - https://auth.robokassa.ru/Merchant/Index.aspx, надо использовать - https://pay.free-kassa.org/
MrchLogin ID Вашего магазина на сервисе Free-kassa.ru
Пароль #1 Секретное слово на сервисе Free-kassa.ru
Пароль #2 Секретное слово 2 на сервисе Free-kassa.ru

Все остальные данные оставьте без изменений

Обратите внимание!
Сумму оплаты необходимо передавать (а так же использовать в подписи) без лишних нулей в дробной части. Например: 1 вместо 1.00, 1.1 вместо 1.10

1.5.2. Interkassa

Параметр
Примечание
URL перехода В платежной форме измените урл перехода, вместо - http://www.interkassa.com/lib/payment.php, надо использовать - https://pay.free-kassa.org/
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 хэш в бинарном виде

1.5.2. InSales

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

Подпись для платежной формы формируется путем нахождения 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='https://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>

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

Подпись для скрипта оповещения формируется путем нахождения MD5-хеша от строки
"ID Вашего магазина:Сумма платежа:Секретное слово 2:Номер заказа"
Пример на PHP:

  md5($_REQUEST['MERCHANT_ID'].':'.$_REQUEST['AMOUNT'].':secret2:'.$_REQUEST['MERCHANT_ORDER_ID'])

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

186 VISA/MASTERCARD KZT
133 FK WALLET RUB

Balance

Получение баланса

Получение баланса

query Parameters
merchantId
required
integer
Example: merchantId=777

ID магазина

Responses

Response samples

Content type
application/json
{
  • "id": 777,
  • "balance": 743.43,
  • "currency": "RUB"
}

Currencies

Список доступных платежных систем

Получение списка доступных платежных систем

Request Body schema: application/json
merchantId
integer

Responses

Request samples

Content type
application/json
{
  • "merchantId": 777
}

Response samples

Content type
application/json
{
  • "WMR":
    {
    },
  • "WMZ":
    {
    }
}

Shops

Список магазинов

Orders

Список заказов

Withdraw

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