Получение информации о состоянии платежа
Обзор
При работе с платёжной платформой ecommpay получать актуальную информацию о состоянии платежей можно разными способами (подробнее — в отдельном обзоре). Наряду с другими интерфейсами для этого могут использоваться специализированные программные запросы к конечным точкам группы payment/status
Gate API. Они позволяют оперативно получать информацию о конкретных платежах в то время, которое актуально со стороны веб-сервиса мерчанта, и могут глубоко интегрироваться в функциональность сервиса.
Для получения информации о состоянии отдельного платежа через Gate API могут использоваться два способа поиска:
- По идентификатору платежа. Этот способ является основным и может использоваться в любое время. Содержание ответов при использовании этого способа в каждом случае зависит от того, был ли зарегистрирован искомый платёж в платформе.
- Если платёж был зарегистрирован, в ответ на запрос о состоянии такого платежа включается актуальная информация о платеже.
- Если платёж не был зарегистрирован (например, при вызове платёжной формы Payment Page и её закрытии пользователем до подтверждения платежа), в ответ на запрос о состоянии такого платежа включается информация о том, что такой платёж не был зарегистрирован.
- Поиск по идентификатору запроса на проведение платежа. Этот способ является дополнительным и для корректного поиска информации должен использоваться не ранее чем через 10 секунд после отправки запроса на проведение искомого платежа. Использование этого способа может быть актуальным, например, когда запрос на проведение платежа не был принят из-за выявленных ошибок в формате или содержании запроса. В таких случаях в ответ на запрос о состоянии платежа включается информация о выявленных ошибках, не позволивших перейти к проведению платежа.
Независимо от способа поиска, все запросы о состоянии платежа выполняются в рамках синхронной схемы взаимодействия между веб-сервисом и платёжной платформой. Это означает, что каждый такой запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа (200) и запрошенная информация без указания статуса запроса. В случаях, если запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса error и описание причины обнаруженной ошибки. Информация об HTTP-кодах ответов представлена в статье Организация взаимодействия, а о кодах ошибок, используемых в платёжной платформе — в статье Работа с информацией об операциях.
Получение информации по идентификатору платежа
Формат запроса
Формат запроса на получение информации о состоянии платежа по его идентификатору соответствует описанному в разделе Организация взаимодействия, конечной точкой API для этого запроса выступает /v2/payment/status, а в теле запроса должен содержаться объект general с основными идентификационными сведениями:
project_id— идентификатор проекта, полученный от ecommpay при интеграции;payment_id— идентификатор платежа, информацию о состоянии которого необходимо получить;signature— подпись запроса, составленная на основе вышеуказанных параметров (подробнее — в разделе Работа с подписью к данным).
{
"general":{
"project_id":50,
"payment_id":"ORDER_ID_302bis",
"signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
}
}
Формат ответа
Формат ответа на запрос о состоянии платежа соответствует описанному в разделе Организация взаимодействия. В заголовке целевого ответа содержится стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к этому коду (200 OK). В теле такого ответа содержатся:
- идентификатор проекта и подпись;
- информация о статусе платежа и обо всех инициированных в рамках этого платежа операциях;
- дополнительная информация, состав которой может варьироваться в зависимости от используемого платёжного метода и может настраиваться для разных методов по согласованию со специалистами технической поддержки.
Базовый набор сведений, передаваемых в ответ на запрос о состоянии платежа, указан в спецификации Gate API.
Примеры ответов
Далее представлен пример данных о проведённой двухстадийной оплате. В этом примере указаны:
- код ответа о том, что запрос был успешно принят (
200); - статус платежа (
success); - код используемого платёжного метода (
card); - сведения об операциях
authиcaptureв массивеoperations.
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.
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).
HTTP/1.1 400 Bad Request //стартовая строка ответа ... //поля заголовка { "status":"error", //статус обработки запроса "code":"2004", //код, уточняющий статус "message":"Required field not provided" //пояснение к коду }
Для сравнения далее представлен пример ответа с информацией об отклонении платежа. В этом примере указаны:
- код ответа о том, что запрос был успешно принят (
200); - статус платежа (
decline); - сведения об операции
sale, которые включают код ошибки при выполнении операции (20502) и поясняющее описание к нему (Error during operation validation).
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).
HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "payment":{ "status":"error" //статус платежа }, "errors":[ { "code":"3061", //код, уточняющий статус "message":"Transaction not found" //пояснение к коду } ], "signature":"O08H+DLViSdn9ZoorYsbearslZsQ==" }
Получение информации по идентификатору запроса
Формат запроса
Формат запроса на получение информации о состоянии платежа по идентификатору запроса на его проведение соответствует описанному в разделе Организация взаимодействия, конечной точкой API для этого запроса выступает /v2/payment/status/request, а в теле запроса должны содержаться следующие сведения:
project_id— идентификатор проекта, полученный от ecommpay при интеграции;request_id— идентификатор запроса на проведение платежа, информацию о состоянии которого необходимо получить, полученный в ответе от платёжной платформы;signature— подпись запроса, составленная на основе вышеуказанных параметров (подробнее — в разделе Работа с подписью к данным).
{
"project_id":50,
"request_id":"2336565",
"signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
}
Формат ответа
Формат ответа на запрос о состоянии платежа соответствует описанному в разделе Организация взаимодействия. В заголовке ответа на успешно принятый запрос содержится стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к коду (200 OK), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа.