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

При работе с платёжной платформой Ecommpay получать информацию о состоянии платежей можно разными способами (подробнее — в отдельном обзоре). Наряду с другими интерфейсами для этого могут использоваться специализированные программные, в том числе через запросы к конечной точке /v2/payment/status Gate API. Они позволяют оперативно получать информацию о конкретных платежах тогда, когда это актуально со стороны веб-сервиса мерчанта, и могут глубоко интегрироваться в функциональность сервиса.

Схема взаимодействия

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

Вместе с тем для корректной обработки запросов о состоянии платежей любой такой запрос должен отправляться со стороны веб-сервиса не ранее чем через две секунды после отправки последнего запроса на действия по искомому платежу. Поэтому после инициирования платежа или операции любого типа (будь то оплата, отмена блокировки, возврат, выплата или что-то ещё) необходимо выдерживать по крайней мере двухсекундный интервал перед проверкой состояния такого платежа. Иначе возможны ошибки с обработкой запросов и предоставлением информации.

Категории информации

В ответы на корректно составленные и обработанные запросы о состоянии платежей могут включаться сведения двух категорий:

• Сведения о платеже — в случаях, когда искомый платёж был зарегистрирован в платформе (и по нему есть информация).

  Эта категория сведений является основной. Она включается в ответы всегда, когда применима.

• Сведения о некорректном запросе на действия по платежу — в случаях, когда последний полученный в платформе запрос на действия по искомому платежу не был принят к выполнению, например из-за отсутствия или некорректного указания в нём необходимых параметров (подробнее далее).

  Эта категория сведений является дополнительной и рекомендуемой к применению. Её включение в ответы настраивается на уровне проектов по согласованию со специалистами технической поддержки Ecommpay.

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

Обработка информации о запросах на действия по платежам

Ответ о состоянии любого платежа подразумевает возможность включения в него сведений только о последнем запросе на действия. Это означает, что если по платежу в платформу последовательно приходят запросы на какие-либо действия, то независимо от корректности предыдущих запросов в качестве актуальных ошибок по запросам рассматриваются лишь ошибки последнего полученного запроса (в то время как ошибки по предыдущим запросам остаются вне контекста и игнорируются).

Такой подход можно рассмотреть на примерах:

1. Если в платформу поступил некорректный запрос на блокировку средств в рамках двухстадийной оплаты (подробнее), то в ответ о состоянии такого платежа включаются сведения о зафиксированных ошибках.
2. Если в дальнейшем в платформе была инициирована и выполнена целевая блокировка средств, а затем по этому платежу было некорректно инициировано списание заблокированных средств, то в ответ о состоянии такого платежа включаются сведения о платеже и сведения о некорректном запросе по этому платежу, с информацией об ошибках в запросе на списание.
3. Если далее по этому же платежу в платформу приходит корректный запрос на частичный возврат, то сведения о некорректном запросе по этому платежу не заполняются (поскольку последний запрос корректен). Чтобы понять, что в таком случае возврат не может быть выполнен из-за того, что не было выполнено списание, следует анализировать сведения о платеже.
4. Если далее по этому же платежу в платформу приходит некорректный запрос на второй частичный возврат, то в сведения о некорректном запросе по этому платежу включается информация об ошибках в последнем запросе на частичный возврат. Чтобы понять, что в таком случае даже корректный запрос на возврат не может быть выполнен из-за того, что не было выполнено списание, следует анализировать сведения о платеже; чтобы понять, почему некорректен последний запрос на возврат — сведения о некорректном запросе.

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

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

Схематично такой подход можно представить следующим образом.

Варианты ответов

С учётом того, был ли зарегистрирован искомый платёж и является ли последний запрос по нему корректным, возможны четыре ситуации и четыре варианта наполнения ответов о состоянии платежа.

• Есть платёж, нет запроса с ошибками.

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

  Со стороны веб-сервиса в таком случае следует проанализировать статусы платежа и операций по нему и действовать в штатном режиме, исходя из этих статусов.

• Есть платёж, есть запрос с ошибками.

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

  Со стороны веб-сервиса в таком случае следует проанализировать информацию об ошибках по запросу на целевое действие и, если актуально, повторно инициировать это действие, отправив скорректированный запрос.

• Нет платежа, нет запроса с ошибками.

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

  Со стороны веб-сервиса в таком случае следует проверить корректность исходного запроса на получение информации о состоянии платежа, при необходимости скорректировать его и использовать повторные попытки получить информацию с интервалами не менее двух секунд, а при их безуспешности попробовать инициировать целевой платёж повторно (с тем же идентификатором) или обратиться к специалистам технической поддержки Ecommpay. Более подробно рекомендуемые в таких ситуациях действия описаны отдельно.

• Нет платежа, есть запрос с ошибками.

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

  Со стороны веб-сервиса в таком случае следует проанализировать информацию об ошибках по запросу на проведение платежа и, если актуально, повторно инициировать этот платёж, отправив скорректированный запрос с указанием того же идентификатора платежа в параметре payment_id, что и в исходном запросе.

В случаях с ошибками в запросах о состоянии платежей или ошибками при их выполнении в ответах указываются соответствующие HTTP-коды (например, 400) и сведения о выявленных ошибках. Со стороны веб-сервиса в таких случаях следует анализировать информацию об ошибках и, если актуально, повторно запрашивать информацию о состоянии целевых платежей, отправляя корректные запросы.

Примеры ответов на запросы для всех перечисленных ситуаций с использованием сведений о некорректных запросах представлены далее.

Также при интерпретировании ответов о состоянии платежей стоит учитывать следующее:

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

Для получения информации о состоянии какого-либо платежа через Gate 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 для ответа с информацией о платеже или 400 Bad Request для ответа о некорректности запроса о состоянии платежа), а также последующие строки с технической информацией согласно используемому протоколу.

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

Примеры ответов для различных ситуаций представлены далее, в отдельном разделе этой статьи.

Состав сведений о состоянии платежа

В случаях, когда запрос о состоянии платежа был корректно отправлен со стороны веб-сервиса и корректно обработан на стороне платформы, в тело ответа включаются:

• Идентификатор проекта и подпись к ответу — в параметрах project_id и signature соответственно.
• Статус платежа — в параметре status.
• Информация о последнем запросе на действия по платежу — в объекте last_failed_request — при выполнении двух условий:
  • для используемого проекта настроено включение такой информации в ответы о состоянии платежей;
  • последний запрос по платежу был получен, но не был принят к выполнению в платформе из-за зафиксированных ошибок.
• Информация об операциях по платежу — о последней инициированной в объекте operation или обо всех инициированных в массиве operations (с учётом специфики проекта и платежа).

  Важно учитывать, что объект operation и массив operations можно интерпретировать как равные по значимости и в ответах на запросы о состоянии одного и того же платежа информация может передаваться сначала одним, а затем другим способом. Поэтому на стороне веб-сервиса должна быть обеспечена корректная обработка обоих вариантов представления информации.

• Дополнительная информация о платеже — в объектах и параметрах, состав которых может варьироваться в зависимости от типа и статуса платежа, платёжного метода и других разных факторов и может настраиваться по согласованию со специалистами технической поддержки.

Состав сведений об ошибках с обработкой запросов

В случаях, когда при обработке запроса о состоянии платежа этот запрос признаётся некорректным или с его обработкой возникают проблемы, в тело ответа могут включаться сведения двух видов:

• Базовые сведения об ошибке (которые могут использоваться для всех ответов, включая ответы с кодами 400, 403, 422 и 500) — в виде набора параметров, в который могут входить:
  • status — статус обработки запроса о состоянии платежа error;
  • code — код возникшей ошибки (в виде строки с типом данных string);
  • message — поясняющая фраза к указанному коду.
  Прим.: При разборе ошибок можно учитывать, что в тех случаях, когда возникают проблемы с обработкой запроса о состоянии платежа, параметр status не включается в объект payment и относится не к платежу, а только к запросу о его состоянии.
• Расширенные сведения об ошибках с заполнением данных (которые могут использоваться для ответов с кодом 400) — в виде массива errors, в котором для каждой ошибки с заполнением данных могут указываться следующие параметры:
  • code — код возникшей ошибки (в виде числа с типом данных integer);
  • message — поясняющая фраза к указанному коду;
  • field — полное название параметра, в заполнении которого допущена ошибка;
  • constraint — краткое описание ограничения или требования, которое не было соблюдено при заполнении указанного параметра.

О зарегистрированных платежах без некорректных запросов

Для зарегистрированных платежей без некорректных запросов в каждый ответ о состоянии платежа включаются сведения о платеже и не включаются сведения об ошибках в последнем полученном запросе по платежу (даже если для проекта настроено их использование).

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",                       // код состояния операции
      "message":"Awaiting processing",     // пояснение к коду
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      },
      "operation_fee":{
        "amount":25,
        "currency":"MYR"
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

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

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• проведение искомого платежа было приостановлено до получения необходимой информации по итогам перенаправления пользователя (для платежа purchase указан статус awaiting redirect result);
• по инициированному в рамках этого платежа списанию средств в платформе ожидается информация по итогам перенаправления пользователя (для операции sale в массиве operations указан статус awaiting redirect result).

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

HTTP/1.1 200 OK                                     // стартовая строка ответа
...                                                 // поля заголовка
{
  "project_id":912103,
  "payment":{
    "id":"ORDER_ID_2018nbl",
    "type":"purchase",                              // тип платежа
    "status":"decline",                             // статус платежа
    "date":"2026-05-04T12:55:51+0000",
    "method":"card",
    "sum":{
      "amount":849,
      "currency":"EUR"
    },
    "description":"Flights"
  },
  "customer":{
    "id":"john_doe@example.com"
  },
  "operations":[
    {
      "id":2018416116,
      "type":"sale",                           // тип операции
      "status":"decline",                      // статус операции
      "date":"2026-05-04T12:55:51+0000",
      "created_date":"2026-05-04T12:55:10+0000",
      "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008",
      "sum_initial":{
        "amount":849,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":849,
        "currency":"EUR"
      },
      "code":"10114",                         // код состояния операции
      "message":"Declined by 3DS Check",      // пояснение к коду
      "provider":{
        "id":5232,
        "payment_id":"1024514",
        "auth_code":""
      },
      "operation_fee":{
        "amount":0,
        "currency":""
      }
    }
  ],
  "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow=="
}

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

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• искомый платёж был отклонён (для платежа purchase указан статус decline);
• инициированное в рамках этого платежа списание средств было отклонено в связи с неудовлетворительными результатами аутентификации пользователя (для операции sale в массиве operations указан статус decline с кодом состояния 10114 и описанием Declined by 3DS Check).

Чтобы провести искомый платёж, в таком случае следует уведомить пользователя о причине отклонения предыдущей попытки оплаты (по результатам аутентификации) и, если пользователь готов к новой попытке оплаты, инициировать новый платёж (с новым идентификатором), предпочтительно с возможностью выбора пользователем других платёжных методов и инструментов.

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",                           // код состояния операции
      "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",                         // код состояния операции
      "message":"Success"                 // пояснение к коду
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}

В этом примере ответ свидетельствует о том, что запрос о состоянии платежа был принят, искомый платёж был проведён, и в рамках этого платежа были выполнены блокировка и списание средств.

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• искомый платёж был проведён (для платежа purchase указан статус success);
• инициированные в рамках этого платежа блокировка и списание средств были выполнены (для операций auth и capture в массиве operations указаны статусы success).

В такой ситуации можно зафиксировать, что искомый платёж был проведён, и закончить работу по нему на стороне веб-сервиса.

О зарегистрированных платежах с некорректными запросами

Для зарегистрированных платежей с некорректными запросами в каждый ответ о состоянии платежа включаются сведения о платеже и (если это настроено для проекта) об ошибках в последнем полученном запросе по платежу.

HTTP/1.1 200 OK                                  // стартовая строка ответа
...                                              // поля заголовка
{
     "last_failed_request":{    // сведения о последнем запросе на действия по платежу
	  "id":"75227d07287cc87fa87901ddc9fc11225...",      // идентификатор запроса
	  "type":"refund",                                  // тип инициируемой операции
      "errors": [                            // сведения об ошибках в запросе
	  {
      "code": "3283",                                      // код ошибки
      "message": "Refund amount more than initial amount"  // пояснение к коду
	  }
    ]
    },
    "operation":{                            // сведения о ранее выполненной операции
        "sum_initial": {
            "amount": 100,
            "currency": "GBP"
        },
        "sum_converted": {
            "amount": 100,
            "currency": "GBP"
        },
        "eci": "02",
        "provider": {
            "id": 6,
            "payment_id": "17770306686380",
            "auth_code": "563253",
            "endpoint_id": 6,
            "date": "2026-05-27T14:19:19+0000"
        },
        "id": "74000014368",
        "type": "sale",                      // тип операции
        "status": "success",                 // статус операции
        "date": "2026-05-27T14:19:19+0000",
        "created_date": "2026-05-27T14:19:19+0000",
        "request_id": "64cfe0272c-e220ed1b035f60da..."  // идентификатор запроса
    },
    "customer": {
        "id": "1"
    },
    "account": {
        "number": "400000******0077"
    },
    "project_id": 432037,
    "payment": {
        "id": "27052026_1",
        "type": "purchase",                  // тип платежа
        "status": "success",                 // статус платежа
        "description": "description",
        "date": "2026-05-27T14:19:19+0000",
        "method": "card",
        "sum": {  
           "amount": 100,                     // сумма платежа
           "currency": "GBP"
        }
    },
   "signature":"yb9JpzzbyEbsdfsdfs+c+0nX7PQwO8TPosdfsdfsPlanEYqj1SAg=="
}

В этом примере ответ свидетельствует о том, что запрос о состоянии платежа был принят, искомый платёж проведён и в рамках этого платежа было выполнено списание средств, но запрос на возврат в рамках этого платежа не был принят к выполнению в связи с некорректным указанием суммы.

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• искомый платёж был проведён (для платежа purchase указан статус success);
• инициированное в рамках этого платежа списание средств было выполнено (для операции sale в объекте operation указан статус success);
• запрос на возврат в рамках этого платежа не был принят к выполнению в связи с некорректным указанием суммы (в объекте last_failed_request указан массив errors с информацией об ошибке с кодом 3283 и описанием Refund amount more than initial amount).

Для исправления ошибки в этом случае следует отправить повторный запрос на возврат с указанием корректной суммы (не превышающей актуальную сумму платежа, в данном случае 100 GBP).

О незарегистрированных платежах без некорректных запросов

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

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

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

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• информация об искомом платеже не была найдена в платформе (для платежа payment указан статус error и массив errors с информацией об ошибке с кодом 3061 и описанием Transaction not found).

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

О незарегистрированных платежах с некорректными запросами

Для незарегистрированных платежей с некорректными запросами в каждый ответ о состоянии платежа включаются краткий набор сведений о платеже и (если это настроено для проекта) сведения об ошибках в последнем полученном запросе по платежу.

HTTP/1.1 200 OK                                  // стартовая строка ответа
...                                              // поля заголовка
{
  "project_id": 432037,
  "payment": {
    "id": "27052026_1",
    "status": "error",                           // статус платежа
    "sum": { 
      "amount": 100, 
      "currency": "USD" 
    }
  },
  "errors": [                                    // сведения об ошибках в запросе
    {
      "field": "booking_info.start_date",
      "code": "3201",                                          // код ошибки
      "message": "booking_info.start_date cannot be empty"     // пояснение к коду
    }
  ],
  "operation": {                                 // сведения об операции
    "code": "702",                               // код состояния
    "message": "Malformed request",              // пояснение к коду
    "type": "sale",                              // тип операции
    "status": "decline",                         // статус операции
    "request_id": "64cfe0b0acfc1b6272c-e220ed127d4..."         // идентификатор запроса
  },
  "signature": "Wkq6GqjEs4w59CxXoR16gLrfrtSnjc7evr..."
}

