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

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

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

Если вы собираете данные карты на своей стороне и не хотите, чтобы они присутствовали на вашем сервере, вам следует использовать seToken (Self Encrypted Token) — самоподписанный токен, используемый для безопасной передачи данных карты. Если вы используете seToken, соответствие PCI DSS не требуется.

Обратите внимание, что seToken может быть сгенерирован с помощью SDK.

Нажмите здесь, чтобы получить дополнительную информацию о seToken.

Если у вас нет доступа к Панели управления, создайте свою учетную запись.

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

Прямая интеграция

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

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

Оплата. Затем интернет-магазин передает данные карты для оплаты заказа, отправляя API-вызов paymentorder.do платежному шлюзу. Этот запрос содержит параметр MDORDER — уникальный номер заказа в системе платежного шлюза, возвращаемый в ответе на register.do.

Пример запроса оплаты заказа:
```
curl --request POST \
--url https://vtb.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=en
```
Пример ответа на запрос оплаты заказа:
```
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://web.payuat.com/acs/auth/start.do",
"paReq": "eJxVUtFu4jAQ/BWU92DHcSCpFle946ryAEd7FKl9OZl4gbSNA05ypP36s0NSWsmSd8br3fGO4brJ3wb/0JRZoSdeMKTeAHVaqEzvJt7j6taPvWsBq71BnP7BtDYoYI5lKXc4yNTEG48kj5KN8jfxOPH5NqZ+kiTURxYlSEMaxtvUE7C8ecCjgK6RsH2GDEgPbUWT7qWuBMj0+GO2EJyNR5QC6SDkaGZTEfGQhRzIGYGWOYpSarUpmr95VwJIS0Na1Loy72LEQyA9gNq8iX1VHa4IqbCshmmRA3EkkIuGZe2i0hZpMiUWH/en39NZs3j5xearHZ+vnk6LD7tPnyZAXAYoWaFglAWUB8mAjq/simIgLQ8yd93tefugM4CD63Hz9eQrA3bQxvrQy+8RYHMoNLo7QD5jeHDGCNgaPNZtXgTkAgC1OmdYiZwGNLB3ewpIv19e/fPO+ZBWdsYvxamWr6rcnNaqWMuQrbF+zqLlXbQ7OHfaJKcqs9NlPDjLcgCIK0M640n3Z2z07S/9Bypv08k=",
"termUrl": "https://vtb.rbsuat.com/payment/rest/finish3ds.do?lang=en"
}
```
Если у вас включена настройка, разрешающая отправку данных браузера клиента (уточните у команды технической поддержки), вы можете отправить в запросе на оплату блок clientBrowserInfo. Мы рекомендуем это сделать, чтобы авторизация прошла без проблем.
См подробное описание блока clientBrowserInfo.
Если требуется 3-D Secure (параметр acsUrl возвращается на Шаг 5), платежный шлюз связывается с Directory Server, чтобы получить доступ к ACS. Он возвращает все данные, необходимые для перенаправления из ACS в интернет-магазин.

Если 3-D Secure не используется, Шаги 7–9 пропускаются, а клиент перенаправляется на страницу подтверждения платежа (Шаг 10). Параметр redirect в этом случае игнорируется, так как интернет-магазин использует собственную страницу подтверждения оплаты.
Сервер интернет-магазина запрашивает упрощенную переадресацию покупателя в ACS, отправляя вызов API acsRedirect.do платежному шлюзу. В запросе используется параметр orderId (полученный на Шагe 5).

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

https://vtb.rbsuat.com/payment/acsRedirect.do?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0

Также возможно перенаправление клиента на ACS с помощью POST-запроса (обычный редирект). Описание этого способа доступно здесь.
Платежный шлюз перенаправляет клиента в ACS.
Держатель карты подтверждает заказ и ACS перенаправляет его в платежный шлюз.
Покупатель возвращается на страницу интернет-магазина (по адресу, указанному при оформлении заказа на Шаге 5) или закрывает страницу.

Пример URL-редиректа:

https://mybestmerchantreturnurl.com/?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0&lang=en
Платежный шлюз асинхронно отправляет уведомление обратного вызова на сервер интернет-магазина (если эта возможность включена).
(Необязательно) Интернет-магазин отправляет запрос getOrderStatusExtended.do платежному шлюзу, чтобы проверить статус заказа и убедиться, что заказ действительно оплачен. Запрос содержит параметр orderId, полученный на Шагe 5. В ответ платежный шлюз возвращает статус заказа в параметре orderStatus. Статус 2 означает успешный платеж, статус 1 означает успешную предварительную авторизацию для двухэтапных платежей (в этом случае производится холдирование средств). Дополнительно возвращается параметр actionCode - он содержит код ответа процессинга банка. См. список кодов ответа здесь.

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

