# Дополнение информации о платеже {#ru_Gate_Clarification .concept} статья о процедуре предоставления дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Gate ## Общая информация {#section_jdm_zr3_m3b .section} Как правило, для проведения платежа достаточно тех данных, которые обязательны для запроса на инициирование этого платежа. Но в отдельных случаях — например, для соблюдения специфических региональных требований или для дополнительной проверки на мошенничество — со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необязательные в общем случае, но необходимые в конкретной ситуации. В платёжной платформе для работы с такими ситуациями используется процедура дополнения информации, в рамках которой обеспечиваются информирование о составе запрашиваемых данных и ожидание предоставления этих данных. При этом поддерживается гибкость как со способом информирования, так и с порядком предоставления данных. Подробные сведения об этом представлены далее. Информация, запрашиваемая в качестве дополнительной, обычно касается пользователя и его платёжного средства: для платежей с использованием карт это могут быть параметры объектов `avs_data` \(для проверки Address Verification Service, [AVS](ru_Gate_avs.md)\) и `customer`, а для платежей с использованием альтернативных методов — необязательные параметры из числа допустимых для исходного запроса на проведение платежа. Со стороны веб-сервиса можно обеспечить передачу полной информации во всех запросах на инициирование платежей \(и уйти от необходимости в дополнении информации\) либо настроить реагирование на ситуации с необходимостью дополнения \(и поддерживать проведение платежей в таких случаях\). Далее представлены сведения о работе с дополнением информации. ## Схема работы {#section_ljh_kw5_zgb .section} Необходимость предоставить данные может быть выявлена как на стороне платёжной системы или провайдера, так и на стороне платёжной платформы. В платёжной платформе поддерживаются *два способа информирования* о необходимости дополнить данные: через оповещения и ответы. Обычно эта информация отправляется в оповещениях — без предварительных запросов со стороны веб-сервиса, но в то же время её можно получать в ответах на запросы о статусе платежа. По согласованию с курирующим менеджером Ecommpay можно отключить отправку оповещений и оставить только отправку ответов на запросы. Со стороны веб-сервиса *реагирование* на сообщение о необходимости дополнения данных сводится к составлению и отправке в платформу корректного запроса на продолжение платежа. Время ожидания такого запроса составляет 30 минут и измеряется с момента выявления необходимости дополнить данные и до получения запроса от веб-сервиса. Если время ожидания истекло и запрос в платформе не принят — платёж автоматически отклоняется. Процедура дополнения данных может включать в себя неоднократную отправку таких запросов, при приёме которых отсчёт времени в платформе каждый раз начинается сначала. Время приёма повторных запросов ограничено только предельным временем проведения конкретного платежа. *Состав запрошенных данных* в теле запроса может варьироваться: данные можно указывать в полном объёме, частично или не указывать совсем, но в любом случае в теле запроса должен содержаться объект `additional_data`. При приёме запроса без этого объекта запрос признаётся некорректным и к веб-сервису отправляется ответ с информацией об ошибке. При приёме каждого корректного запроса обновляется список запрашиваемых данных, о чём сообщается любым из способов информирования. Как только в платёжную платформу поступают все запрашиваемые данные, проведение платежа продолжается дальше. ![](images/ru_clarification_uml.svg) В рамках взаимодействия с платёжной платформой для дополнения информации со стороны веб-сервиса необходимо: 1. Получить список параметров в объекте `clarification_fields` в оповещении или ответе. 2. Отправить POST-запрос, содержащий требуемый набор данных с объектом `additional_data` и подпись, к конечной точке [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification). 3. Получить и обработать ответ о приёме запроса в обработку — `200 OK`. Ответ `200 OK` отправляется, когда все запрашиваемые параметры указаны корректно и в полном объёме. При невыполнении хотя бы одного условия цикл повторяется, начиная с шага 1. Информация о форматах сообщений о необходимости дополнить данные и о формате запроса на продолжение платежа приведена далее. ## Форматы сообщений с запрашиваемыми данными {#section_oyf_d4j_m3b .section} Информация о необходимости дополнить данные может передаваться как в оповещении, так и в ответе на запрос статуса платежа. *Для оповещения* о необходимости дополнить данные используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). К особенностям оповещения в этом случае можно отнести наличие объекта `clarification_fields` со списком запрашиваемых параметров.Так, в следующем примере запрашиваются индекс и адрес пользователя, необходимые для проверки AVS при проведении оплаты с использованием платёжной карты. ```language-json 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 { "sum_request": { "amount": 45000, "currency": "USD" }, "request_id": "80bdc0831c3f8e1", "payment": { "id": "", "method": "card", "date": "2019-07-29T11:19:33+0000", "result_code": "9999", "result_message": "Awaiting processing", "is_new_attempts_available": false, "attempts_timeout": 0, "provider_id": 3 }, "sum_real": { "amount": 45000, "currency": "USD" }, "status": "awaiting clarification", // Статус платежа "customer": { "id": "4314220000000056" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "JUDY DOE", "expiry_month": "03", "expiry_year": "2021" }, "clarification_fields": { // Запрашиваемая информация "avs_data": [ "avs_post_code", "avs_street_address" ] }, "general": { "project_id": 11, "payment_id": "EPr-bf14", "signature": "99q4lpCEuNpxp3ugvxF1qPbinWUIwNSLaxcVbF0A==" }, "description": "", "operations": [ { "id": 7282148104130, "type": "sale", "status": "awaiting clarification", "date": "2019-07-29T11:19:33+0000", "processing_time": null, "sum": { "amount": 45000, "currency": "USD" }, "code": "9999", "message": "Awaiting processing" } ] } ``` *Для ответа* о необходимости дополнить информацию используется формат, который совпадает как для оповещений, так и для ответов в рамках исходного запроса на проведение платежа.В следующем примере ответа на запрос к конечной точке [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status) сообщается о необходимости указать электронную почту, имя и фамилию, платёжный адрес и дату рождения пользователя. ```language-json HTTP/1.1 200 OK Server: api.com Date: Wed, 29 July 2019 09:27:45 GMT Content-Type: application/json; charset=UTF-8 Content-Length: 875 Connection: keep-alive Keep-Alive: timeout=60 Cache-Control: no-cache Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Origin: * X-Powered-By: PHP/7.0.32 Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent, X-Requested-With,If-Modified-Since,Cache-Control,Content-Type { "sum_request": { "amount": 500, "currency": "CNY" }, "request_id": "563c42d4846d105e77", "payment": { "method": "cup-card", "date": "2019-07-29T09:27:45+0000", "result_code": "9999", "result_message": "Awaiting processing", "status": "awaiting clarification", // Статус платежа "is_new_attempts_available": false, "attempts_timeout": 0, "id": "E2E_01_0868", "cascading_with_redirect": false, "provider_id": 1145 }, "sum_real": { "amount": 500, "currency": "CNY" }, "customer": { "id": "7826" }, "clarification_fields": { // Запрашиваемая информация "customer": [ "email", "first_name", "last_name", "billing.address", "billing.city", "billing.country", "billing.postal", "day_of_birth" ] }, "general": { "project_id": 245, "payment_id": "E2E_01_0868", "signature": "MYiga7aoW0UBFBfeTdIiF0QFOokEfyuSA==" }, "description": "", "operations": [ { "id": 1315207090506, "type": "sale", "status": "awaiting clarification", "date": "2019-07-29T09:27:45+0000", "processing_time": null, "request_id": "563c42d4846d105e77", "sum": { "amount": 500, "currency": "CNY" }, "code": "9999", "message": "Awaiting processing" } ] } ``` ## Формат запроса для продолжения платежа {#section_vgx_ww5_zgb .section} Запрос для продолжения платежа с учётом дополнения данных отправляется методом POST к конечной точке [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) и должен содержать следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\). - `additional_data` — объект с запрошенными данными. Параметры в объекте могут быть указаны полностью, частично или не указаны совсем. **Прим.:** Объект `interface_type` не обязателен для заполнения. Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и данные, которые требуются для продолжения платежа.В следующем примере в качестве дополнительных данных указаны почтовый индекс и адрес пользователя \(в соответствии с запрошенными данными в примере оповещения выше\). ```language-json { "general": { "project_id": 11, "payment_id": "EPr-bf14", "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...==" }, "additional_data": { "avs_data":{ "avs_post_code": "99546", "avs_street_address": "01 Main Street, CA" } } } ``` В следующем примере представлены данные двух запросов. Это может быть актуально для случая, когда 30 минут недостаточно, чтобы предоставить запрошенную информацию в полном объеме. В таком случае сначала от веб-сервиса отправляется запрос только для продолжения платежа, поэтому в объекте `additional_data` параметры совсем не указаны. А далее отправляется запрос для продолжения платежа с учётом запрошенных данных, поэтому в объекте `additional_data` указаны электронная почта, имя и фамилия, платёжный адрес и дата рождения пользователя \(в соответствии с запрошенными данными в примере ответа выше\). ```language-json // Тело запроса для продолжения платежа { "general": { "project_id": 245, "payment_id": "E2E_01_0868", "signature": "5uco0y4eeTdf59R/1SQXdfepidfw==" }, "additional_data": { } } // Тело запроса для продолжения платежа с учётом требуемых данных { "general": { "project_id": 1144, "payment_id": "128755012", "signature": "5uco0y4eeTdf59R/1SQXdfepidfw==" }, "additional_data": { "customer": { "email": "test@testmail.com", "first_name": "杨", "last_name": "思荣", "billing": { "address": "和飞机的事", "city": "市区-东城区", "country": "CN", "postal": "156114" }, "day_of_birth": "12-12-1990" } } } ``` **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md)