Получение информации о состоянии платежа
Обзор
При работе с платёжной платформой ecommpay получать актуальную информацию о состоянии платежей можно разными способами: через интерфейс Dashboard, а также на программном уровне — через оповещения, автоматически отправляемые в заданных случаях (подробнее — в разделе Оповещения), и ответы на запросы о состоянии платежа. Такие запросы можно отправлять при любой необходимости — например, для проверки статуса оплаты через платёжный терминал, когда проведение платежа может занимать не один день, — но не ранее, чем через 10 секунд после отправки запроса на проведение платежа.
Получать информацию о платеже на программном уровне можно следующими способами:
- По идентификатору платежа.Этот способ может быть актуален в случаях, когда запрос на проведение платежа был принят и платёж был зарегистрирован в платформе. В таких случаях ответы содержат основную информацию о платеже, а в случаях, когда запрос на проведение платежа ещё не принят (например при вызове платёжной формы Payment Page и её закрытии пользователем до подтверждения оплаты) — информацию о том, что такой платёж не был зарегистрирован в платформе.
- По идентификатору запроса на проведение платежа. Этот способ может быть актуален в случаях, когда запрос на проведение платежа не был принят из-за ошибок в запросе. В таких случаях ответы содержат информацию о выявленных ошибках. Получать информацию о платеже после принятия запроса на его проведение предпочтительнее по идентификатору платежа.
Запрос о состоянии платежа выполняется в рамках синхронной схемы взаимодействия между веб-сервисом и платёжной платформой. Это означает, что запрос полностью выполняется на стороне платёжной платформы в течение одного 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), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа.