Merchant API
Введение
Данная документация предназначена для разработчиков, осуществляющих интеграцию с Merchant API FirstPay. В документе описаны основные принципы взаимодействия с API, форматы запросов и ответов, формирование и проверка подписи, создание и обработка платежей, а также механика работы с платежами через банковские карты и баланс мобильного телефона.
Документация содержит описание необходимых параметров, примеры запросов и ответов, тестовые данные и рекомендации по обработке результатов платежей. Для корректной интеграции рекомендуется последовательно ознакомиться с разделами документации и учитывать обязательные параметры, указанные для каждого метода.
Данная документация предназначена для разработчиков, осуществляющих интеграцию с Merchant API FirstPay. В документе описаны основные принципы взаимодействия с API, форматы запросов и ответов, формирование и проверка подписи, создание и обработка платежей, а также механика работы с платежами через банковские карты и баланс мобильного телефона.
Документация содержит описание необходимых параметров, примеры запросов и ответов, тестовые данные и рекомендации по обработке результатов платежей. Для корректной интеграции рекомендуется последовательно ознакомиться с разделами документации и учитывать обязательные параметры, указанные для каждого метода.
Механика запросов
API поддерживает GET запросы и POST запросы с Content-type равным form-data или x-www-form-urlencoded
Данные можно отправлять:
API поддерживает GET запросы и POST запросы с Content-type равным form-data или x-www-form-urlencoded
Данные можно отправлять:
- Метод GET - данные передаются в GET параметрах, при передаче сложных структурированных данных, таких как многомерные массивы, используется следующий формат записи: https://api.firstpay.kz/script.php?param_1=val¶m_2[subParam_1]=val2& param_2[subParam_2]=val3¶m_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>
Формирование подписи
Любые сообщения (запросы и ответы) между Firstpay и мерчантом подписываются. Для формирования подписи необходимо конкатенировать с разделителем;
• имя вызываемого скрипта (от последнего / до конца или ?)
b. поля с одинаковыми именами берутся в том порядке, в котором они присутствуют в сообщении
• и платежный пароль secret_key, который задается в настройках магазина и известен только мерчанту и Firstpay.
От полученной в результате конкатенации строки необходимо вычислить md5 и добавить в запрос или ответ в качестве дополнительного параметра pg_sig. MD5 хэш записывается в виде шестнадцатеричной строки в нижнем регистре (32 символа).
Любая сторона может добавлять в запрос или ответ дополнительные параметры, не указанные в документации. Эти параметры также участвуют в вычислении подписи. Сообщение не подписывается, и соответственно поля pg_salt и pg_sig отсутствуют только в одном случае – когда Firstpay не смог идентифицировать мерчанта и поэтому не знает его secret_key. В таком случае поле pg_error_code (числовой код ошибки) принимает значение 101. Полный список возможных значений поля pg_error_code см. в разделе Справочник кодов ошибок.
Есть два варианта использования метода:
• Прямая передача данных от мерчанта в Firstpay
• Передача данных через браузер пользователя в Firstpay
При прямой передаче данных от мерчанта в Firstpay, мерчант должен посылать данные на init_payment.php.
При передаче данных через браузер пользователя в Firstpay, мерчант должен направить пользователя с данными на payment.php.
Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.
Имена дополнительных параметров мерчанта должны быть уникальны.
После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу, где плательщик завершает платеж.
В случае успеха пользователь будет перенаправлен на страницу оплаты.
В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте http://firstpay.kz .
Любые сообщения (запросы и ответы) между Firstpay и мерчантом подписываются. Для формирования подписи необходимо конкатенировать с разделителем;
• имя вызываемого скрипта (от последнего / до конца или ?)
• все поля сообщения в алфавитном порядке, включая случайную строку pg_salt, состоящую из произвольного количества цифр и латинских букв, при этом:
a. к вложенным тегам это правило применяется рекурсивно (только XML)b. поля с одинаковыми именами берутся в том порядке, в котором они присутствуют в сообщении
• и платежный пароль secret_key, который задается в настройках магазина и известен только мерчанту и Firstpay.
От полученной в результате конкатенации строки необходимо вычислить md5 и добавить в запрос или ответ в качестве дополнительного параметра pg_sig. MD5 хэш записывается в виде шестнадцатеричной строки в нижнем регистре (32 символа).
Любая сторона может добавлять в запрос или ответ дополнительные параметры, не указанные в документации. Эти параметры также участвуют в вычислении подписи. Сообщение не подписывается, и соответственно поля pg_salt и pg_sig отсутствуют только в одном случае – когда Firstpay не смог идентифицировать мерчанта и поэтому не знает его secret_key. В таком случае поле pg_error_code (числовой код ошибки) принимает значение 101. Полный список возможных значений поля pg_error_code см. в разделе Справочник кодов ошибок.
Есть два варианта использования метода:
• Прямая передача данных от мерчанта в Firstpay
• Передача данных через браузер пользователя в Firstpay
При прямой передаче данных от мерчанта в Firstpay, мерчант должен посылать данные на init_payment.php.
При передаче данных через браузер пользователя в Firstpay, мерчант должен направить пользователя с данными на payment.php.
Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.
Имена дополнительных параметров мерчанта должны быть уникальны.
После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу, где плательщик завершает платеж.
В случае успеха пользователь будет перенаправлен на страницу оплаты.
В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте http://firstpay.kz .
Тестовые карты
Все новые мерчанты первоначально находятся в тестовом режиме, затем после завершения тестирования и отправки мерчантом в Firstpay подписанного Акта о подключении администрация Firstpay переводит мерчант в рабочий режим.
В тестовом режиме можно использовать только тестовые платежные методы, а в рабочем режиме, наоборот, оплата тестовыми платежными методами невозможна.
После перехода мерчанта в рабочий режим можно создавать отдельные транзакции в тестовом режиме, передавая параметр pg_testing_mode в запросах на создание платежа и на получение списка платежных методов. Значение pg_testing_mode=1 включает тестовый режим для одной конкретной транзакции. Для проведения тестовых транзакций в боевом режиме необходимо обратится менеджеру для уточнения деталей.
Если сам мерчант находится в тестовом режиме, то значение переданного флага pg_testing_mode не имеет значения. Включение и выключение тестового режима в настройках мерчанта осуществляется только администрацией Firstpay.
После создания транзакции никаких автоматических действий с ней не происходит. Для того, чтобы протестировать дальнейшее прохождение транзакции нужно зайти в административную панель, и войти в транзакцию. Далее управлять ее действиями с помощью тестовых кнопок.
В качестве имени карте нужно указывать от 2 слов в английской раскладке.
Пароль для 3-D Secure проверки: 12345678
Список тестовых карт:
Все новые мерчанты первоначально находятся в тестовом режиме, затем после завершения тестирования и отправки мерчантом в Firstpay подписанного Акта о подключении администрация Firstpay переводит мерчант в рабочий режим.
В тестовом режиме можно использовать только тестовые платежные методы, а в рабочем режиме, наоборот, оплата тестовыми платежными методами невозможна.
После перехода мерчанта в рабочий режим можно создавать отдельные транзакции в тестовом режиме, передавая параметр pg_testing_mode в запросах на создание платежа и на получение списка платежных методов. Значение pg_testing_mode=1 включает тестовый режим для одной конкретной транзакции. Для проведения тестовых транзакций в боевом режиме необходимо обратится менеджеру для уточнения деталей.
Если сам мерчант находится в тестовом режиме, то значение переданного флага pg_testing_mode не имеет значения. Включение и выключение тестового режима в настройках мерчанта осуществляется только администрацией Firstpay.
После создания транзакции никаких автоматических действий с ней не происходит. Для того, чтобы протестировать дальнейшее прохождение транзакции нужно зайти в административную панель, и войти в транзакцию. Далее управлять ее действиями с помощью тестовых кнопок.
В качестве имени карте нужно указывать от 2 слов в английской раскладке.
Пароль для 3-D Secure проверки: 12345678
Список тестовых карт:
Тестовые номера телефонов
Механика мобильной коммерции подразумевает тестирование в рамках ряда операторов.
Ниже будут предоставлены номера и соответствующие им OTP коды для проведения тестов
Список номеров:
Механика мобильной коммерции подразумевает тестирование в рамках ряда операторов.
Ниже будут предоставлены номера и соответствующие им OTP коды для проведения тестов
Список номеров: