Как узнать статус платежа

Обзор

В процессе обработки платежа информация о статусе платежа передается в оповещениях, поступающих из платежной платформы, но иногда требуется отдельно уточнить текущий статус того или иного платежа. Проще всего воспользоваться пользовательским интерфейсом своего личного кабинета на сайте Dashboard, но статус также можно запросить программными средствами через Gate API. Здесь рассказывается, как отправить запрос информации о статусе платежа, обработать полученный ответ и извлечь из него статус платежа, а также приведены примеры ответов платежной платформы для разных платежей.

Запрос о состоянии платежа выполняется синхронно, то есть он полностью выполняется в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа 200 и информация о состоянии платежа.

Если запрос некорректен или с его приемом и обработкой возникли неполадки, в ответе на запрос содержатся:

  • HTTP-код ответа отличный от 200;
  • статус обработки запроса error;
  • описание причины обнаруженной ошибки.

Подробнее об HTTP-кодах ответов см. Общий порядок интеграции, а о кодах ошибок, используемых в платежной платформе, см. раздел Статусы операций и коды ответов.

Запрос о состоянии платежа следует отправлять не ранее, чем через 10 секунд после отправки запроса на проведение платежа. Это время платежной платформе нужно на обработку запроса на проведение платежа и создания на его основе нового платежа. Если запрос о состоянии платежа отправить раньше, платежная платформа вернет ошибку и сообщит о том, что такой платеж не зарегистрирован в платформе.

Запрос

Для запроса информации о состоянии платежа используется стандартный формат, подробно описанный в разделе Общий порядок интеграции. Далее представлена информация, необходимая для создания и отправки запроса информации о состоянии платежа.

HTTP-метод запроса POST
Формат тела запроса JSON
Конечная точка /v2/payment/status
Табл. 1. Базовые параметры запроса статуса платежа
Объект Параметр Описание

general
object
required

project_id
integer
required

 Идентификатор проекта, полученный от Rocketpay при интеграции

payment_id
string
required

 Идентификатор платежа, информацию о состоянии которого необходимо получить

signature
string
required

 Подпись запроса, составленная после определения всех параметров запроса. (Подробнее см. раздел Подписывание и проверка подписи.)

Вот пример запроса статуса платежа.

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

{
    "general":{
       "project_id":50,
       "payment_id":"ORDER_ID_302",
       "signature":"qflDO7yiPKCFTyqCAaT+...yf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}

Синхронный ответ

В ответе на запрос о состоянии платежа используется стандартный формат, описанный в разделе Общий порядок интеграции.

В заголовке ответа на успешно принятый запрос содержится стартовая строка с указанием протокола и его версии, например HTTP/1.1, код ответа и поясняющая фраза к коду, например 200 OK, а в теле такого ответа содержатся следующие обязательные данные:

  • идентификатор проекта;
  • информация о статусе платежа и обо всех инициированных в рамках этого платежа операциях;
  • подпись.

Также в теле ответа могут содержаться дополнительные данные, состав которых настраивается по согласованию со специалистами технической поддержки и варьируется в зависимости от платежного метода. Далее приведены примеры ответов на платежи, находящиеся на разных этапах обработки, а также примеры ответов о невозможности обработать запрос и ответ с информацией об отсутствии запрошенного платежа в платежной платформе.

Пример 1: Ответ о статусе успешной двухстадийной оплаты

Пример ответа содержит в числе прочего:

  • 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 Elton",
    "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=="
}

Пример 2: Ответ для платежа в промежуточном статусе

Пример ответа для незавершенной одностадийной оплаты содержит в числе прочего:

  • 200 — код ответа, свидетельствующий о том, что запрос успешно принят;
  • awaiting redirect result — статус платежа, говорящий о том, что платеж находится в ожидании возврата пользователя после перенаправления в систему внешнего провайдера;
  • mobile — код используемого платежного метода;
  • 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":"mobile",                   // Код платежного метода
    "sum":{ 
      "amount":25000,
      "currency":"KZT"
    },
    "description":"Book premium"
  },
  "customer":{ 
    "id":"Scott",
    "phone":"77761234567"
  },
  "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":"KZT"
      },
      "sum_converted":{ 
        "amount":25000,
        "currency":"KZT"
      },
      "code":"9999",                       // Код, уточняющий статус операции sale
      "message":"Awaiting processing",     // Пояснение к коду
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

