2. Платежи

Раздел протокола «Платежи» предназначен для работы с платежами. С помощью запросов можно получать информацию о платежах, загружать различные реестры платежей с применением фильтрации по датам, статусам, платежным системам, осуществлять поиск, а также полностью или частично возвращать платежи и подтверждать списание.

Для инициализации платежа нужно использовать выставление счета, HTML-Форму, IFRAME-Форму или получение прямой ссылки на оплату.

Статусы платежей изменяются в соответствии с диаграммой состояний. Статусы «получен» (obtained), «совершён без оповещения» (stuck), «совершён» (success) эквивалентны с точки зрения поступления средств на расчётный счёт предприятия. Все они означают, что у держателя была списана сумма транзакции, и она либо уже зачислилась, либо в ближайшее время зачислится на расчётный счёт предприятия. Статусы «отменён» (canceled) и «не состоялся» (failed) означают, что платеж провести не удалось.

Диаграмма статусов платежей

Раздел протокола содержит следующие запросы:

  URI Назначение
2.1 /info/payments/bydate/ Получение реестра платежей за период, с фильтром по статусам и платёжным системам.
2.2 /info/payments/bydatecount/ Получение количества платежей за период, сгруппированное по статусам и по платежным системам
2.3 /info/payments/byid/ Получение информации о платеже по идентификатору
2.4 /info/options/byid/ Получение дополнительной информации об опциях платежа
2.5 /info/params/byid/ Получение дополнительных необязательных параметров платежа
2.6 /info/httplog/byid/ Отображает информацию об HTTP запросе по идентификатору платежа
2.7 /info/refunds/bypaymentid/ Отображает информацию по возвратам для данного платежа
2.8 /change/payment/reverse/ Полный или частичный возврат платежа
2.9 /change/payment/repeatcnt/ Сброс счетчика повтора оповещений для платежа
2.10 RESERVE Запрос на инициализацию платежа
2.11 /info/payments/search/ Поиск платежа по значениям параметров в диапазоне дат
2.12 /change/payment/capture/ Подтверждение списания средств по ранее авторизованной операции

 

2.1. Запрос получения реестра платежей /info/payments/bydate/

Запрос возвращает реестр платежей за период. Для удобства вывода в таблицу можно указать максимальное число объектов в выборке и пропустить первые сколько-то значений. Также можно выбрать платежи только с определёнными статусами. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/payments/bydate/?limit=100&from=0&start=2016-04-14&end=2017-03-14&
status[]=success&status[]=canceled&status[]=failed&payment_system_id[]=9&payment_system_id[]=1
  Параметр Назначение
1. start Дата начала периода в формате YYYY-MM-DD
2. end Дата конца периода в формате YYYY-MM-DD
3. payment_system_id[] Идентификатор платежной системы. Применяется для фильтрации по платежной системе. Обязательный параметр.
4. status[] Статус платежей. Применяется для фильтрации платежей по статусам. Может принимать значения: ‘pending’, ‘obtained’, ‘canceled’, ‘success’, ‘failed’, ‘stuck’, ‘refunded’, ‘refunding’, ‘partially_refunded’. Обязательный параметр.
5. from Пропускает первые N значений. Обязательный параметр.
6. limit Количество возвращаемых значений. Обязательный параметр.
Таблица 2.1.1. Параметры запроса

В ответ возвращается объект следующего вида:

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор платежа
2. pay_amount Сумма платежа
3. refund_amount Возвращенная часть платежа
4. clientid Идентификатор клиента в системе магазина
5. orderid Номер заказа в системе магазина
6. payment_system_id Идентификатор платежной системы
7. unique_id Уникальный идентификатор транзакции
8. status Статус платежа
9. repeat_counter Количество отправленных запросов при проведении платежа в систему
магазина
10. pending_datetime Дата/Время создания платежа
11. obtain_datetime Дата/Время проведения платежа
12. success_datetime Дата/Время информирования магазина о проведенном платеже
Таблица 2.1.2 Параметры ответа на запрос

Пример ответа на запрос:

 

2.2. Запрос получения количества платежей за период /info/payments/bydatecount/

Запрос возвращает количество платежей за период. Запрос возвращает данные, сгруппированные по статусам и сгруппированные по платежным системам. Также запрос возвращает полную сумму платежей за этот период. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/payments/bydatecount/?start=2014-04-14&end=2014-05-14&
status[]=success&status[]=canceled&status[]=failed&payment_system_id[]=6&payment_system_id[]=1
  Параметр Назначение
1. start Дата начала периода в формате
YYYY-MM-DD
2. end Дата конца периода в формате
YYYY-MM-DD
3. payment_system_id[] Идентификатор платежной системы. Применяется для фильтрации по платежной системе.
4. status[] Статус платежей. Применяется для фильтрации платежей по статусам. Может принимать значения: ‘pending’, ‘obtained’, ‘canceled’, ‘success’, ‘failed’, ‘stuck’, ‘refunded’, ‘refunding’, ‘partially_refunded’.
Таблица 2.2.1. Параметры запроса

