# Получение информации о состоянии платежа {#ru_Gate_payment_status_request .concept} статья о возможности получать через Gate актуальную информацию о конкретных платежах, независимо от того, через какие интерфейсы они были инициированы **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Обзор {#ru_gate_payment_status_request_overview} При работе с платёжной платформой Ecommpay получать актуальную информацию о состоянии платежей можно разными способами \(подробнее — в отдельном [обзоре](ru_platform_payment_information_overview.md)\). Наряду с другими интерфейсами для этого могут использоваться специализированные программные запросы к конечным точкам группы `payment/status` Gate API. Они позволяют оперативно получать информацию о конкретных платежах в то время, которое актуально со стороны веб-сервиса мерчанта, и могут глубоко интегрироваться в функциональность сервиса. Для получения информации о состоянии отдельного платежа через Gate API могут использоваться два способа поиска: - *По идентификатору платежа*. Этот способ является основным и может использоваться в любое время. Содержание ответов при использовании этого способа в каждом случае зависит от того, был ли зарегистрирован искомый платёж в платформе. - Если платёж был зарегистрирован, в ответ на запрос о состоянии такого платежа включается актуальная информация о платеже. - Если платёж не был зарегистрирован \(например, при вызове платёжной формы Payment Page и её закрытии пользователем до подтверждения платежа\), в ответ на запрос о состоянии такого платежа включается информация о том, что такой платёж не был зарегистрирован. - *Поиск по идентификатору запроса на проведение платежа*. Этот способ является дополнительным и для корректного поиска информации должен использоваться не ранее чем через 2 секунды после отправки запроса на проведение искомого платежа. Использование этого способа может быть актуальным, например, когда запрос на проведение платежа не был принят из-за выявленных ошибок в формате или содержании запроса. В таких случаях в ответ на запрос о состоянии платежа включается информация о выявленных ошибках, не позволивших перейти к проведению платежа. **Прим.:** В общем случае поиск по идентификатору запроса не рекомендуется использовать вместо основного поиска по идентификатору платежа. Получать информацию о любом платеже после принятия запроса на его проведение предпочтительнее по идентификатору платежа. Независимо от способа поиска, все запросы о состоянии платежа выполняются в рамках синхронной схемы взаимодействия между веб-сервисом и платёжной платформой. Это означает, что каждый такой запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа \(`200`\) и запрошенная информация без указания статуса запроса. В случаях, если запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса `error` и описание причины обнаруженной ошибки. Информация об HTTP-кодах ответов представлена в статье [Организация взаимодействия](ru_gate_interaction_organisation.md#), а о кодах ошибок, используемых в платёжной платформе — в статье [Работа с информацией об операциях](ru_platform_payment_info_codes.md). ## Получение информации по идентификатору платежа {#ru_gate_payment_status_request_by_payment_id} ### Формат запроса {#section_xxz_2nm_rkb .section} Формат запроса на получение информации о состоянии платежа по его идентификатору соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md#), конечной точкой API для этого запроса выступает [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status), а в теле запроса должен содержаться объект `general` с основными идентификационными сведениями: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, информацию о состоянии которого необходимо получить; - `signature` — подпись запроса, составленная на основе вышеуказанных параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\). ```language-json { "general":{ "project_id":50, "payment_id":"ORDER_ID_302bis", "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" } } ``` ### Формат ответа {#section_ayz_2nm_rkb .section} Формат ответа на запрос о состоянии платежа соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md#). В заголовке целевого ответа содержится стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к этому коду \(`200 OK`\). В теле такого ответа содержатся: - идентификатор проекта и подпись; - информация о статусе платежа и обо всех инициированных в рамках этого платежа операциях; - дополнительная информация, состав которой может варьироваться в зависимости от используемого платёжного метода и может настраиваться для разных методов по согласованию со специалистами технической поддержки. Базовый набор сведений, передаваемых в ответ на запрос о состоянии платежа, указан [в спецификации Gate API](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status). ### Примеры ответов {#section_htw_t1q_jlb .section} Далее представлен пример данных о проведённой двухстадийной оплате. В этом примере указаны: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`success`\); - код используемого платёжного метода \(`card`\); - сведения об операциях `auth` и `capture` в массиве `operations`. ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":50, "payment":{ "id":"ORDER_ID_302bis", "type":"purchase", //тип платежа "status":"success", //статус платежа "date":"2019-12-12T15:46:51+0000", "method":"card", //код платёжного метода "sum_real":{ "amount":33, "currency":"USD" }, "description":"Booking" }, "customer":{ "id":"6361696170" }, "account":{ "number":"4314220000000056", "type":"visa", "card_holder":"Michael Nurenberg", "expiry_month":"03", "expiry_year":"2024" }, "operations":[ { "id":9435219675496, "type":"auth", //тип операции "status":"success", //статус операции "date":"2019-12-11T15:46:37+0000", "created_date":"2019-12-11T15:46:35+0000", "request_id":"bcRFZRJkmfcf-178c3d843c99-00009436", "sum":{ "amount":33, "currency":"USD" }, "code":"0", //код, уточняющий статус операции auth "message":"Success", //пояснение к коду "eci":"07", "provider":{ "id":615, "payment_id":"2015611", "auth_code":"7213535217", "endpoint_id":615, "date":"2019-12-11T15:46:36+0000" }, "operation_fee":{ //объект с информацией о комиссии "amount":31, "currency":"USD" } }, { "id":9435219671141, "type":"capture", //тип операции "status":"success", //статус операции "date":"2019-12-12T15:46:51+0000", "created_date":"2019-12-12T15:46:48+0000", "request_id":"2f114083cfb0f6d12c2-2ac890ebadb793-05015382", "code":"0", //код, уточняющий статус операции capture "message":"Success" //пояснение к коду } ], "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg==" } ``` В представленном далее примере данных о незавершённой одностадийной оплате содержится следующая информация: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`awaiting redirect result`\); - код используемого платёжного метода \(Malaysian Banks\); - сведения об операции `sale` в массиве `operations`. ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":72, "payment":{ "id":"ORDER_ID_tetan_M_2007_2012", "type":"purchase", //тип платежа "status":"awaiting redirect result", //статус платежа "date":"2019-12-11T15:59:10+0000", "method":"`Malaysian Banks`", //код платёжного метода "sum":{ "amount":25000, "currency":"MYR" }, "description":"Book premium" }, "customer":{ "id":"Scott", "phone":"44177118324" }, "operations":[ { "id":65747461, "type":"sale", //тип операции "status":"awaiting redirect result", //статус операции "date":"2019-12-11T15:59:10+0000", "created_date":"2019-12-11T15:59:06+0000", "request_id":"97c7dd03080b4293603f28e64-0c415bc3e876c911f2d87-00006979", "sum_initial":{ "amount":25000, "currency":"MYR" }, "sum_converted":{ "amount":25000, "currency":"MYR" }, "code":"9999", //код, уточняющий статус операции sale "message":"Awaiting processing", //пояснение к коду "provider":{ "id":2012, "payment_id":"", "auth_code":"" }, "operation_fee":{ //объект с информацией о комиссии "amount":25, "currency":"MYR" } } ], "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA==" } ``` Далее представлен пример ответа на некорректно составленный запрос. Если в запросе обнаружена ошибка, то в ответе указывается следующее: - код ответа с описанием причины ошибки в стартовой строке \(`400 Bad Request`\); - статус обработки запроса \(`error`\); - уточняющая информация об ошибке: код ошибки \(`2004`\) и поясняющее описание к нему \(`Required field not provided`\). ```language-json HTTP/1.1 400 Bad Request //стартовая строка ответа ... //поля заголовка { "status":"error", //статус обработки запроса "code":"2004", //код, уточняющий статус "message":"Required field not provided" //пояснение к коду } ``` Для сравнения далее представлен пример ответа с информацией об отклонении платежа. В этом примере указаны: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`decline`\); - сведения об операции `sale`, которые включают код ошибки при выполнении операции \(`20502`\) и поясняющее описание к нему \(`Error during operation validation`\). ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":912103, "payment":{ "id":"ORDER_ID_2018nbl", "type":"purchase", //тип платежа "status":"decline", //статус платежа "date":"2018-05-04T12:55:51+0000", "method":"mobile", //код платёжного метода "sum":{ "amount":849, "currency":"EUR" }, "description":"Flights" }, "account":{ "number":"20072017", "type":"mTELE2" }, "customer":{ "id":"otokarczuk@gmail.com" }, "operations":[ { "id":2018416116, "type":"sale", //тип операции "status":"decline", //статус операции "date":"2020-05-04T12:55:51+0000", "created_date":"2020-05-04T12:55:10+0000", "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008", "sum_initial":{ "amount":849, "currency":"EUR" }, "sum_converted":{ "amount":849, "currency":"EUR" }, "code":"20502", //код, уточняюший статус операции sale "message":"Error during operation validation", //пояснение к нему "provider":{ "id":5232, "payment_id":"1024514", "auth_code":"" }, "operation_fee":{ //объект с информацией о комиссии "amount":0, "currency":"" } } ], "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow==" } ``` Далее представлен пример ответа на запрос о состоянии такого платежа, запрос на инициирование которого не был принят в платёжной платформе \(например, когда пользователь закрыл платёжную форму до подтверждения оплаты\). В этом случае в ответе содержатся: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`error`\); - уточняющая информация об ошибке: код ошибки \(`3061`\) и описание к нему \(`Transaction not found`\). ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "payment":{ "status":"error" //статус платежа }, "errors":[ { "code":"3061", //код, уточняющий статус "message":"Transaction not found" //пояснение к коду } ], "signature":"O08H+DLViSdn9ZoorYsbearslZsQ==" } ``` ## Получение информации по идентификатору запроса {#ru_gate_payment_status_request_by_request_id} ### Формат запроса {#section_jjf_htc_vtb .section} Формат запроса на получение информации о состоянии платежа по идентификатору запроса на его проведение соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md#), конечной точкой API для этого запроса выступает [/v2/payment/status/request](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status-request), а в теле запроса должны содержаться следующие сведения: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `request_id` — идентификатор запроса на проведение платежа, информацию о состоянии которого необходимо получить, полученный в ответе от платёжной платформы; - `signature` — подпись запроса, составленная на основе вышеуказанных параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\). ```language-json { "project_id":50, "request_id":"2336565", "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" } ``` ### Формат ответа {#section_j2w_htc_vtb .section} Формат ответа на запрос о состоянии платежа соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md#). В заголовке ответа на успешно принятый запрос содержится стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к коду \(`200 OK`\), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа. ## Дополнительные материалы {#ru_gate_payment_status_request_related_links} При работе с запросами на получение статуса платежа могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#) — раздел с общей информацией о взаимодействии с платёжной платформой через Gate. - [Модель проведения платежей](ru_platform_payment_model.md) — раздел с информацией о типах, схемах проведения и возможных статусах поддерживаемых платежей. - [Работа с подписью к данным](ru_platform_signature.md#) — раздел с информацией о создании и проверке подписи в запросах и оповещениях при взаимодействии с платёжной платформой. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md) — раздел со списком кодов ошибок и ответов, используемых в платёжной платформе для уточнения информации об операциях.