Дополнение информации о платеже

Общая информация

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

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

Далее представлены сведения о работе с дополнением информации.

Схема работы

Необходимость предоставить данные может быть выявлена как на стороне платёжной системы или провайдера, так и на стороне платёжной платформы.

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

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

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

Как только в платёжную платформу поступают все запрашиваемые данные, проведение платежа продолжается дальше.

В рамках взаимодействия с платёжной платформой для дополнения информации со стороны веб-сервиса необходимо:

1. Получить список параметров в объекте clarification_fields в оповещении или ответе.
2. Отправить POST-запрос, содержащий требуемый набор данных с объектом additional_data и подпись, к конечной точке /v2/payment/clarification.
3. Получить и обработать ответ о приёме запроса в обработку — 200 OK.

Ответ 200 OK отправляется, когда все запрашиваемые параметры указаны корректно и в полном объёме. При невыполнении хотя бы одного условия цикл повторяется, начиная с шага 1.

Информация о форматах сообщений о необходимости дополнить данные и о формате запроса на продолжение платежа приведена далее.

Форматы сообщений с запрашиваемыми данными

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

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

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: example.com
{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "clarification_fields": {                  // Запрашиваемая информация
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the customer's consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The text to be displayed on the payment form",
          "default": "The consent text to be displayed to the customer"
        }
      }
    }
  }
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

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

Формат запроса для продолжения платежа

Запрос для продолжения платежа с учётом дополнения данных отправляется методом POST к конечной точке /v2/payment/clarification и должен содержать следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от Benker при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• additional_data — объект с запрошенными данными. Параметры в объекте могут быть указаны полностью, частично или не указаны совсем.

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и данные, которые требуются для продолжения платежа.

{
    "general": {
        "project_id": 200,
        "payment_id": "abc12345",
        "signature": "PJkV8ej\/UG0Di8jQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "The consent text displayed to the customer"
        }
    }
 ...
}