Интернет-эквайринг с комиссией от 1%

Принимайте платежи на сайте, в онлайн-магазине
или в соцсетях — по картам и через СБП

Главное изображение комиссия 1%

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 Параметры ответа на запрос

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

 

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. advanced Флаг для получения дополнительных опций платежа. Может принимать значение «true».
Таблица 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 Параметры ответа на запрос

Если передан флаг advanced, дополнительно возвращаются следующие параметры:

Тип Формат ответа
  Параметр Назначение
1. APPROVAL_CODE Код авторизации успешной оплаты.
2. CARD_NUMBER Замаскированный номер карты плательщика
3. RESULT Результат выполнения операции оплаты
4. RESULT_CODE Код результата выполнения операции оплаты
5. 3DSECURE Информация о том, была ли использована процедура проверки безопасности 3DSECURE в процессе оплаты.
6. RRN RRN успешной оплаты.
Таблица 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. ВАЖНО! Значения именно true/false! Значения 1/0 не воспринимаются системой.
4. sbp_refund_to Используется только в определённых случаях. Передавать не нужно.
5. token Токен безопасности.
6. 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.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 Параметры ответа на запрос

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

 

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 Параметры ответа на запрос

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

 

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. Чтобы назначение запросов было более наглядным на приведенном ниже скриншоте отмечено, какие запросы используются для реализации функций личного кабинета.

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

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

Заявка на консультацию
Оставьте заявку

Наш сотрудник свяжется с вами в ближайшее время

Получите консультацию

Расскажем про все детали подключения

Получайте платежи

Предоставим личный кабинет
и поможем настроить оплату

Мы гарантируем безопасность и сохранность ваших данных

Нажимая кнопку «Отправить заявку», вы подтверждаете, что согласны на обработку персональных данных

Ответим на вопросы и проконсультируем

+7 (800) 775-45-63 Бесплатный звонок по России

+7 (495) 984-89-15 Бесплатный звонок по Москве