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

статья о процедуре предоставления дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Gate

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

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

Информация, запрашиваемая в качестве дополнительной, обычно касается пользователя и его платёжного средства: для платежей с использованием карт это могут быть параметры объектов 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"
        }
    }
}