В этом примере ответ свидетельствует о том, что запрос о состоянии платежа был принят, однако искомый платёж не был зарегистрирован в платформе из-за ошибки с заполнением полей.

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа был принят (код ответа — 200);
• искомый платёж не был зарегистрирован в платформе (для платежа payment указан статус error);
• в запросе на проведение платежа была допущена одна ошибка с заполнением полей (в массиве errors указан один объект с полным названием параметра booking_info.start_date, кодом ошибки 3201 и описанием booking_info.start_date cannot be empty).

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

Об ошибках с запросами о состоянии платежа

В случаях с ошибками в запросах о состоянии платежей или ошибками при их выполнении в каждый ответ включаются соответствующие HTTP-коды и сведения о выявленных ошибках.

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

В этом примере ответ свидетельствует о том, что запрос о состоянии платежа не был принят, поскольку в запросе не были указаны обязательные параметры.

В этом примере ответ свидетельствует о том, что:

• запрос о состоянии платежа не был принят (код ответа — 400);
• в запросе не были указаны обязательные параметры (для запроса указан статус error с кодом ошибки 2004 и описанием Required field not provided).

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

Общая организация контроля

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

1. Настроить работу с синхронными ответами и, если это актуально, с оповещениями от платформы (подробнее — в статьях об организации взаимодействия и о работе с оповещениями).

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

2. Настроить работу со служебными кодами и описаниями состояния операций (подробнее).

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

3. Настроить включение в ответы о состоянии платежей информации о некорректных запросах (через обращение к специалистам технической поддержки Ecommpay).

   Это позволяет получать в ответах о состоянии платежей более развёрнутые сведения и оперативно идентифицировать и исправлять ошибки, из-за которых запросы на действия по платежам не принимаются к выполнению в платформе.

4. Настроить правила отправки запросов о состоянии платежей — таким образом, чтобы обеспечить своевременное получение необходимой информации о платежах согласно специфике работы веб-сервиса.

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

5. Настроить корректное реагирование на информацию, получаемую в ответах о состоянии платежей.
   1. При отсутствии информации об ошибках продолжать работу в штатном режиме.
   2. При наличии информации об ошибках чётко различать ошибки двух категорий:
      • ошибки, которые касаются запросов о состоянии платежей (когда HTTP-код ответа на запрос о состоянии платежа не равен 200 и в теле ответа представлена информация об ошибках по запросу);
      • ошибки, которые касаются искомых платежей и запросов на действия по ним (когда HTTP-код ответа на запрос о состоянии платежа равен 200 и в теле ответа представлена информация об ошибках по платежу).
   3. При получении информации об ошибках, касающихся запросов о состоянии платежей, корректировать эти запросы (когда это актуально) и отправлять их повторно.
   4. При получении информации об ошибках, касающихся искомых платежей и запросов на действия по ним, анализировать содержание ответов и принимать соответствующие действия, включая уведомления пользователей и повторную отправку запросов на действия по платежам, когда это актуально (подробнее).
      Внимание: При отправке повторных запросов на действия по платежам важно избегать дублирования платежей и таких операций, как частичные возвраты, когда они могут быть ошибочно инициированы более одного раза и выполнены без технических ошибок. Ответственность за дублирование действий в таких ситуациях возлагается на мерчанта.

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

   5. При получении ответов о том, что информация об искомом платеже отсутствует в платформе, реагировать в соответствии с процедурой, описанной далее .

Схему реагирования на ответы о состоянии платежей можно представить следующим образом.

Примеры ответов с ошибками разных типов представлены в соответствующем разделе.

Реагирование на отсутствие информации о платежах

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

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

В таких ситуациях рекомендуется действовать следующим образом.

1. Убедиться, что в исходном запросе о состоянии платежа были указаны корректные идентификаторы проекта и платежа (платёж с искомыми идентификаторами должен быть предварительно инициирован со стороны веб-сервиса).
2. Выполнить одно из следующих действий с учётом результата проверки на шаге 1:
   1. Если была выявлена ошибка с идентификаторами, сформировать и отправить запрос со скорректированными параметрами.
   2. Если не было выявлено ошибки с идентификаторами, взять тайм-аут не менее двух секунд и отправить повторный запрос с исходными параметрами.
3. Если по результатам шага 2 не удалось получить информацию об искомом платеже, выполнить повторные попытки с интервалами не менее двух секунд — до первой успешной (с получением искомой информации) либо до исчерпания предельного числа попыток, определяемого на стороне веб-сервиса (в общем случае рекомендуется делать не более десяти попыток).
4. Если по результатам шага 3 не удалось получить информацию об искомом платеже и ситуация допускает повторное инициирование этого платежа, повторить запрос на его проведение (с использованием того же идентификатора), убедиться в получении синхронного ответа о приёме этого запроса в обработку и продолжить работу по этому платежу в штатном режиме.
5. Если по результатам предыдущих действий не удалось получить информацию о платеже и инициировать его повторно, уведомить пользователя о технических проблемах с проведением платежа, обратиться к специалистам технической поддержки Ecommpay и согласовать с ними актуальные действия, включая возможность инициирования нового платежа вместо искомого.
   Внимание: Чтобы не допускать дублирования платежей, не следует инициировать новые платежи (с новыми идентификаторами) вместо тех, по которым не удалось получить информацию, до тех пор, пока это не согласовано со специалистами технической поддержки Ecommpay.

Повторное инициирование операций

В работе с платежами и операциями по ним следует учитывать различие между двумя ситуациями с повторными запросами:

• независимо от того, был ли зарегистрирован в платформе ранее инициированный платёж, повторная отправка запроса на его проведение с тем же идентификатором в параметре payment_id не приводит к дублированию (поскольку если платёж с таким идентификатором уже был зарегистрирован, новый запрос на его проведение отклоняется и никак не влияет на состояние платежа);
• в ситуациях, когда платёж был зарегистрирован в платформе, повторно инициируемая операция по нему может приводить к дублированию действий (поскольку может интерпретироваться как последующая операцию по платежу, например в случаях с частичными возвратами), и в связи с этим перед повторным инициированием действий по любому платежу критически важно получить и корректно интерпретировать информацию о состоянии этого платежа и операций по нему.

В случаях, когда может быть актуальным повторно инициировать определённую операцию по платежу, рекомендуется действовать следующим образом:

1. Получить информацию о состоянии целевого платежа.

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

2. Проанализировать полученные сведения об операциях по платежу и определить, есть ли среди них операция, которую планируется инициировать повторно.

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

3. Выполнить одно из следующих действий с учётом результата анализа на шаге 2:
   1. Если информация об искомой операции найдена и для этой операции указан конечный статус (success или decline) — реагировать, исходя из статуса операции.

      Для выполненной операции (со статусом success) не следует инициировать никаких повторных действий. Для отклонённой операции (со статусом decline) следует уточнить причину отклонения и, если это допустимо с учётом причины отклонения и сценария работы веб-сервиса, инициировать операцию повторно.

   2. Если информация об искомой операции найдена и для этой операции указан промежуточный статус (например, processing или awaiting clarification) — реагировать, исходя из типа и статуса операции.

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

   3. Если информация об искомой операции не найдена, но в ответе есть информация о некорректном запросе — устранить указанные ошибки и отправить скорректированный запрос.

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

   4. Если в ответе нет информации ни об искомой операции, ни о некорректном запросе — взять дополнительный тайм-аут не менее десяти секунд, повторить шаги 1 и 2 и при получении такого же результата отправить повторный запрос, если на стороне веб-сервиса есть готовность к повторному инициированию операции.

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

Схематично такую процедуру можно представить следующим образом.

При возникновении вопросов в любой из описанных ситуаций можно обращаться к специалистам технической поддержки Ecommpay.

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

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