Прямые платежи с 3DS2

Общее описание

Платежный шлюз поддерживает аутентификацию с помощью протокола 3-D Secure 2.0 (3DSv2), обновленной версии протокола 3-D Secure.

Если вы используете платежную страницу на вашей стороне и хотите использовать аутентификацию клиента по протоколу 3DS 2.0, для каждой транзакции вам необходимо отправить в платёжный шлюз запрос на оплату два раза. Отправка первого запроса инициирует процедуру аутентификации по протоколу 3DS 2.0, а отправка второго — продолжает процедуру с данными, полученным от сервера 3DS (дополнительного компонента, который взаимодействует с платежными системами и ACS).

Если клиент после аутентификации перенаправляется на страницу магазина, необходимо завершить платёж, отправив запрос finish3dsVer2Payment.do.

Проверка подлинности клиента на ACS

Протокол проверки подлинности 3DSv2 в зависимости от настроек ACS банка-эмитента позволяет выполнить проверку подлинности без участия клиента. В этом случае от клиента не потребуется совершать действия для аутентификации, такие как ввод одноразового пароля.

Таким образом, после второго запроса на оплату заказа в зависимости от настроек ACS эмитента возможны два варианта развития событий:

если клиенту не нужно аутентифицироваться на ACS, придёт ответ об оплате;
если клиенту нужно аутентифицироваться на ACS, его браузер будет переадресован на страницу аутентификации, где он должен будет пройти проверку подлинности (схема challenge-response).

Схема интеграции

Direct integration

Клиент выбирает продукт в интернет-магазине и нажимает на кнопку Купить.
Сервер интернет-магазина получает запрос на покупку и открывает платежную страницу.
Покупатель вводит данные своей карты на платежной странице интернет-магазина.
Сервер интернет-магазина собирает данные карты.
Сервер интернет-магазина запрашивает регистрацию заказа, отправляя вызов API register.do. Этот запрос должен содержать параметр amount – сумму платежа в минимальных единицах валюты и параметр returnUrl – адрес, на который будет перенаправлен клиент после успешной оплаты на Шаге 9 (дополнительная информация о перенаправлении доступна здесь). В ответ платежный шлюз отправляет orderId - уникальный номер заказа в системе платежного шлюза.

Пример запроса на регистрацию заказа:
```
curl --request POST \
--url https://abby.rbsuat.com/payment/rest/register.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=2000 \
--data currency=933 \
--data userName=test_user \
--data password=test_user_password \
--data returnUrl=finish.html \
--data description=my_first_order \
--data language=ru
```
Пример ответа на регистрацию заказа:
```
{
"orderId": "0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0",
"formUrl": "https://abby.rbsuat.com/payment/merchants/pay/payment_en.html?mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0"
}
```
Также вы можете удерживать сумму на счете до списания средств с помощью вызова registerPreAuth.do. Чтобы узнать больше о холдировании и завершении, нажмите здесь.
Оплата заказа - этап 1. Мерчант передает карточные данные путем отправки первого API запроса paymentorder.do в платежный шлюз (для оплаты также можно использовать запрос paymentOrderBinding.do, google/payment.do или google/paymentDirect.do). Запрос должен содержать параметр MDORDER - уникальный номер заказа в системе платежного шлюза, возвращенный в ответе на запрос register.do.

Платёжный шлюз проверяет на сервере 3DS возможность проведения аутентификации клиента по протоколу 2.0 и отправляет ответ. В ответе, в том числе, возвращаются следующие параметры:
- is3DSVer2 - флаг возможности проведения аутентификации 3DSv2 (true/false),
- threeDSServerTransId - идентификатор транзакции, присвоенный сервером 3DS,
- threeDSMethodURLServer - адрес сервера 3DS для сбора данных о браузере,
- threeDSMethodURL - (необязательно) адрес сервера ACS для сбора данных о браузере,
- threeDSMethodDataPacked - (необязательно) данные для сбора данных о браузере на ACS.
Пример первого запроса оплаты заказа:
```
curl --request POST \
--url https://abby.rbsuat.com/payment/rest/paymentorder.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data MDORDER=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0 \
--data '$PAN=4000001111111118' \
--data '$CVC=123' \
--data YYYY=2030 \
--data MM=12 \
--data 'TEXT=TEST CARDHOLDER' \
--data 'ip=185.230.240.201' \
--data language=ru
```
Пример ответа на первый запрос оплаты заказа:
```
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "5802746e-3393-40c3-929a-dc966ebf08c6",
"threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
"threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6",
"threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9jb21tb24wMy50c3QucmJzdGVzdC5ydS8zZHNzZXJ2ZXIvYXBpL3YxL2Fjcy9ub3RpZmljYXRpb24_dGhyZWVEU1NlcnZlclRyYW5zSUQ9NTgwMjc0NmUtMzM5My00MGMzLTkyOWEtZGM5NjZlYmYwOGM2IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1ODAyNzQ2ZS0zMzkzLTQwYzMtOTI5YS1kYzk2NmViZjA4YzYifQ"
}
```
Мерчант в отдельном iframe методом POST вызывает threeDSMethodURLServer, используя значение, полученное из ответа на запрос оплаты заказа. Это позволяет серверу 3DS собрать данные о браузере клиента.
(Необязательный шаг) Если в ответе на запрос оплаты заказа пришли параметры threeDSMethodURL и threeDSMethodDataPacked, то мерчант в отдельном iframe методом POST вызывает threeDSMethodURL. В этом методе необходимо передать значение, полученное из параметра threeDSMethodDataPacked, полученного в ответе на запрос оплаты заказа. При этом нужно его передать в параметре, который называется threeDSMethodData. Это позволяет ACS собрать данные о браузере клиента.
Оплата заказа - этап 2. Мерчант повторно отправляет запрос paymentorder.do (или другой запрос, использованный на шаге 6), чтобы завершить оплату заказа (или осуществить перевод денежных средств). При этом необходимо передать параметр threeDSServerTransId - идентификатор транзакции, который был создан сервером 3DS и возвращён на шаге 6. Кроме того, для переадресации клиента на страницу магазина после проведения оплаты заказа можно передать ссылку переадресации в параметре threeDSVer2FinishUrl.

Пример второго запроса оплаты заказа:
```
curl --request POST \
--url https://abby.rbsuat.com/payment/rest/paymentorder.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
--data '$PAN=4000001111111118' \
--data '$CVC=123' \
--data YYYY=2030 \
--data MM=12 \
--data 'TEXT=TEST CARDHOLDER' \
--data language=ru \
--data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6
```
Платежный шлюз взаимодействует с 3DS сервером и ACS, чтобы выяснить, требуется ли клиенту проходить аутентификацию на ACS, и отправляет ответ на запрос оплаты. Если клиенту требуется проходить аутентификацию на ACS, в ответе возвращается acsUrl – URL для перенаправления на ACS, а также packedCReq – упакованные данные для challenge request. Если не требуется (frictionless аутентификация) – возвращается ответ об успешном завершении оплаты.

Пример ответа на второй запрос оплаты заказа:
```
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://example.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU4MDI3NDZlLTMzOTMtNDBjMy05MjlhLWRjOTY2ZWJmMDhjNiIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiODFmZTU1ODUtZmZhOS00Y2NkLTljMjAtY2QzYWFiZDQwNTllIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}
```
Если у вас включена специальная настройка выполнения повторного 3DS 2 challenge при получении soft decline после frictionless аутентификации и Платежный шлюз получил код "soft decline" от процессингового центра банка после frictionless аутентификации, ответ на запрос будет снова содержать параметры 3DS 2 аутентификации (как на шаге 6), в том числе новый threeDSServerTransID.
В этом случае необходимо выполнить ряд дополнительных шагов (см. здесь).
Если клиенту не требуется проходить аутентификацию на ACS, переходите на шаг 13.

Если клиенту требуется проходить аутентификацию на ACS, с платежной страницы происходит перенаправление на acsUrl с параметром creq=packedCReq, полученным на шаге 9.
Клиент проходит проверку подлинности и ACS перенаправляет его на страницу магазина.

Для завершения транзакции мерчант отправляет в платежный шлюз запрос finish3dsVer2Payment.do, передавая параметр threeDSServerTransId - идентификатор транзакции, который был создан сервером 3DS и возвращён на шаге 6.

Пример запроса:

curl --request POST \
--url https://abby.rbsuat.com/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
--data userName=test_user \
--data password=test_user_password \

Пример ответа:

{
"redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
"errorCode": 0,
"is3DSVer2": true
}

Платежный шлюз асинхронно отправляет уведомление обратного вызова на сервер интернет-магазина.
Интернет-магазин отправляет запрос getOrderStatusExtended.do платежному шлюзу, чтобы проверить статус заказа и убедиться, что заказ действительно оплачен. Запрос содержит параметр orderId, полученный на Шагe 5. В ответ платежный шлюз возвращает статус заказа в параметре orderStatus. Статус 2 означает успешный платеж, статус 1 означает успешную предварительную авторизацию для двухэтапных платежей (в этом случае производится холдирование средств). Дополнительно возвращается параметр actionCode - он содержит код ответа процессинга банка. См. список кодов ответа здесь.

Дополнительные сведения см. в разделе Получение статуса заказа.

Дополнительные шаги при получении soft decline после frictionless аутентификации

У вас может быть включена специальная настройка выполнения повторного 3DS 2 challenge при получении soft decline после frictionless аутентификации. "Soft decline" - это специальный код ответа, который процессинговый центр банка может получить от ACS и отправить в Платежный шлюз. Он означает, что для транзакции требуется более высокий уровень аутентификации.

Если эта настройка включена (обратитесь в команду поддержки, чтобы это выяснить) и Платежный шлюз получил код "soft decline" от процессингового центра банка после frictionless аутентификации, вам все же необходимо пройти полную (full) 3DS 2 аутентификацию. Таким образом, необходимо выполнить следующие дополнительные шаги:

Мерчант в отдельном iframe методом POST вызывает threeDSMethodURLServer, используя значение, полученное из ответа на запрос оплаты заказа. Это позволяет серверу 3DS собрать данные о браузере клиента.
(Необязательный шаг) Если в ответе на запрос оплаты заказа пришли параметры threeDSMethodURL и threeDSMethodDataPacked, то мерчант в отдельном iframe методом POST вызывает threeDSMethodURL. В этом методе необходимо передать значение, полученное из параметра threeDSMethodDataPacked, полученного в ответе на запрос оплаты заказа. При этом нужно его передать в параметре, который называется threeDSMethodData. Это позволяет ACS собрать данные о браузере клиента.
Оплата заказа - этап 2a. Мерчант повторно отправляет запрос на оплату, передавая новый параметр threeDSServerTransId. В ответе возвращается acsUrl – URL-адрес для перенаправления на ACS и новый packedCReq – упакованные данные для challenge request. Платежная страница перенаправляется на acsUrl с параметром creq=packedCReq, и клиент выполняет challenge (переход на шаг 11 основной схемы интеграции).