Пример 3: Ответ об отсутствии платежа в платежной платформе

Далее представлен пример ответа на запрос о состоянии такого платежа, запрос на инициирование которого не был принят в платежной платформе (например, когда пользователь закрыл платежную форму до подтверждения оплаты). В этом случае в ответе помимо прочего содержатся:

  • 200 — код ответа, свидетельствующий о том, что запрос успешно принят;
  • error — статус платежа, говорящий об ошибке получения информации о платеже;
  • 3061 (Transaction not found) — код ошибки и ее описание, говорящее, что такого платежа в платежной платформе не существует.

Рис.: Пример ответа об отсутствии запрошенного платежа в платежной платформе

HTTP/1.1 200 OK                                  // Стартовая строка ответа
...                                              // Поля заголовка
{
  "payment":{
    "status":"error"                             // Статус платежа
  },
  "errors":[
    {
      "code":"3061",                             // Код, уточняющий статус   
      "message":"Transaction not found"          // Пояснение к коду - платеж не найден
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

Пример 4: Ответ о временных неполадках в обработке платежа

Внимание: В случае такой ошибки статус платежа не является итоговым. Рекомендуется повторить отправку запроса о состоянии данного платежа позже. До получения более подробной информации платеж считать проведенным нельзя.

Далее представлен пример ответа на запрос о состоянии платежа, запрос на инициирование которого был принят в платежной платформе, но каким-либо причинам информация о котором в данное время недоступна в платежной платформе (например, в случае сетевых сбоев). В этом случае в ответе содержатся:

  • 200 — код ответа, свидетельствующий о том, что запрос успешно принят;
  • error — статус платежа, говорящий о том, что сведения о запрошенном платеже отсутствуют;
  • код ошибки — одно из следующих значений:
    • 3061 (Transaction not found) — код ошибки и ее описание, говорящие об отсутствии информации о платеже в платежной платформе.
    • 3062 (Payment details not received) — код ошибки и ее описание, говорящие о временном отсутствии информации о платеже в платежной платформе.

Рис.: Пример ответа о сбоях с получением информации

HTTP/1.1 200 OK                                 // Стартовая строка ответа
...                                             // Поля заголовка
{
  "payment":{
    "status":"error"                            // Статус платежа
  },
  "errors":[
    {
      "code":"3062",                             // Код, уточняющий статус   
      "message":"Payment details not received"   // Пояснение к коду
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

Пример 5: Ответ о ошибке в запросе статуса платежа

Далее представлен пример ответа на некорректно составленный запрос, в котором отсутствует необходимый параметр. Ответ содержит следующее:

  • 400 Bad Request — код ответа с описанием причины ошибки в стартовой строке;
  • error — статус обработки запроса о состоянии платежа. Не путать со статусом исходного запроса о проведении платежа!
  • 2004 и Required field not provided — код ошибки и его описание, поясняющее, что в запросе отсутствует необходимое поле.

Рис.: Пример ответа об ошибке в запросе

HTTP/1.1 400 Bad Request                         // Стартовая строка ответа
...                                              // Поля заголовка
{
   "status":"error",                             // Статус обработки запроса
   "code":"2004",                                // Код, уточняющий статус
   "message":"Required field not provided"       // Пояснение к коду
}

Пример 6: Ответ с информацией об отклонении оплаты

Здесь представлен пример ответа с информацией об отклонении платежа. Помимо прочего ответ содержит следующую информацию:

  • 200 — код ответа, свидетельствующий о том, что запрос успешно принят;
  • decline — статус платежа, говорящий об отклонении платежа, в данном случае это оплата;
  • 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":"johndoe@example.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=="
}

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

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