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

Обзор

При работе с платёжной платформой 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), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа.

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

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

Организация взаимодействия — раздел с общей информацией о взаимодействии с платёжной платформой через Gate.
Модель проведения платежей — раздел с информацией о типах, схемах проведения и возможных статусах поддерживаемых платежей.
Работа с подписью к данным — раздел с информацией о создании и проверке подписи в запросах и оповещениях при взаимодействии с платёжной платформой.
Информация об операциях — раздел со списком кодов ошибок и ответов, используемых в платёжной платформе для уточнения информации об операциях.