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

Обзор

При работе с платёжной платформой ECommPay получать актуальную информацию о состоянии платежей можно разными способами: через интерфейс Dashboard (Old 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), а в теле такого ответа содержатся следующие обязательные данные: идентификатор проекта, подпись, информация о статусе платежа и обо всех инициированных в рамках этого платежа операциях. Также в теле такого ответа могут содержаться дополнительные данные, состав которых настраивается по согласованию со специалистами технической поддержки и варьируется в зависимости от платёжного метода.

Примеры ответов

Далее представлен пример данных о проведённой двухстадийной оплате. В этом примере указаны:

  • код ответа о том, что запрос был успешно принят (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":"4805153025061891",
    "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"
     }
    },
    { 
      "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",                //пояснение к коду
      "provider":{ 
        "id":615,
        "payment_id":"2015611",
        "auth_code":"7213535217",
        "endpoint_id":615,
        "date":"2019-12-12T15:46:51+0000"
      }
    }
  ],
  "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":""
      }
    }
  ],
  "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":""
      }
    }
  ],
  "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=="
}

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

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