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

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

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

Информация, запрашиваемая в качестве дополнительной, обычно касается пользователя и его платёжного средства: для платежей с использованием карт это могут быть параметры объектов avs_data (для проверки Address Verification Service, AVS) и customer, а для платежей с использованием альтернативных методов — необязательные параметры из числа допустимых для исходного запроса на проведение платежа.

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

Рис. 1. Оповещение
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 сообщается о необходимости указать электронную почту, имя и фамилию, платёжный адрес и дату рождения пользователя.

Рис. 2. Ответ
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"
        }
    ]
}

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

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

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

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

{
  "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 указаны электронная почта, имя и фамилия, платёжный адрес и дата рождения пользователя (в соответствии с запрошенными данными в примере ответа выше).

// Тело запроса для продолжения платежа
{
    "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"
        }
    }
}