Прямые платежи (расширенная схема с 3DS2)

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

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

Если вы используете платежную страницу на вашей стороне и хотите использовать аутентификацию клиента по протоколу 3DS2, для каждой транзакции вам необходимо отправить в платёжный шлюз следующую последовательность запросов:

запрос оплаты, который инициирует аутентификацию по протоколу 3DS2,
запросы 3DS-методов threeDSMethodURLServer и (опционально) threeDSMethodURL, которые передают на 3DS сервер и ACS данные о браузере, в отдельном "iframe",
запрос continue.do для продолжения оплаты и получения данных для прохождения challenge на ACS,
если клиент после аутентификации перенаправляется на страницу магазина, необходимо завершить платёж, отправив запрос finish3dsVer2Payment.do.

Детальное описание всех шагов смотрите в схеме интеграции.

Обратите внимание, что seToken может быть сгенерирован с помощью SDK.

Нажмите здесь, чтобы получить дополнительную информацию о seToken.

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

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

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

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

Если у вас нет доступа к Панели управления, создайте свою учетную запись.

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

Direct integration

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

Пример запроса на регистрацию заказа:
```
curl --request POST \
--url https://vtb.rbsuat.com/payment/rest/register.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=2000 \
--data currency=643 \
--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://vtb.rbsuat.com/payment/merchants/pay/payment_en.html?mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0"
}
```
Также вы можете удерживать сумму на счете до списания средств с помощью вызова registerPreAuth.do. Чтобы узнать больше о холдировании и завершении, нажмите здесь.
Начало оплаты. Мерчант передает карточные данные путем отправки API запроса paymentorder.do в платежный шлюз (для оплаты также можно использовать другой платежный запрос, например, paymentOrderBinding.do). Запрос должен содержать параметр MDORDER - уникальный номер заказа в системе платежного шлюза, возвращенный в ответе на запрос register.do.

Платёжный шлюз проверяет на сервере 3DS возможность проведения аутентификации клиента по протоколу 3DSv2 и отправляет ответ. Если требуется 3DSv2 аутентификация, в ответе, в том числе, возвращаются следующие параметры, относящиеся к 3DSv2:
- threeDSServerTransId - идентификатор транзакции, присвоенный сервером 3DS
- threeDSMethodURLServer - адрес сервера 3DS для сбора данных о браузере
- threeDSMethodURL - (опционально) адрес сервера ACS для сбора данных о браузере
- threeDSMethodDataPacked - (опционально) данные для сбора данных о браузере на ACS
Если параметры, относящиеся к 3DSv2, отсутствуют в ответе, шаги 7-9 пропускаются.

Пример запроса оплаты заказа:
```
curl --request POST \
--url https://vtb.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": "c300fd79-5e7d-4882-89c7-43458e2538b6",
"threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
"threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=c300fd79-5e7d-4882-89c7-43458e2538b6",
"threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9jb21tb24wMy50c3QucmJzdGVzdC5ydS8zZHNzZXJ2ZXIvYXBpL3YxL2Fjcy9ub3RpZmljYXRpb24_dGhyZWVEU1NlcnZlclRyYW5zSUQ9NTgwMjc0NmUtMzM5My00MGMzLTkyOWEtZGM5NjZlYmYwOGM2IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1ODAyNzQ2ZS0zMzkzLTQwYzMtOTI5YS1kYzk2NmViZjA4YzYifQ"
}
```
Если у вас включена специальная настройка, позволяющая отправлять данные браузера клиента (уточните это у команды поддержки), вы можете отправить в первом запросе на оплату блок clientBrowserInfo. См. подробное описание блока clientBrowserInfo.
Следующие шаги могут зависеть от параметров, полученных на шаге 6, следующим образом:
- Если ответ не содержит threeDSMethodURLServer (это возможно, только если вы передали блок clientBrowserInfo в запросе оплаты), шаг 7 пропускается.
- Если ответ не содержит параметров threeDSMethodURL и threeDSMethodDataPacked, шаг 8 пропускается.
- Если ответ не содержит ни threeDSMethodURLServer, ни threeDSMethodURL и threeDSMethodDataPacked, но содержит acsUrl (используется full 3DS2), выполняется переход на шаг 10 и перенаправление на ACS.
- Если ответ не содержит ни threeDSMethodURLServer, ни threeDSMethodURL и threeDSMethodDataPacked, а также не содержит acsUrl (frictionless аутентификация), выполняется переход на шаг 13.

