Merchant API

Введение

О сервисе

FreedomPay - универсальное средство приема платежей для бизнеса.

Сервис предоставляет возможность приема платежей, выплат на банковские карты, а также сохранения карт. Базовые сценарии описаны в разделе "Сценарии платежа".

Сценарии разделены на три части:
  • Прием платежей. В этом разделе описана механика, при которой FreedomPay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.
  • Выплаты. В этом разделе описана механика, когда FreedomPay выплачивает деньги на банковскую карту пользователя.
  • Сохранение карт. Базовая механика сохранения карт. Далее сохраненные карты можно использовать как для приема платежей так и для выплат.
Каждый сценарий документации содержит все запросы которые можно выполнить для реализации выбранного сценария.

Работа с Postman
Данная документация доступна в виде Postman коллекции для HTTP-клиента Postman
Коллекция активно работает с переменными окружения Postman.
Run in Postman
Реализована динамическая генерация подписи с помощью Pre-request scripts. При правильной настройке переменных, параметр подписи будет генерироваться для каждого запроса автоматически(в консоли можно смотреть из чего была сгенерирована подпись).

Основные переменные окружения для работы с Postman:
Дополнительные переменные окружения:
Механика запросов

API поддерживает GET запросы и POST запросы с Content-type равным form-data или x-www-form-urlencoded

Данные можно отправлять:
  • Метод GET - данные передаются в GET параметрах, при передаче сложных структурированных данных, таких как многомерные массивы, используется следующий формат записи: https://api.freedompay.kz/script.php?param_1=val&param_2[subParam_1]=val2& param_2[subParam_2]=val3&param_3=val4
  • Метод POST – данные передаются в POST параметрах. Структурные данные при работе через POST, формируются аналогичным образом.
  • Через XML - запросы передаются также методом Post, только в единственном параметре pg_xml, представленный в XML виде:
Пример:

<?xml version="1.0" encoding="utf-8"?><request><pg_param1>value1</pg_param><pg_param2>value2</pg_param></request>
Формирование подписи

Любые сообщения (запросы и ответы) между FreedomPay и мерчантом подписываются. Для формирования подписи необходимо конкатенировать с разделителем;

  1. имя вызываемого скрипта (от последнего / до конца или ?)
  2. все поля сообщения в алфавитном порядке, включая случайную строку pg_salt, состоящую из произвольного количества цифр и латинских букв, при этом:
  3. a. к вложенным тегам это правило применяется рекурсивно (только XML)
  4. b. поля с одинаковыми именами берутся в том порядке, в котором они присутствуют в сообщении
  5. и платежный пароль secret_key, который задается в настройках магазина и известен только мерчанту и FreedomPay.

От полученной в результате конкатенации строки необходимо вычислить md5 и добавить в запрос или ответ в качестве дополнительного параметра pg_sig. MD5 хэш записывается в виде шестнадцатеричной строки в нижнем регистре (32 символа).

Любая сторона может добавлять в запрос или ответ дополнительные параметры, не указанные в документации. Эти параметры также участвуют в вычислении подписи. Сообщение не подписывается, и соответственно поля pg_salt и pg_sig отсутствуют только в одном случае – когда FreedomPay не смог идентифицировать мерчанта и поэтому не знает его secret_key. В таком случае поле pg_error_code (числовой код ошибки) принимает значение 101. Полный список возможных значений поля pg_error_code см. в разделе Справочник кодов ошибок.

Тестовые номера телефонов
Механика мобильной коммерции подразумевает тестирование в рамках ряда операторов.
Ниже будут предоставлены номера и соответствующие им OTP коды для проведения тестов

Список номеров: