Аутентификация 3‑D Secure

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

Аутентификация пользователя с использованием протокола 3‑D Secure (Three-Domain Secure) предназначена для безопасного проведения интернет-оплат с использованием платёжных карт. Такая аутентификация, как правило, обязательна для проведения оплаты и может выполняться по-разному: как с необходимостью пользователя выполнить определённые действия для подтверждения своей личности, так и без такой необходимости.в следующих вариантах:

Notice: В этой статье представлена информация о второй версии протокола 3‑D Secure, 3‑D Secure 2, так как поддержка первой версии платёжными системами American Express, Mastercard и Visa прекращена.

Аутентификация 3‑D Secure может выполняться в следующих вариантах:

  • Аутентификация без участия пользователя (frictionless flow). Выбор эмитентом этого варианта способствует повышению проходимости и улучшению пользовательского опыта.
  • Аутентификация с подтверждением пользователем своей личности (challenge flow). Подтверждение личности пользователя может выполняться, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом.


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

Пользовательские сценарии

Со стороны пользователя проведение оплаты с аутентификацией 3‑D Secure может выглядеть следующим образом:

  1. На стороне веб-сервиса мерчанта пользователь подтверждает готовность перейти к оплате.
  2. Пользователю отображается платёжная форма с учётом параметров её вызова, после чего он выполняет необходимые действия, подтверждает оплату и ему отображается страница ожидания Payment Page.
  3. Если эмитентом выбран вариант аутентификации challenge flow, пользователю отображается страница аутентификации (ACS), после чего он выполняет необходимые действия и ему отображается страница ожидания Payment Page.
  4. Пользователю отображается страница Payment Page с информацией о результате оплаты.

Подключение

Аутентификация 3‑D Secure подключается для проекта специалистами ecommpay вместе с подключением карточных платежей, дополнительных действий со стороны мерчанта не требуется.

Форматы данных

В запросах на проведение платежей с прямым использованием платёжных карт необходимо передавать один из следующих параметров.

Параметры Описание

customer_email
string

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

customer_phone
string

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

В запросах на проверку платёжных инструментов (режим работы платёжной формы Card Verify) передавать эти параметры не требуется.

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

Параметр Описание

payment_merchant_risk
string

Информация о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации.

Передаётся в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта payment с необходимыми объектами и параметрами.

Рис. 1. Пример JSON-объекта
{ 
  "payment":{ 
    "reorder":"01",
    "preorder_purchase":"01",
    "preorder_date":"11-10-2022",
    "challenge_indicator":"01",
    "challenge_window":"01",
    "gift_card":{ 
      "amount":12345,
      "currency":"USD",
      "count":1
    }
  }
}
Рис. 2. Пример строки
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==
 2

challenge_indicator
string

 Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения:
  • 01 — без предпочтений
  • 02 — предпочтительно не выполнять
  • 03 — предпочтительно выполнять
  • 04 — обязательно выполнять
  • 05 — не выполнять, анализ рисков выполнен на стороне мерчанта
  • 06 — не выполнять, применить сценарий Data Only
  • 07 — не выполнять, Strong Customer Authentication уже выполнена иным способом
  • 08 — не выполнять, мерчант включен в список доверенных для этого пользователя
  • 09 — обязательно выполнять, предпочтительно предложить пользователю добавить мерчанта в список доверенных
 2-12

challenge_window
string

 Размер окна для открытия страницы аутентификации. Возможные значения:
  • 01 — 250 x 400 пикселей
  • 02 — 390 x 400 пикселей
  • 03 — 500 x 600 пикселей
  • 04 — 600 x 400 пикселей
  • 05 — полноэкранный режим
 2-22

preorder_date
string

 Планируемая дата поступления товара или услуги в формате ДД-ММ-ГГГГ 2-32

preorder_purchase
string

 Индикатор предварительного заказа. Возможные значения:
  • 01 — не является предварительным заказом
  • 02 — является предварительным заказом
 2-42

reorder
string

 Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения:
  • 01 — первичная покупка
  • 02 — повторная покупка
 2-52

gift_card
object

 Объект с информацией об оплате предоплаченными или подарочными картами 2-62

amount
integer

 Общая сумма оплаты предоплаченными или подарочными картами в минорных единицах валюты 2-6-12-6

currency
string

 Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 (например, GBP) 2-6-22-6

count
integer

 Количество предоплаченных или подарочных карт, использованных для оплаты 2-6-32-6

customer_account_info
string

Информация об учётной записи пользователя на стороне веб-сервиса и о контактных данных пользователя.

Передаётся в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта customer с необходимыми объектами и параметрами.

Рис. 3. Пример JSON-объекта
{ 
  "customer":{ 
    "address_match":"Y",
    "home_phone":"79105211111",
    "work_phone":"74955211111",
    "account":{ 
      "additional":"gamer12345",
      "age_indicator":"01",
      "date":"01-10-2022",
      "change_indicator":"01",
      "change_date":"01-10-2022",
      "pass_change_indicator":"01",
      "pass_change_date":"01-10-2022",
      "purchase_number":12,
      "provision_attempts":16,
      "activity_day":22,
      "activity_year":222,
      "payment_age_indicator":"01",
      "payment_age":"01-10-2022",
      "suspicious_activity":"01",
      "auth_method":"01",
      "auth_time":"01-10-202213:12",
      "auth_data":"login_0102"
    }
  }
}
Рис. 4. Пример строки
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI3OTEwNTIxMTExMSIsCiAgICAid29ya19waG9uZSI6Ijc0OTU1MjExMTExIiwKICAgICJhY2NvdW50Ijp7IAogICAgICAiYWRkaXRpb25hbCI6ImdhbWVyMTIzNDUiLAogICAgICAiYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImRhdGUiOiIwMS0xMC0yMDIyIiwKICAgICAgImNoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJjaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicGFzc19jaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGFzc19jaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicHVyY2hhc2VfbnVtYmVyIjoxMiwKICAgICAgInByb3Zpc2lvbl9hdHRlbXB0cyI6MTYsCiAgICAgICJhY3Rpdml0eV9kYXkiOjIyLAogICAgICAiYWN0aXZpdHlfeWVhciI6MjIyMiwKICAgICAgInBheW1lbnRfYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBheW1lbnRfYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJzdXNwaWNpb3VzX2FjdGl2aXR5IjoiMDEiLAogICAgICAiYXV0aF9tZXRob2QiOiIwMSIsCiAgICAgICJhdXRoX3RpbWUiOiIwMS0xMC0yMDIyMTM6MTIiLAogICAgICAiYXV0aF9kYXRhIjoibG9naW5fMDEwMiIKICAgIH0KICB9Cn0==
 3

address_match
string

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

Возможные значения:
  • Y — совпадает
  • N — не совпадает
 3-13

home_phone
string

 Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44991234567) 3-23

work_phone
string

 Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44997654321) 3-33

account
object

 Объект, содержащий информацию об учётной записи пользователя на стороне мерчанта 3-43

additional
string

 Дополнительная информация об учётной записи пользователя, например её идентификатор; в произвольном формате с использованием до шестидесяти четырёх символов 3-4-13-4

activity_day
integer

 Количество попыток проведения оплаты за последние 24 часа, не более трёх символов (999) 3-4-23-4

activity_year
integer

 Количество попыток проведения оплаты за последние 365 дней, не более трёх символов (999) 3-4-33-4

age_indicator
string

 Количество дней с момента создания учётной записи пользователя. Возможные значения:
  • 01 — платёж проводится без аутентификации в учётной записи
  • 02 — учётная запись создана в день проведения платежа
  • 03 — менее 30 дней
  • 04 — от 30 до 60 дней
  • 05 — более 60 дней
 3-4-43-4

auth_data
string

 Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов 3-4-53-4

auth_method
string

 Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения:
  • 01 — доступ без аутентификации
  • 02 — аутентификация с использованием данных, сохранённых на стороне мерчанта
  • 03 — аутентификация с использованием Federated Identity (например, Google Account или Facebook)
  • 04 — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online (FIDO)
 3-4-63-4

auth_time
string

 Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате ДД-ММ-ГГГГчч:мм 3-4-73-4

date
string

 Дата создания учётной записи в формате ДД-ММ-ГГГГ 3-4-83-4

change_date
string

 Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате ДД-ММ-ГГГГ 3-4-93-4

change_indicator
string

 Количество дней с момента последних изменений в учётной записи, за исключением изменения или сброса пароля. Возможные значения:
  • 01 — изменения в день проведения платежа
  • 02 — менее 30 дней
  • 03 — от 30 до 60 дней
  • 04 — более 60 дней
 3-4-103-4

pass_change_date
string

 Дата последнего изменения или сброса пароля в формате ДД-ММ-ГГГГ 3-4-113-4

pass_change_indicator
string

 Количество дней с момента последнего изменения или сброса пароля. Возможные значения:
  • 01 — пароль не был изменён или сброшен
  • 02 — пароль был изменён или сброшен в день проведения платежа
  • 03 — менее 30 дней
  • 04 — от 30 до 60 дней
  • 05 — более 60 дней
 3-4-123-4

payment_age
string

 Дата добавления платёжных данных карты в формате ДД-ММ-ГГГГ 3-4-133-4

payment_age_indicator
string

 Количество дней с момента сохранения данных платёжной карты, используемой для проведения платежа, в учётной записи пользователя. Возможные значения:
  • 01 — платёж проводится без аутентификации в учётной записи
  • 02 — данные карты сохранены в день проведения платежа
  • 03 — менее 30 дней
  • 04 — от 30 до 60 дней
  • 05 — более 60 дней
 3-4-143-4