(Выполняется при условии) 3DS-method. Мерчант в отдельном "iframe" методом POST вызывает threeDSMethodURLServer, используя значение, полученное из ответа на запрос оплаты заказа. Это позволяет серверу 3DS собрать данные о браузере клиента.

Пример кода:

const iframe = document.createElement('iframe');
  iframe.style.cssText = 'width: 0; height: 0; border: none;';
 const html = `
   <form
     id="threeDsMethodTo3DSServer"
     method="post"
     action="${threeDSMethodURLServer as string}"></form>
 `;
 document.body.append(iframe);
 if (iframe.contentWindow) {
   iframe.contentWindow.document.open();
   iframe.contentWindow.document.write(html);
   (iframe.contentWindow.document.forms['threeDsMethodTo3DSServer'] as HTMLFormElement).submit();
 }

(Выполняется при условии) 3DS-method. Если в ответе на запрос оплаты заказа пришли параметры threeDSMethodURL и threeDSMethodDataPacked, то мерчант в отдельном "iframe" методом POST вызывает threeDSMethodURL. В этом методе необходимо передать значение, полученное из параметра threeDSMethodDataPacked, полученного в ответе на запрос оплаты заказа. При этом нужно его передать в параметре, который называется threeDSMethodData. Это позволяет ACS собрать данные о браузере клиента.

Пример кода:
```
const iframe = document.createElement('iframe');
 iframe.style.cssText = 'width: 0; height: 0; border: none;';
 const html = `
   <form id="threeDsMethodToACS"
     method="post"
     action="${threeDSMethodURL}"
   >
     <input type="hidden" name="threeDSMethodData" value="${threeDSMethodDataPacked as string}"/>
   </form>
 `;
 document.body.append(iframe);
 if (iframe.contentWindow) {
   iframe.contentWindow.document.open();
   iframe.contentWindow.document.write(html);
   (iframe.contentWindow.document.forms['threeDsMethodToACS'] as HTMLFormElement).submit();
 }
```
Продолжение оплаты. Мерчант отправляет запрос continue.do, чтобы завершить оплату заказа (или осуществить перевод денежных средств). Запрос должен содержать mdOrder - номер заказа в платежном шлюзе.

Пример запроса:
```
curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/3ds/continue.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0 \
  --data userName=test-user \
  --data password=test-password
```
Платежный шлюз взаимодействует с 3DS сервером и ACS, чтобы выяснить, требуется ли клиенту проходить аутентификацию на ACS, и отправляет ответ на запрос оплаты. Если клиенту требуется проходить аутентификацию на ACS, в ответе возвращается acsUrl – URL для перенаправления на ACS, а также packedCReq – упакованные данные для challenge request. Если не требуется (frictionless аутентификация) – возвращается ответ об успешном завершении оплаты.

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

Если клиенту требуется проходить аутентификацию на ACS, продавец перенаправляет клиента на ACS. Читайте, как это сделать здесь.
Клиент проходит проверку подлинности и ACS перенаправляет его на страницу магазина.
Если в запросе на оплату был передан параметр threeDSVer2FinishUrl, для завершения транзакции мерчант отправляет в платежный шлюз запрос finish3dsVer2Payment.do. В этом запросе нужно передать параметр threeDSServerTransId - идентификатор транзакции, который был создан сервером 3DS и возвращён на шаге 6.

Пример запроса:
```
curl --request POST \
--url https://vtb.rbsuat.com/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=c300fd79-5e7d-4882-89c7-43458e2538b6 \
--data userName=test_user \
--data password=test_user_password \
```
Пример ответа:
```
{
"redirect": "http://test.com?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0&lang=en",
"errorCode": 0,
"is3DSVer2": true
}
```
Платежный шлюз асинхронно отправляет уведомление обратного вызова на сервер интернет-магазина (если эта возможность включена).
(Необязательно) Интернет-магазин отправляет запрос getOrderStatusExtended.do платежному шлюзу, чтобы проверить статус заказа и убедиться, что заказ действительно оплачен. Запрос содержит параметр orderId, полученный на Шагe 5. В ответ платежный шлюз возвращает статус заказа в параметре orderStatus. Статус 2 означает успешный платеж, статус 1 означает успешную предварительную авторизацию для двухэтапных платежей (в этом случае производится холдирование средств). Дополнительно возвращается параметр actionCode - он содержит код ответа процессинга банка. См. список кодов ответа здесь.

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

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

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

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

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