В ответ возвращается составной объект следующего вида:

  1. Массив с платежами, сгруппированный по статусам.
  2. Массив с платежами, сгруппированный по платежным системам.
  3. Полный счетчик всех платежей с учетом фильтров.
Тип Формат ответа
  Параметр Назначение
1. statuses Массив, сгруппированный по различным статусам, состоящий из элементов [status=>”value”,count=>”value”]
2. payment_systems Массив, сгруппированный по различным платежным системам [payment_system_id=>”value”,count=>”value”]
3. fullcount Полное количество платежей
Таблица 2.2.2 Параметры ответа на запрос

Пример ответа на запрос:

 

2.3. Запрос получения информации о платеже по идентификатору /info/payments/byid/

Запрос возвращает информацию о платеже по его идентификатору в PayKeeper. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/payments/byid/?id=11186
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper
Таблица 2.3.1. Параметры запроса

В ответ возвращается объект следующего вида:

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор платежа
2. pay_amount Сумма платежа
3. refund_amount Возвращенная часть платежа
4. clientid Идентификатор клиента в системе магазина
5. orderid Номер заказа в системе магазина
6. payment_system_id Идентификатор платежной системы
7. site_description Системное название платежной системы
8. system_description Название платежной системы
9. unique_id Уникальный идентификатор транзакции
10. status Статус платежа
11. repeat_counter Количество отправленных запросов при проведении платежа в систему
магазина
12. pending_datetime Дата/Время создания платежа
13. obtain_datetime Дата/Время проведения платежа
14. success_datetime Дата/Время информирования магазина о проведенном платеже
Таблица 2.3.2 Параметры ответа на запрос

Пример ответа на запрос:

 

2.4. Запрос получение дополнительной информации об опциях платежа /info/options/byid/

Запрос возвращает дополнительную информацию об опциях платежа по его идентификатору в PayKeeper. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/options/byid/?id=11186
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper
Таблица 2.4.1. Параметры запроса

Ответ на запрос может содержать различные параметры, в зависимости от платежной системы и статуса платежа. Мы рекомендуем использовать эти данные только в качестве дополнительной информации и не строить логику работы информационной системы в зависимости от их значений.

Пример возвращаемого объекта:

 

2.5. Запрос получения дополнительных необязательных параметров платежа /info/params/byid/

Запрос возвращает дополнительные параметры платежа, передаваемые платежными системами. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/params/byid/?id=11186
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper
Таблица 2.5.1. Параметры запроса

Ответ на запрос содержит массив параметров платежа в следующем формате.

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор
2. payment_id Идентификатор платежа
3. field Ключ
4. value Значение
Таблица 2.5.2 Параметры ответа на запрос

Пример возвращаемого объекта:

 

2.6. Запрос получения HTTP параметров платежа /info/httplog/byid/

Запрос возвращает HTTP параметры запросов платежа по его идентификатору в системе PayKeeper. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/httplog/byid/?id=11186
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper
Таблица 2.6.1. Параметры запроса

Ответ на запрос содержит массив параметров платежа в следующем формате.

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор
2. payment_id Идентификатор платежа
3. request_method Тип HTTP запроса
4. request_uri URI Запроса
5. ip IP Адрес запроса
6. body Тело запроса
7. datetime Дата/Время запроса
Таблица 2.6.2 Параметры ответа на запрос

Пример возвращаемого объекта:

 

2.7. Запрос информации по возвратам для платежа /info/refunds/bypaymentid/

Запрос возвращает информацию о возвратах, выполненных по данному платежу. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.

Тип Формат запроса
GET /info/refunds/bypaymentid/?id=124076
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper
Таблица 2.7.1. Параметры запроса

По одному платежу может быть несколько возвратов. Ответ на запрос содержит массив параметров платежа в следующем формате.

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор возврата
2. payment_id Идентификатор платежа
3. refund_number Порядковый номер возврата по данному платежу
4. user Пользователь, инициировавший возврат
5. amount Сумма возврата
6. reminder Остаток после возврата
7. datetime Дата/Время проведения возврата
8. status Статус возврата. Принимает значения «started», «done», «failed»
Таблица 2.7.2 Параметры ответа на запрос

Пример возвращаемого объекта:

 

2.8. Запрос на возврат платежа /change/payment/reverse/

Данный метод автоматически определяет, будет выполнен полный возврат или отмена авторизации, частичный возврат или частичное списание в зависимости от состояния платежа на момент выполнения возврата и возможностей банка-эквайера.
Если система работает в режиме автоматической генерации фискальных чеков 54-ФЗ, то в этом запросе может дополнительно передаваться информация о товарах к возврату. В случае, если у исходного платежа была указана корзина с товарами, то при полном возврате корзину можно не указывать, а при частичном корректная корзина необходима для формирования корректного чека 54-ФЗ. Если корзина товара указана неверно, то на проведение возврата это не повлияет, но чек сгенерирован не будет. Если платёж на момент выполнения запроса был авторизован, то чек будет сгенерирован только на сумму частичного списания.

