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

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

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

Для оплаты можно передать в Платежный сервис Роутер данные карты, зашифрованный токен или идентификатор связки.

Существует два пути интеграции:

Два запроса — один для регистрации, другой для оплаты заказа. В этом случае можно будет сделать повторные попытки оплаты заказа в случае неудачи. Например, клиент сможет выбрать другой способ оплаты или другую карту/связку.
Один запрос — регистрация и оплата одним запросом. В этом случае повторные попытки оплаты одного и того же заказа (с одним orderNumber) не поддерживаются.

Схема интеграции с двумя запросами

Регистрация заказа

1. Клиент выбрал товар (корзина сформирована, все дополнительные подтверждения на стороне Партнера пройдены).

2. Партнер направляет в Платежный сервис Роутер запрос регистрации заказа: register.do для одностадийной оплаты или registerPreAuth.do для двухстадийной оплаты. Подробнее об этих видах оплаты см. в разделе Двухстадийные платежи.

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

curl --request POST \
'https://api.router.rbsuat.com/v1/register.do' \
-H 'Content-Type: application/json' \
--data-raw \
'{
    "orderNumber": "order_123473",
    "amount": 1234,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "userName": "test_user",
    "password": "test_user_password",
    "clientId":"client_10001"
}'

3. Платежный сервис Роутер проводит проверку входных данных и осуществляет регистрацию заказа.

4. Платежный сервис Роутер возвращает Партнеру номер зарегистрированного заказа orderId.

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

{
    "errorCode": "0",
    "formUrl": "https://router.rbsuat.com/wl/payment.html?mdOrder=2dc811e7-8d1c-407a-bd25-a4f41f96cc60&language=en",
    "orderId": "2dc811e7-8d1c-407a-bd25-a4f41f96cc60",
    "orderNumber": "order_123457"
}

(Опционально) Получение связок

5-6. (Опционально) Партнер запрашивает в Платежном сервисе связки методом getBindings.do. Платежный сервис Роутер запрашивает связки во всех банках и возвращает их Партнеру.

Эти шаги выполняются в случае, если Партнер использует связки, и связки хранятся на стороне банка. Если Партнер хранит связки на своей стороне, то эти шаги нужно пропустить. Подробнее о связках, способах их хранения, связанных с этим ограничениях, особенностях создания и оплаты заказов см. на странице Связки

Сбор и отправка карточных данных

7. Партнер направляет клиента на страницу ввода карточных данных.

8. Клиент указывает данные карты или выбирает связку (если Партнер использует связки, см. шаги 5-6).

9. Если на предыдущем шаге выбрана связка, переход на шаг 10. Если Клиент указал данные карты, Партнер может сгенерировать seToken, как описано в разделе Генерация seToken.

10. Партнер направляет в Платежный сервис Роутер запрос оплаты заказа:

При оплате картой paymentOrder.do. Передается либо зашифрованный seToken, либо данные карты.
При оплате связкой, хранящейся на стороне банка, paymentOrderBinding.do. Передается идентификатор связки.

Пример запроса с использованием seToken:

curl --request POST --url 'https://api.router.rbsuat.com/v1/paymentOrder.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password",
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "seToken": "RJ7Pzbt...",
    "mdOrder": "2dc811e7-8d1c-407a-bd25-a4f41f96cc60"
}'

Пример запроса с использованием данных карты:

curl --request POST --url 'https://api.router.rbsuat.com/v1/paymentOrder.do' 
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password_",
    "mdOrder": "f44a15a2-765e-44b7-a223-489ee61359c1",
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "month": "12",
    "pan": "4343821200124342",
    "year": "2024"
}'

11. (Опционально) Платежный сервис Роутер расшифровывает SeToken своим приватным ключом.

12. На основе карточных данных Платежный сервис Роутер осуществляет выбор банка согласно правилам.

13-16 Платежный сервис Роутер направляет в Банк запрос на регистрацию, а затем оплату заказа. Банк возвращает результаты регистрации и оплаты (на схеме — необходимо пройти 3DS).

Ответ на запрос оплаты

17. Платежный сервис Роутер направляет Партнеру ответ на запрос оплаты. В случае оплаты без 3DS в ответе присутствует ссылка для перенаправления клиента: failUrl или returnUrl из запроса регистрации заказа, и Шаги 18-22 пропускаются. В противном случае далее нужно выполнить Шаги 18-22 для прохождения 3DS.

Всего может быть три варианта ответа:

Пример ответа без 3DS (параметр is3DSVer2 == false, код ошибки 0, нет acsUrl и paReq, статус транзакции финальный):

{
    "errorCode": 0,
    "info": "Ваш платёж обработан, происходит переадресация...",
    "is3DSVer2": false,
    "mdOrder": "2dc811e7-8d1c-407a-bd25-a4f41f96cc60",
    "redirect": "https://mybestmerchantreturnurl.com/success?orderId=2dc811e7-8d1c-407a-bd25-a4f41f96cc60&lang=ru",
    "transactionState": "DEPOSITED"
}

Пример ответа с 3DSv1 (параметр is3DSVer2 == false, в наличии acsUrl и paReq, статус транзакции начальный):

{
    "acsUrl": "https://api.router.rbsuat.com/v1/start3DSv1.do",
    "errorCode": 0,
    "info": "Ваш платёж обработан, происходит переадресация...",
    "is3DSVer2": false,
    "mdOrder": "81cc3e27-b313-46a1-8d5d-9836ff713050",
    "paReq": "eJxVUtty...",
    "termUrl": "https://api.router.rbsuat.com/v1/finish3DSv1.do",
    "transactionState": "CREATED"
}

Пример ответа с 3DSv2 (параметр is3DSVer2 == true):

{
    "errorCode": 0,
    "is3DSVer2": true,
    "mdOrder": "ab39552e-f9cf-4fa4-9af7-b4266efd85f4",
    "threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0=",
    "threeDSMethodURL": "https://web.rbsuat.com/acs2/acs/3dsMethod",
    "threeDSMethodURLServer": "https://web.rbsuat.com/3dsserver/api/v1/client/gather?threeDSServerTransID=03c0287a-f08f-4820-aa9e-2f985323588a",
    "threeDSServerTransId": "03c0287a-f08f-4820-aa9e-2f985323588a"
}

Прохождение 3DS

3DS не требуется

Если ответ на запрос оплаты свидетельствует о том, что 3DS не требуется, нужно перейти к Шагу 23 для запроса и отображения финального статуса заказа.

3DS v1

18. Партнер осуществляет взаимодействие с Клиентом для прохождения 3DS. См. Редирект на ACS.

19. Партнер направляет в Платежный сервис Роутер запрос завершения 3DS finish3dsPayment.do.

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

curl --request POST --url 'https://api.router.rbsuat.com/v1/finish3dsPayment.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mdOrder": "ee70f9a2-cb36-4961-a13b-b3dc24a44649",
    "paRes": "eJydVtuSoN...",
    "userName": "test_user",
    "password": "test_user_password"
}'

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

{
    "errorCode": 0
}

20-22 Платежный сервис Роутер получает от Банка и возвращает Партнеру ответ на запрос завершения 3DS.

3DS v2

18. Партнер осуществляет взаимодействие с Клиентом для прохождения 3DS v2:

18.1. Если в ответе за первый запрос оплаты был параметр threeDSMethodURLServer, то Партнер в отдельном фрейме должен выполнить вызов этого URL методом POST. Это позволяет серверу 3DS собрать данные о браузере клиента.

Пример кода:

<html>
<head><title>3DS Method</title></head>
<body>
    <script>
        // Замените на реальный URL, полученный из ответа на запрос оплаты
        const threeDSMethodURLServer = 'https://example.com';

        const iframe = document.createElement('iframe');
        iframe.style.cssText = 'width: 0; height: 0; border: none;';

        const html = `
            <form
                id="threeDsMethodTo3DSServer"
                method="post"
                action="${threeDSMethodURLServer}">
            </form>
        `;

        document.body.append(iframe);

        if (iframe.contentWindow) {
            iframe.contentWindow.document.open();
            iframe.contentWindow.document.write(html);
            (iframe.contentWindow.document.forms['threeDsMethodTo3DSServer']).submit();
        }
    </script>
</body>
</html>

Ожидаемый ответ — HTTP 200 без тела.

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

Пример кода:

