Получение информации о состоянии платежа

Обзор

При работе с платёжной платформой Benker получать актуальную информацию о состоянии платежей можно разными способами (подробнее — в отдельном обзоре). Наряду с другими интерфейсами для этого могут использоваться специализированные программные запросы к конечным точкам группы payment/status Gate API. Они позволяют оперативно получать информацию о конкретных платежах в то время, которое актуально со стороны веб-сервиса мерчанта, и могут глубоко интегрироваться в функциональность сервиса.

Для получения информации о состоянии отдельного платежа через Gate API могут использоваться два способа поиска:

  • По идентификатору платежа. Этот способ является основным и может использоваться в любое время. Содержание ответов при использовании этого способа в каждом случае зависит от того, был ли зарегистрирован искомый платёж в платформе.
    • Если платёж был зарегистрирован, в ответ на запрос о состоянии такого платежа включается актуальная информация о платеже.
    • Если платёж не был зарегистрирован (например, при вызове платёжной формы Payment Page и её закрытии пользователем до подтверждения платежа), в ответ на запрос о состоянии такого платежа включается информация о том, что такой платёж не был зарегистрирован.
  • Поиск по идентификатору запроса на проведение платежа. Этот способ является дополнительным и для корректного поиска информации должен использоваться не ранее чем через 10 секунд после отправки запроса на проведение искомого платежа. Использование этого способа может быть актуальным, например, когда запрос на проведение платежа не был принят из-за выявленных ошибок в формате или содержании запроса. В таких случаях в ответ на запрос о состоянии платежа включается информация о выявленных ошибках, не позволивших перейти к проведению платежа.
Notice: В общем случае поиск по идентификатору запроса не рекомендуется использовать вместо основного поиска по идентификатору платежа. Получать информацию о любом платеже после принятия запроса на его проведение предпочтительнее по идентификатору платежа.

Независимо от способа поиска, все запросы о состоянии платежа выполняются в рамках синхронной схемы взаимодействия между веб-сервисом и платёжной платформой. Это означает, что каждый такой запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа (200) и запрошенная информация без указания статуса запроса. В случаях, если запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса error и описание причины обнаруженной ошибки. Информация об HTTP-кодах ответов представлена в статье Организация взаимодействия, а о кодах ошибок, используемых в платёжной платформе — в статье Работа с информацией об операциях.

Получение информации по идентификатору платежа

Формат запроса

Формат запроса на получение информации о состоянии платежа по его идентификатору соответствует описанному в разделе Организация взаимодействия, конечной точкой API для этого запроса выступает /v2/payment/status, а в теле запроса должен содержаться объект general с основными идентификационными сведениями:

  • project_id — идентификатор проекта, полученный от Benker при интеграции;
  • payment_id — идентификатор платежа, информацию о состоянии которого необходимо получить;
  • signature — подпись запроса, составленная на основе вышеуказанных параметров (подробнее — в разделе Работа с подписью к данным).
Рис. 1. Пример тела запроса на получение информации о состоянии платежа
{
    "general":{
       "project_id":50,
       "payment_id":"ORDER_ID_302bis",
       "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}

Формат ответа

Формат ответа на запрос о состоянии платежа соответствует описанному в разделе Организация взаимодействия. В заголовке целевого ответа содержится стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к этому коду (200 OK). В теле такого ответа содержатся:

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

Базовый набор сведений, передаваемых в ответ на запрос о состоянии платежа, указан в спецификации Gate API.

Получение информации по идентификатору запроса

Формат запроса

Формат запроса на получение информации о состоянии платежа по идентификатору запроса на его проведение соответствует описанному в разделе Организация взаимодействия, конечной точкой API для этого запроса выступает /v2/payment/status/request, а в теле запроса должны содержаться следующие сведения:

  • project_id — идентификатор проекта, полученный от Benker при интеграции;
  • request_id — идентификатор запроса на проведение платежа, информацию о состоянии которого необходимо получить, полученный в ответе от платёжной платформы;
  • signature — подпись запроса, составленная на основе вышеуказанных параметров (подробнее — в разделе Работа с подписью к данным).
Рис. 2. Пример тела запроса на получение информации о состоянии платежа
{
   "project_id":50,
   "request_id":"2336565",
   "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
}

Формат ответа

Формат ответа на запрос о состоянии платежа соответствует описанному в разделе Организация взаимодействия. В заголовке ответа на успешно принятый запрос содержится стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к коду (200 OK), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа.

Дополнительные материалы

При работе с запросами на получение статуса платежа могут быть полезны следующие материалы: