Формат запросов на проведение платежей через Gate

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

При переходе к 3‑D Secure 2 для запросов на проведение платежей используется стандартный формат с поддержкой параметров, которые не являются обязательными, но рекомендуются для повышения вероятности выбора варианта аутентификации frictionless flow. К таким параметрам относятся как новые параметры, так и поддержанные ранее.

Общее описание форматов запросов при работе через Gate представлено в разделе Организация взаимодействия, а описание объектов и параметров, использование которых рекомендуется для повышения вероятности выбора варианта аутентификации frictionless flow, — в этом разделе.

Новый объект acs_return_url

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

ПАРАМЕТР ТИП ОПИСАНИЕ
return_url string Адрес веб-сервиса для перенаправления пользователя после аутентификации, является обязательным при использовании расширенной схемы
3ds_notification_url string Адрес веб-сервиса для получения уведомления о том, что данные приняты сервером управления доступом. Является обязательным, если на стороне мерчанта необходимо получать такие уведомления в рамках аутентификации по расширенной схеме

Новые параметры в объекте customer

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

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

Описания этих параметров представлены в таблицах далее.

Табл. 1. Информация о браузере пользователя
ПАРАМЕТР ТИП ОПИСАНИЕ
accept_header string Значение HTTP-заголовка Accept, полученного со стороны браузера пользователя
color_depth integer Глубина цвета браузера пользователя в битах на пиксель
java_enabled boolean Индикатор поддержки сценариев Java браузером пользователя
js_enabled boolean Индикатор поддержки сценариев JavaScript браузером пользователя
timezone_offset string Разница между временем браузера пользователя и UTC, указывается в минутах (например, -120)
Табл. 2. Информация об учётной записи пользователя на стороне веб-сервиса
ПАРАМЕТР ТИП ОПИСАНИЕ
address_match boolean

Указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте shipping

home_phone string Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44991234567)
work_phone string Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44997654321)
account — объект, содержащий информацию об учётной записи пользователя на стороне мерчанта
additional string Дополнительная информация об учётной записи пользователя, например её идентификатор; в произвольном формате с использованием до шестидесяти четырёх символов
activity_day integer Количество попыток проведения оплаты за последние 24 часа, не более трёх символов (999)
activity_year integer Количество попыток проведения оплаты за последние 365 дней, не более трёх символов (999)
age_indicator string Количество дней с момента создания учётной записи пользователя. Возможные значения:
  • 01 — платёж проводится без аутентификации в учётной записи,
  • 02 — учётная запись создана в день проведения платежа,
  • 03 — менее 30 дней,
  • 04 — от 30 до 60 дней,
  • 05 — более 60 дней
auth_data string Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов
auth_method string Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения:
  • 01 — доступ без аутентификации;
  • 02 — аутентификация с использованием данных, сохранённых на стороне мерчанта;
  • 03 — аутентификация с использованием Federated ID (например, Google Account или Facebook);
  • 04 — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online (FIDO)
auth_time string Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате ДД-ММ-ГГГГчч:мм
date string Дата создания учётной записи в формате ДД-ММ-ГГГГ
change_date string Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате ДД-ММ-ГГГГ
change_indicator string Количество дней с момента последних изменений в учётной записи, за исключением изменения или сброса пароля. Возможные значения:
  • 01 — изменения в день проведения платежа,
  • 02 — менее 30 дней,
  • 03 — от 30 до 60 дней,
  • 04 — более 60 дней
pass_change_date string Дата последнего изменения или сброса пароля в формате ДД-ММ-ГГГГ
pass_change_indicator string Количество дней с момента последнего изменения или сброса пароля. Возможные значения:
  • 01 — пароль не был изменён или сброшен,
  • 02 — пароль был изменён или сброшен в день проведения платежа,
  • 03 — менее 30 дней,
  • 04 — от 30 до 60 дней,
  • 05 — более 60 дней
payment_age string Дата добавления платёжных данных карты в формате ДД-ММ-ГГГГ
payment_age_indicator string Количество дней с момента сохранения данных платёжной карты, используемой для проведения платежа, в учётной записи пользователя. Возможные значения:
  • 01 — платёж проводится без аутентификации в учётной записи,
  • 02 — данные карты сохранены в день проведения платежа,
  • 03 — менее 30 дней,
  • 04 — от 30 до 60 дней,
  • 05 — более 60 дней
provision_attempts integer Количество попыток сохранения новых платёжных данных карты за последние 24 часа, не более трёх символов (999)
purchase_number integer Количество покупок, совершённых через эту учётную запись за последние 6 месяцев, не более четытрёх символов (9999)
suspicious_activity string Индикатор подозрительной активности. Возможные значения:
  • 01 — без подозрений,
  • 02 — с подозрительной активностью
Табл. 3. Информация о доставке товара или услуги пользователю
ПАРАМЕТР ТИП ОПИСАНИЕ
shipping — объект, содержащий информацию о доставке
address string Адрес доставки, не более ста пятидесяти символов
address_usage string Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате ДД-ММ-ГГГГ
address_usage_indicator string Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения:
  • 01 — указанный адрес используется впервые,
  • 02 — менее 30 дней назад,
  • 03 — от 30 до 60 дней назад,
  • 04 — более 60 дней назад
city string Название города доставки, не более пятидесяти символов
country string Код страны доставки в формате ISO 3166-1 alpha-2 (например, GB)
delivery_email string Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов
delivery_time string Срок доставки. Возможные значения:
  • 01 — электронная доставка в день покупки,
  • 02 — доставка в день покупки,
  • 03 — доставка на следующий день после покупки,
  • 04 — доставка более чем через один день после покупки
name_indicator string Индикатор совпадения имени пользователя с именем получателя. Возможные значения:
  • 01 — имена совпадают,
  • 02 — имена не совпадают
postal string Почтовый индекс доставки, не более шестнадцати символов
region_code string Код штата, провинции или региона страны в формате ISO 3166-2, например SPE для Санкт-Петербурга.

При указании значения этого параметра также необходимо указать значение параметра country в объекте shipping

type string Способ доставки, выбранный пользователем. Возможные значения:
  • 01 — доставка на платёжный адрес держателя карты;
  • 02 — доставка на другой подтверждённый адрес;
  • 03 — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым;
  • 04 — доставка в магазин;
  • 05 — электронная доставка;
  • 06 — без доставки (например, в случае покупки билетов на мероприятие);
  • 07 — другое
Табл. 4. Данные о предыдущей аутентификации пользователя
ПАРАМЕТР ТИП ОПИСАНИЕ
mpi_result — объект с данными о предыдущей аутентификации пользователя
acs_operation_id string Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре acs_operation_id оповещения о результате проведения предыдущего платежа
authentication_flow string

Указатель варианта предыдущего прохождения аутентификации пользователем, полученное в параметре authentication_flow оповещения о результате проведения предыдущего платежа.

Возможные значения:

  • 01 — frictionless flow,
  • 02 — challenge flow
authentication_timestamp string Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре mpi_timestamp оповещения о результате проведения предыдущего платежа

Новые параметры в объекте payment

ПАРАМЕТР ТИП ОПИСАНИЕ
challenge_indicator string Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения:
  • 01 — без предпочтений;
  • 02 — предпочтительно не выполнять;
  • 03 — предпочтительно выполнять;
  • 04 — обязательно выполнять;
  • 05 — не выполнять, анализ рисков выполнен на стороне мерчанта;
  • 06 — не выполнять, применить сценарий Data Only;
  • 07 — не выполнять, Strong Customer Authentication уже выполнена иным способом;
  • 08 — не выполнять, мерчант включен в список доверенных для этого пользователя;
  • 09 — обязательно выполнять, предпочтительно предложить пользователю добавить мерчанта в список доверенных
challenge_window string Размер окна для открытия страницы аутентификации. Возможные значения:
  • 01 — 250 x 400 пикселей,
  • 02 — 390 x 400 пикселей,
  • 03 — 500 x 600 пикселей,
  • 04 — 600 x 400 пикселей,
  • 05 — полноэкранный режим
preorder_date string Планируемая дата поступления товара или услуги в формате ДД-ММ-ГГГГ
preorder_purchase string Индикатор предварительного заказа. Возможные значения:
  • 01 — не является предварительным заказом,
  • 02 — является предварительным заказом
reorder string Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения:
  • 01 — первичная покупка,
  • 02 — повторная покупка
gift_card — объект с информацией об оплате предоплаченными или подарочными картами
amount integer Общая сумма оплаты предоплаченными или подарочными картами в минорных единицах валюты
currency string Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 (например, GBP)
count integer Количество предоплаченных или подарочных карт, использованных для оплаты

Новый параметр в объекте billing

ПАРАМЕТР ТИП ОПИСАНИЕ
region_code string Код штата, провинции или региона страны в формате ISO 3166-2, например MOS для Московской области.

При указании значения этого параметра также необходимо указать значение параметра billing_country

Ранее поддержанные параметры

Для повышения вероятности выбора аутентификации варианта аутентификации frictionless flow в запросах на открытие платёжной формы рекомендуется использовать не только новые параметры, но и некоторые из реализованных ранее. К таким параметрам относятся параметры из объекта customer, перечисленные далее.

ПАРАМЕТР ТИП ОПИСАНИЕ
email string Адрес электронной почты пользователя
phone string Номер телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх
billing — объект с информацией о платёжном адресе пользователя
address string Улица платёжного адреса пользователя
city string Город платёжного адреса пользователя
country string Страна платёжного адреса пользователя в формате ISO 3166-1 alpha-2
postal string Почтовый индекс платёжного адреса пользователя