<html>
<head><title>3DS Method to ACS</title></head>
<body>
    <script>
        // Замените на реальные значения, полученные из ответа на запрос оплаты
        const threeDSMethodURL = 'https://example.com';
        const threeDSMethodDataPacked = 'your_data';

        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}">
            </form>
        `;

        document.body.append(iframe);

        if (iframe.contentWindow) {
            iframe.contentWindow.document.open();
            iframe.contentWindow.document.write(html);
            (iframe.contentWindow.document.forms['threeDsMethodToACS']).submit();
        }
    </script>
</body>
</html>

Ожидаемый ответ — HTTP 200 без тела.

18.3. Партнер повторно выполняет запрос оплаты (в сценарии оплаты картой двумя запросами — paymentOrder.do, в других сценариях запрос может быть другим) с теми же самыми данными, но добавив еще один параметр threeDSServerTransId из ответа на первый запрос. Минимальная задержка перед отправкой второго запроса составляет 10 секунд после первого запроса оплаты. Это время необходимо для того, чтобы вызовы в пунктах 16.1 и 16.2 успели выполниться на серверах 3DS и ACS. Таким образом, все необходимые данные для ответа на повторный запрос оплаты будут готовы к моменту его выполнения.

Если в ответе на первый запрос нет ни threeDSMethodURLServer, ни threeDSMethodURL, ни threeDSMethodDataPacked, но есть acsUrl (используется full 3DS2), то этот шаг пропускается и можно переходить сразу к Шагу 16.4.

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

curl --request POST --url 'https://api.router.rbsuat.com/v1/paymentOrder.do' 
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password_",
    "mdOrder": "f44a15a2-765e-44b7-a223-489ee61359c1",
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "month": "12",
    "pan": "4343821200124342",
    "year": "2024",
    "threeDSServerTransId":"c9f26542-6b31-4b1e-b9e6-019d4339a75f"
}'

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

{
    "acsUrl": "https://web.rbsuat.com/acs2/acs/creq",
    "errorCode": 0,
    "info": "Ваш платёж обработан, происходит переадресация...",
    "is3DSVer2": true,
    "mdOrder": "f44a15a2-765e-44b7-a223-489ee61359c1",
    "packedCReq": "eyJ0a...",
    "threeDSServerTransId": "7bba6753-7ff3-4241-ab58-f152f1399d65",
    "transactionState": "CREATED"
}

18.4. Если в ответе есть acsUrl, выполняется редирект на ACS.

19. Партнер направляет в Платежный сервис Роутер запрос завершения 3DS v2 finish3dsVer2Payment.do.

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

curl --request POST --url 'https://api.router.rbsuat.com/v1/finish3dsVer2Payment.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mdOrder": "c5775866-6750-4428-ab07-52df52daa523",
    "threeDSServerTransId": "da5ac269-4faf-4f80-8645-0b73db313b66",
    "userName": "test_user",
    "password": "test_user_password"
}'

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

{
    "errorCode": 0
}

20-22 Платежный сервис Роутер получает от Банка и возвращает Партнеру ответ на запрос завершения 3DS v2.

Отображение финального статуса заказа

23. Партнер отправляет в Платежный сервис Роутер запрос статуса операции getOrderStatusExtended.do.

24-27 Платежный сервис Роутер получает от Банка и передает Партнеру статус заказа для показа Клиенту.

Схема интеграции с одним запросом

Запрос регистрации и оплаты

1. Клиент инициирует оплату заказа.

2-3. (Опционально) Партнер запрашивает в Платежном сервисе связки методом getBindings.do. Платежный сервис Роутер запрашивает связки во всех банках и возвращает их Партнеру. Эти шаги выполняются в случае, если связки хранятся на стороне банка. Если Партнер хранит связки на своей стороне, то эти шаги нужно пропустить. Подробнее о связках, способах их хранения, связанных с этим ограничениях, особенностях создания и оплаты заказов см. на странице Связки

4. Партнер отображает Клиенту страницу оплаты, где Клиент может выбрать связку или ввести данные карты.

5. Клиент передает данные для оплаты.

6. Если Клиент на предыдущем шаге выбрал связку, переход к шагу 5. Если Клиент ввел данные карты, Партнер может зашифровать их в токен для оплаты. Порядок формирования токена см. здесь: Генерация seToken.

7. Партнер отправляет в Платежный сервис Роутер запрос instantPayment.do.

В этом запросе можно передать один из следующих способов оплаты:

данные карты;
зашифрованный токен;
идентификатор связки bindingId, если связки хранятся на стороне банка.

Чтобы указать тип оплаты, используется параметр preAuth: значение false означает одностадийную оплату (как если бы заказ регистрировался запросом register.do), а значение true — двухстадийную (как при регистрации registerPreAuth.do). Подробнее об этих видах оплаты см. в разделе Двухстадийные платежи.

Пример запроса с данными карты:

curl --location 'https://api.router.rbstest.ru/v1/instantPayment.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderNumber": "order_123566",
    "amount": 153700,
    "backUrl": "https://mybestmerchantreturnurl.com",
    "cardholderName": "TEST CARDHOLDER",
    "clientId": "259753456",
    "cvc": "123",
    "expiry": "203412",
    "pan": "4276550099363189",
    "language": "ru",
    "preAuth": false,
    "password": "test_user",
    "userName": "test_user_password",
}'

8-13. Платежный сервис выполняет регистрацию и маршрутизацию заказа, а затем возвращает Партнеру результат оплаты (на схеме — необходимо пройти 3DS). Возможны следующие варианты ответа:

Платеж выполнен (как правило, после прохождения 3DS). В ответе возвращается статус заказа. Пример ответа см. на странице Статус оплаты.
Требуется 3DS — запрос содержит параметр is3DSVer2 == true, либо is3DSVer2 == false вместе с acsUrl и paReq. Пример ответа см. выше в разделе Ответ на запрос оплаты.

Прохождение 3DS

14. Если требуется 3DS, то Партнер должен выполнить шаги для прохождения 3DS.

Важно отметить, что при прохождении 3DS v2 повторный запрос оплаты — также instantPayment.do с теми же параметрами, что на шаге 5, и с добавлением threeDSServerTransId из ответа на первый запрос. В остальном процесс прохождения 3DS полностью аналогичен сценарию с двумя запросами.

Отображение финального статуса заказа

15. Партнер отправляет в Платежный сервис Роутер запрос статуса операции getOrderStatusExtended.do.

16-19. Платежный сервис Роутер получает от Банка и передает Партнеру статус заказа для показа Клиенту.

Редирект на ACS

3DS v1

Если оплата производится с помощью 3-D Secure ver.1, партнер должен перенаправлять своих клиентов в ACS по адресу, указанному в параметре acsUrl, полученном в ответе на запрос оплаты. Тело запроса должно включать MD=mdorder&PaReq=paReq&TermUrl=termUrl, где:

MD - уникальный идентификатор заказа в платежном шлюзе;
PaReq - параметр paReq, полученный в ответе на запрос оплаты. Это сообщение, которое должно быть отправлено в ACS вместе с редиректом и содержит данные, необходимые для аутентификации;
TermUrl - параметр termUrl, полученный в ответе на запрос оплаты. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации.

Это должен быть запрос POST (не GET).

Пример страницы для отправки POST-запроса:

<head>
    <title>Payment confirmation</title>
</head>
<body>
    <h1>Payment confirmation</h1>
    <form name="form1" id="form1" action="" method="POST">
        acsUrl: <input name="acsUrl" id="acsUrl" /> <br><br>
        MD: <input name="MD" /> <br><br>
        PaReq: <input  name="PaReq" /> <br><br>
        TermUrl: <input  name="TermUrl" /> <br><br>
        <input type="button"  value="Send data to ACS" onClick="
            var form = document.getElementById('form1'); 
            form.action = document.getElementById('acsUrl').value; 
            alert('Posting data to ' + form.action);    
            form.submit() 
        "/>
    </form>
</body>
</html>

Сохраните этот код в файл html на своем компьютере и откройте в браузере. Введите в форму данные из ответа на paymentOrder.do и нажмите на кнопку.

PaRes для завершения оплаты 3DS можно посмотреть в теле вызова finish3DSv1.do в Dev Tools (F12 в Chrome).

3DS v2

Если оплата производится с помощью 3-D Secure ver.2, партнер должен перенаправлять своих клиентов в ACS по адресу, указанному в параметре acsUrl, полученном в ответе на запрос оплаты. Тело запроса должно включать creq, в котором передается значение параметра packedCReq.

Это должен быть запрос POST (не GET).

Пример страницы для отправки POST-запроса:

<html>
<head><title>ACS Redirect</title></head>
<body onload="document.forms['acs'].submit()">
ACS Redirect
<form id="acs" method="post" action="[acsUrl]">
    <input type="hidden" id="creq" name="creq" value="[packedCReq]"/></form>
</body>
</html>