Запрос возвращает платеж полностью или частично. Возврат могут делать только пользователи с включённой функцией возврата. Для возврата платежа необходимо выполнить POST-запрос со следующими параметрами.

Тип Формат запроса
POST /change/payment/reverse/
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper.
2. amount Возвращаемая сумма, разделитель точка.
3. partial Признак частичного возврата, может принимать значения true/false. В случае полного возврата, сумма возврата должна быть указана.
4. token Токен безопасности.
5. refund_cart Массив товаров к возврату. JSON-строка в таком же формате, что и при инициализации платежа.
Таблица 2.8.1. Параметры запроса

В случае успешного выполнения результатом данного запроса будет объект:

В случае возникновения ошибки будет возвращен объект с расшифровкой ошибки:

Возврат происходит в асинхронном режиме, поэтому сама по себе инициализация возврата не является гарантией его успешного выполнения. Для автоматического контроля возвратов рекомендуется использовать поисковый метод 2.1 (с выбором платежей со статусом refunding ), чтобы отслеживать появление незавершённых возвратов, либо контролировать проведение возврата по конкретному платежу запросом 2.7. На выполнение возврата обычно требуется до нескольких минут, поэтому рекомендуется проверять результат выполнения возврата через 3 минуты. Также PayKeeper может отправлять callback-запрос с уведомлением о состоявшемся возврате. Эта возможность включается в конфигурации сервера с PayKeeper.

2.9. Запрос на сброс счетчика повторов для платежа /change/payment/repeatcnt/

Запрос сбрасывает счетчик оповещений для платежа и инициирует работу информера PayKeeper. Для сброса счетчика необходимо выполнить POST-запрос со следующими параметрами.

Тип Формат запроса
POST /change/payment/repeatcnt/
  Параметр Назначение
1. id Идентификатор платежа в системе PayKeeper.
2. token Токен безопасности.
Таблица 2.9.1. Параметры запроса

В случае успешного выполнения результатом данного запроса будет объект:

Подробнее о работе информера можно прочесть в разделе Приём POST оповещений

 

2.11. Поиск платежей по значениям параметров в диапазоне дат /info/payments/search/

Запрос возвращает платежи, чьи номера, параметры оплаты, номера карт или коды авторизаций содержат указанную в запросу подстроку. Поиск осуществляется в пределах диапазона дат, который задаётся параметрами запроса.

Тип Формат запроса
GET /info/payments/search/?query=4038*9682&beg_date=2016-01-01&end_date=2017-04-04
  Параметр Назначение
1. query Подстрока для поиска в параметрах платежа id и clientid, а также в опциях orderid, service_name, client_email, client_phone, CARD_NUMBER, APPROVAL_CODE. Поиск поддерживает синтаксис MySQL like. Символ * заменяется на %.
2. beg_date Дата начала периода в формате YYYY-MM-DD.
3. end_date Дата конца периода в формате YYYY-MM-DD.
Таблица 2.11.1. Параметры запроса

Ответ на запрос содержит массив объектов следующего вида.

Тип Формат ответа
  Параметр Назначение
1. id Номер платежа
2. clientid Идентификатор плательщика
3. orderid Номер заказа
4. unique_id Идентификатор транзакции, назначенный Банком
5. pay_amount Сумма платежа
6. status Статус платежа
7. payment_system_id Идентификатор платёжной системы
8. repeat_counter Количество попыток оповещения ТСП об успешности платежа
9. pending_datetime Дата/время начала операции
10. success_datetime Дата/Время проведения платежа
11. success_datetime Дата/Время информирования магазина о проведенном платеже
Таблица 2.11.2 Параметры ответа на запрос

Пример возвращаемого массива:

 

2.12. Списание средств по ранее проведённой авторизации /change/payment/capture/

В случае, если необходимо списать средства по ранее выполненной авторизации, не дожидаясь автосписания, следует воспользоваться данным запросом. Для выполнения частичного списания нужно использовать запрос 2.8.

Тип Формат запроса
POST /change/payment/capture/
  Параметр Назначение
1. id Номер платежа к списанию
2. token Токен безопасности.
Таблица 2.12.1. Параметры запроса

Ответ на запрос содержит объект с результатом операции, либо объект ошибки. Успешный результат операции означает принятие запроса Банком, но не его исполнение. Проверку успешности списания необходимо выполнить спустя несколько минут при помощи запроса 2.4.

Тип Формат ответа
  Параметр Назначение
1. result Номер платежа
Таблица 2.12.2 Параметры ответа на запрос

Пример возвращаемого объекта:

 

Запросы 2.* и личный кабинет PayKeeper

Рассмотренные выше запросы также используются в личном кабинете PayKeeper. Чтобы назначение запросов было более наглядным на приведенном ниже скриншоте отмечено, какие запросы используются для реализации функций личного кабинета.

Личный кабинет PayKeeper — Раздел платежи