provision_attempts
integer

 Количество попыток сохранения новых платёжных данных карты за последние 24 часа, не более трёх символов (999) 3-4-153-4

purchase_number
integer

 Количество покупок, совершённых через эту учётную запись за последние 6 месяцев, не более четырёх символов (9999) 3-4-163-4

suspicious_activity
string

 Индикатор подозрительной активности. Возможные значения:
  • 01 — без подозрений
  • 02 — с подозрительной активностью
 3-4-173-4

customer_shipping
string

Информация о доставке товара или услуги пользователю.

Передаётся в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта customer с необходимыми объектами и параметрами.

Рис. 5. Пример JSON-объекта
{ 
  "customer":{ 
    "shipping":{ 
      "type":"01",
      "delivery_time":"01",
      "delivery_email":"test@gmail.com",
      "address_usage_indicator":"01",
      "address_usage":"01-10-2022",
      "city":"Moscow",
      "country":"RU",
      "address":"Lenina street 12",
      "postal":"109111",
      "region_code":"RU",
      "name_indicator":"01"
    }
  }
}
Рис. 6. Пример строки
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTW9zY293IiwKICAgICAgImNvdW50cnkiOiJSVSIsCiAgICAgICJhZGRyZXNzIjoiTGVuaW5hIHN0cmVldCAxMiIsCiAgICAgICJwb3N0YWwiOiIxMDkxMTEiLAogICAgICAicmVnaW9uX2NvZGUiOiJSVSIsCiAgICAgICJuYW1lX2luZGljYXRvciI6IjAxIgogICAgfQogIH0KfQ====
 4

shipping
object

 Объект, содержащий информацию о доставке 4-14

address
string

 Адрес доставки, не более ста пятидесяти символов 4-1-14-1

address_usage
string

 Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате ДД-ММ-ГГГГ 4-1-24-1

address_usage_indicator
string

 Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения:
  • 01 — указанный адрес используется впервые
  • 02 — менее 30 дней назад
  • 03 — от 30 до 60 дней назад
  • 04 — более 60 дней назад
 4-1-34-1

city
string

 Название города доставки, не более пятидесяти символов 4-1-44-1

country
string

 Код страны доставки в формате ISO 3166-1 alpha-2 (например, GB) 4-1-54-1

delivery_email
string

 Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов 4-1-64-1

delivery_time
string

 Срок доставки. Возможные значения:
  • 01 — электронная доставка в день покупки
  • 02 — доставка в день покупки
  • 03 — доставка на следующий день после покупки
  • 04 — доставка более чем через один день после покупки
 4-1-74-1

name_indicator
string

 Индикатор совпадения имени пользователя с именем получателя. Возможные значения:
  • 01 — имена совпадают
  • 02 — имена не совпадают
 4-1-84-1

postal
string

 Почтовый индекс доставки, не более шестнадцати символов 4-1-94-1

region_code
string

 Код штата, провинции или региона страны в формате ISO 3166-2, например SPE для Санкт-Петербурга.

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

 4-1-104-1

type
string

 Способ доставки, выбранный пользователем. Возможные значения:
  • 01 — доставка на платёжный адрес держателя карты
  • 02 — доставка на другой подтверждённый адрес
  • 03 — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым
  • 04 — доставка в магазин
  • 05 — электронная доставка
  • 06 — без доставки (например, в случае покупки билетов на мероприятие)
  • 07 — другое
 4-1-114-1

customer_mpi_result
string

Информация о предыдущей аутентификации пользователя.

Передаётся в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта customer с объектом mpi_result и необходимыми объектами и параметрами.

Рис. 7. Пример JSON-объекта
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210101050"
    }
  }
}
Рис. 8. Пример строки
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0==
 5

mpi_result
object

 Объект с данными о предыдущей аутентификации пользователя 5-15

acs_operation_id
string

 Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре acs_operation_id оповещения о результате проведения предыдущего платежа 5-1-15-1

authentication_flow
string

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

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

  • 01 — frictionless flow
  • 02 — challenge flow
 5-1-25-1

authentication_timestamp
string

 Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре mpi_timestamp оповещения о результате проведения предыдущего платежа 5-1-35-1

billing_address
string

 Улица платёжного адреса пользователя 6

billing_city
string

 Город платёжного адреса пользователя 7

billing_country
string

 Страна платёжного адреса пользователя в формате ISO 3166-1 alpha-2 8

billing_postal
string

 Почтовый индекс платёжного адреса пользователя 9

billing_region_code
string

 Код штата, провинции или региона страны в формате ISO 3166-2, например MOS для Московской области.

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

 10

customer_email
string

 Адрес электронной почты пользователя 11

customer_phone
string

 Номер телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх 12