2. Платежи
Раздел протокола «Платежи» предназначен для работы с платежами. С помощью запросов можно получать информацию о платежах, загружать различные реестры платежей с применением фильтрации по датам, статусам, платежным системам, осуществлять поиск, а также полностью или частично возвращать платежи и подтверждать списание.
Для инициализации платежа нужно использовать выставление счета, HTML-Форму, IFRAME-Форму или получение прямой ссылки на оплату.
Статусы платежей изменяются в соответствии с диаграммой состояний. Статусы «получен» (obtained), «совершён без оповещения» (stuck), «совершён» (success) эквивалентны с точки зрения поступления средств на расчётный счёт предприятия. Все они означают, что у держателя была списана сумма транзакции, и она либо уже зачислилась, либо в ближайшее время зачислится на расчётный счёт предприятия. Статусы «отменён» (canceled) и «не состоялся» (failed) означают, что платеж провести не удалось.
Диаграмма статусов платежей
Раздел протокола содержит следующие запросы:
2.13/change/payment/post-sale-receipt/Сгенерировать чек окончательного расчёта
| 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 | НЕ ПОДДЕРЖИВАЕТСЯ | Запрос на инициализацию платежа |
| 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 Параметры ответа на запрос | ||
Пример ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
[ { "id": "136641", "pay_amount": "1000.00", "refund_amount": "0.00", "clientid": null, "orderid": null, "payment_system_id": "6", "unique_id": "Rj5er56P5ItOLxi0uuptDER7NM=", "status": "canceled", "repeat_counter": "0", "pending_datetime": "2017-03-17 16:44:30", "obtain_datetime": null, "success_datetime": null }, { "id": "136640", "pay_amount": "2150.00", "refund_amount": "0.00", "clientid": "Оплата за кресло-качалку", "orderid": "Петров Иван Сергеевич", "payment_system_id": "6", "unique_id": "xONlvdy91aB+N3I21n1WE5/5ZqEg=", "status": "success", "repeat_counter": "0", "pending_datetime": "2017-03-15 16:54:49", "obtain_datetime": "2017-03-15 16:56:26", "success_datetime": "2017-03-15 16:56:30" }, ... ] |
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. | statuses | Массив, сгруппированный по различным статусам, состоящий из элементов [status=>”value”,count=>”value”] |
| 2. | payment_systems | Массив, сгруппированный по различным платежным системам [payment_system_id=>”value”,count=>”value”] |
| 3. | fullcount | Полное количество платежей |
| Таблица 2.2.2 Параметры ответа на запрос | ||
Пример ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
[ { "statuses": [ {"status":"canceled","count":"14"}, {"status":"success","count":"71"}, {"status":"failed","count":"3"} ] }, { "payment_systems": [ {"payment_system_id":"1","count":"47"}, {"payment_system_id":"6","count":"41"} ] }, { "fullcount": [ {"count":"88"} ] } ] |
2.3. Запрос получения информации о платеже по идентификатору /info/payments/byid/
Запрос возвращает информацию о платеже по его идентификатору в платёжную платформу. Для получения данных необходимо выполнить 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 Параметры ответа на запрос | ||
Пример ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
[ { "id": "11186", "pay_amount": "12000.00", "refund_amount": "0.00", "clientid": "ivan.petrov@mail.ru", "orderid": "7916", "payment_system_id": "40", "site_description": "Рсбанк", "system_description": "Rosbank", "unique_id": "8613d9ab-1234-4678-9014-0f3489dcaba4", "status": "success", "repeat_counter": "0", "pending_datetime": "2017-03-21 14:25:33", "obtain_datetime": "2017-03-21 14:29:48", "success_datetime": "2017-03-21 14:30:02" } ] |
2.4. Запрос получение дополнительной информации об опциях платежа /info/options/byid/
Запрос возвращает дополнительную информацию об опциях платежа по его идентификатору в платёжную платформу. Для получения данных необходимо выполнить GET-запрос со следующими параметрами.
| Тип | Формат запроса | |
| GET | /info/options/byid/?id=11186 | |
| Параметр | Назначение | |
| 1. | id | Идентификатор платежа в системе PayKeeper |
| Таблица 2.4.1. Параметры запроса | ||
Ответ на запрос может содержать различные параметры, в зависимости от платежной системы и статуса платежа. Мы рекомендуем использовать эти данные только в качестве дополнительной информации и не строить логику работы информационной системы в зависимости от их значений.
Пример возвращаемого объекта:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
[ { "orderid": "7916", "client_ip": "109.252.85.68", "service_name": "Uslugi po perevodu", "client_email": "info@example.com", "client_phone": "+79112511000", "qiwi_phone": "", "msgtype": "Visa", "RRN": "304756189111", "APPROVAL_CODE": "186111", "CARD_NUMBER": "472732**2524", "actionCode": "0", "actionCodeDescription": "", "orderStatus": "2", "preauth": "false" } ] |
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 Параметры ответа на запрос | ||
Пример возвращаемого объекта:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
[ { "id": "282", "payment_id": "11186", "field": "0/value", "value": "86ead1ab-111d-4aa6-8daf-01119bbaaa1" }, { "id": "283", "payment_id": "11186", "field": "1/name", "value": "service_name" }, { "id": "284", "payment_id": "11186", "field": "1/value", "value": "null" }, { "id": "285", "payment_id": "11186", "field": "2/name", "value": "client_email" }, { "id": "286", "payment_id": "11186", "field": "2/value", "value": "null" }, { "id": "287", "payment_id": "11186", "field": "cardAuthInfo/expiration", "value": "202109" }, { "id": "288", "payment_id": "11186", "field": "cardAuthInfo/cardholderName", "value": "Ivan Petrov" } ] |
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 Параметры ответа на запрос | ||
Пример возвращаемого объекта:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
[ { "id": "176325", "payment_id": "11186", "request_method": "POST", "request_uri": "/order/inline/", "ip": "187.145.22.11", "body": "orderid=7916&clientid=ivanivanov%40mail.ru&sum=120000&phone=891112345678", "datetime": "2017-03-21 14:25:20" } ] |
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 Параметры ответа на запрос | ||
Пример возвращаемого объекта:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
[ { "id": "1", "payment_id": "124076", "refund_number": "1", "user": "admin", "amount": "9730.00", "remainder": "0.00", "datetime": "2017-02-10 10:58:36", "status": "done" } ] |
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. Параметры запроса | ||
В случае успешного выполнения результатом данного запроса будет объект:
|
1 2 3 4 5 |
[ { "result" : "success" } ] |
В случае возникновения ошибки будет возвращен объект с расшифровкой ошибки:
|
1 2 3 4 5 6 7 |
[ { "result": "fail", "msg": 'Нельзя сделать возврат по платежу, статус которого не "совершён", "получен" или "превышено число повторов"' } ] |
Возврат происходит в асинхронном режиме, поэтому сама по себе инициализация возврата не является гарантией его успешного выполнения. Для автоматического контроля возвратов рекомендуется использовать поисковый метод 2.1 (с выбором платежей со статусом refunding ), чтобы отслеживать появление незавершённых возвратов, либо контролировать проведение возврата по конкретному платежу запросом 2.7. На выполнение возврата обычно требуется до нескольких минут, поэтому рекомендуется проверять результат выполнения возврата через 3 минуты. Также платёжная платформа может отправлять callback-запрос с уведомлением о состоявшемся возврате. Эта возможность включается в конфигурации сервера с платёжной платформы.
2.9. Запрос на сброс счетчика повторов для платежа /change/payment/repeatcnt/
Запрос сбрасывает счетчик оповещений для платежа и инициирует работу информера PayKeeper. Для сброса счетчика необходимо выполнить POST-запрос со следующими параметрами.
| Тип | Формат запроса | |
| POST | /change/payment/repeatcnt/ | |
| Параметр | Назначение | |
| 1. | id | Идентификатор платежа в системе PayKeeper. |
| 2. | token | Токен безопасности. |
| Таблица 2.9.1. Параметры запроса | ||
В случае успешного выполнения результатом данного запроса будет объект:
|
1 2 3 4 5 |
[ { "result" : "success" } ] |
Подробнее о работе информера можно прочесть в разделе Приём POST оповещений
2.10. Запрос на инициализацию платежа НЕ ПОДДЕРЖИВАЕТСЯ
В настоящее время не используется
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. | obtain_datetime | Дата/Время проведения платежа |
| 11. | success_datetime | Дата/Время информирования магазина о проведенном платеже |
| Таблица 2.11.2 Параметры ответа на запрос | ||
Пример возвращаемого массива:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
[ { "id": "124134", "pay_amount": "1.00", "clientid": "Иванов Петр Семенович", "orderid": "325009", "payment_system_id": "6", "unique_id": "Nhf+fl3l8Rz/rvCEtMNCVm12Ew=", "status": "success", "repeat_counter": "0", "pending_datetime": "2017-03-30 13:20:59", "obtain_datetime": "2017-03-30 13:21:43", "success_datetime": "2017-03-30 13:21:47" }, ... ] |
2.12. Списание средств по ранее проведённой авторизации /change/payment/capture/
В случае, если необходимо списать средства по ранее выполненной авторизации, не дожидаясь автосписания, следует воспользоваться данным запросом. Для выполнения частичного списания нужно использовать запрос 2.8.
| Тип | Формат запроса | |
| POST | /change/payment/capture/ | |
| Параметр | Назначение | |
| 1. | id | Номер платежа к списанию |
| 2. | token | Токен безопасности. |
| Таблица 2.12.1. Параметры запроса | ||
Ответ на запрос содержит объект с результатом операции, либо объект ошибки. Успешный результат операции в случае status = queued (при работе с Промсвязьбанком) означает принятие запроса Банком, но не его исполнение. Проверку успешности списания необходимо выполнить спустя несколько минут при помощи запроса 2.4.
| Тип | Формат ответа | |
| Параметр | Назначение | |
| 1. | result | Номер платежа |
| Таблица 2.12.2 Параметры ответа на запрос | ||
Пример возвращаемого объекта:
|
1 2 3 4 5 |
[ { "result" : "success" } ] |
2.13. Генерация чека окончательного расчёта /change/payment/post-sale-receipt/
Согласно закону 54-ФЗ о применении контрольно-кассовой техники при передаче товара, предварительно оплаченного через Интернет, необходимо выдать кассовый чек. Также, согласно закону, если при передаче товара не происходит дополнительного расчёта, чек может быть выдан в электронном виде. Данный метод предназначен для простого оформления чека при передаче товара.
Если у всех товарных позиций в чеке по платежу код признака расчёта был полной предоплатой, с помощью этого метода можно выдать соответствующий чек окончательного расчёта. Товарные позиции будут соответствовать товарным позициям в исходном чеке.
| Тип | Формат запроса | |
| POST | /change/payment/post-sale-receipt/ | |
| Параметр | Назначение | |
| 1. | id | Номер платежа, по которому выдаётся чек окончательного расчёта |
| Таблица 2.13.1. Параметры запроса | ||
Все товарные позиции чека окончательного расчёта будут такими же, как и в первом чеке по данному платежу. Для чеков окончательного расчёта по авансовому платежу эту функцию использовать нельзя, т.к. при окончательном расчёте должен быть указан точный перечень товаров или услуг. Сумма чека «зачёт аванса» окончательного расчёта будет равна сумме чека «электронными» первого чека по платежу. Если платёж был частично возвращён, в качестве корзины товаров будут использоваться оставшиеся товары.
Чек формируется в асинхронном режиме. Если запрос был сформирован корректно и был принят, в ответ будет возвращён объект с полем result = success и номером сгенерированного запроса на чек receipt_id. Результат формирования чека нужно проверять запросом 8.4.
Запросы 2.* и личный кабинет PayKeeper
Рассмотренные выше запросы также используются в личном кабинете PayKeeper. Чтобы назначение запросов было более наглядным на приведенном ниже скриншоте отмечено, какие запросы используются для реализации функций личного кабинета.