Документация JSON API
JSON API протокол PayKeeper предназначен для полностью автоматического управления приёмом платежей. С помощью данного протокола можно в автоматическом режиме производить отправку счетов, совершать возвраты, узнавать статус платежей и т. д. Мы рекомендуем использовать его в случае необходимости интеграции с биллинговыми или бухгалтерскими системами, самописными, либо сильно измененными CMS системами, мобильными приложениями и другими системами, когда применения базовых средств интеграции недостаточно.
JSON-запросы выполняются на сервер, на котором расположен PayKeeper. Каждый запрос должен иметь заголовок Authorization: Basic для Basic HTTP-авторизации.
Для POST-запросов должен передаваться заголовок Content-Type: application/x-www-form-urlencoded.
Для удобства использования протокол JSON API разбит на следующие разделы:
- Общая статистика принимаемых платежей по различным платёжным системам и датам.
- Получение информации о платежах, выполнение полного и частичного возврата платежей. Работа с реестром платежей с возможностью фильтрации по «Статусам», «Датам», «Платёжным системам».
- Работа с электронными счетами, выставление счетов на e-mail, дублирование старых счетов. Работа с реестром электронных счетов, отображение с возможностью фильтрации по датам и статусам.
- Получение информации о системе.
- Изменение внутренней конфигурации системы.
- Экспорт данных из системы. Экспорт списков платежей, счетов.
- Работа с чеками по 54-ФЗ, создание чеков. Работа с реестром чеков, отображение с возможностью фильтрации по типам и фискальным атрибутам.
- Работа с привязкой карт и проведением платежей по привязкам.
Любые запросы на чтение данных выполняются GET запросами, на изменение данных на сервере или совершение каких-либо действий POST запросами. Для подписи POST запросов используется специально сгенерированный token (Подробнее в разделе Токен безопасности.)
В случае успешного выполнения запроса возвращается JSON кодированный объект:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
[ { "id":"97452", "pay_amount":"1.00", "refund_amount":"0.00", "clientid":"Ivan Ivanov", "orderid":null, "payment_system_id":"3", "unique_id":null, "status":"success", "repeat_counter":"0", "pending_datetime":"2014-05-14 15:59:00", "obtain_datetime":"2014-05-14 15:59:01", "success_datetime":"2014-05-14 15:59:01" }, ... ] |
В случае логической ошибки в ответе возвращается объект ошибки:
|
1 2 3 4 |
{ "result":"fail", "msg":"Error description" } |
Объект ошибки содержит два поля – result, всегда равное fail, и поле msg со словесным пояснением причины ошибки для отображения пользователю.
Примеры использования JSON API протокола: