API платёжного шлюза интернет-эквайринга Help

3DS v.2.x

Порядок запросов

  1. Создание заказа

  2. Установка карты

  3. 3DS Method

  4. AReq

  5. CReq

  6. CRes

Создание заказа

Запрос

{ "order": { "typeRid": "Purchase", "amount": 100.00, "currency": "RUB", "title": "Название заказа", "description": "Описание заказа", "hppRedirectUrl":"https://pgtest.bspb.ru/result" } }

Основные параметры запроса на создание заказа

Ответ

Основные параметры ответа на запрос создания заказа

Установка карты

Запрос

{ "token": { "card": { "panBlock": { "data": "220033*********7707" }, "expiration": "1226", "entryMode": "ECommerce" } } }

Ответ

{ "order": { "status": "Preparing", "cvv2AuthStatus": "Required", "tdsV1AuthStatus": "NotSupportedIss", "tdsV2AuthStatus": "Required", "otpAutStatus": "IneligibleOrder", "srcToken": { "id": 3600, "paymentMethod": "Card", "role": "Src", "status": "Active", "regTime": "2023-12-19 15:02:15", "displayName": "220033*********7707", "card": { "expiration": "1226", "brand": "Mir" } } }, "tdsData": { "aReq": { "threeDSServerTransID": "be6e2b83-72d6-4807-a2d9-87965494a1de", "messageType": "AReq", "messageVersion": "2.1.0", "threeDSCompInd": "Y", "threeDSRequestorAuthenticationInd": "01", "threeDSRequestorID": "2200330101VEND_RID_12964", "threeDSRequestorName": "2200330101TT00001", "threeDSRequestorURL": "https://pgtest.bspb.ru", "threeDSServerOperatorID": "OperIdDS", "threeDSServerRefNumber": "DSRefNum", "threeDSServerURL": "https://pgtest.bspb.ru/three-ds-server-url", "acquirerBIN": "1234", "acquirerMerchantID": "VEND_RID_12964", "cardExpiryDate": "2612", "deviceChannel": "02", "mcc": "8062", "merchantCountryCode": "643", "merchantName": "TT00001", "messageCategory": "01", "purchaseAmount": "10000", "purchaseCurrency": "643", "purchaseExponent": "2", "purchaseDate": "20231219120208" }, "methodUrl": "https://acstest.bspb.ru/3ds2/tx/device-information" } }

3DS Method

Создайте JSON-объект, содержащий threeDSServerTransID, полученный в ответе, и URL-адрес, на который ACS отправит уведомление по завершении взаимодействия с браузером держателя карты в threeDSMethodNotificationURL:

{ "threeDSServerTransID": "be6e2b83-72d6-4807-a2d9-87965494a1de", "threeDSMethodNotificationURL": "Requestor callback URL" }

Порядок действий

  1. Инициируйте скрытый HTML-фрейм в браузере держателя карты

  2. Создайте форму с полем ввода с именем threeDSMethodData

  3. Поле содержит вышеуказанный закодированный Base64-URL

  4. Отправьте форму на threeDSMethodURL с HTML-фреймом в качестве цели

Пример

Добавьте iframe в браузер держателя карты, используя JavaScript:

let displayBox = document.getElementById('displayBox'); let iframe = document.createElement('iframe'); iframe.classList.add('hidden'); iframe.name = "threeDSMethodIframe"; displayBox.appendChild(iframe);

Создайте HTML-форму, которая содержит поле ввода:

<form class="" id="threeDSMethodForm"> <input type="hidden" name="threeDSMethodData" id="threeDSMethodData"/> </form>

Пример отправки данной формы:

// Создание объекта данных с необходимыми значениями let threeDSMethodData = { threeDSServerTransID: 'TRANS ID', threeDSMethodNotificationURL: 'URL' } // Получаем ссылку на форму let form = document.getElementById('threeDSMethodForm'); // 1. Сериализация объекта threeDSMethodData в JSON // 2. Base64-URL кодирует его // 3. Установка значения в input формы // Предупреждение: Значение Base64-URL не должно содержать '=' document.getElementById('threeDSMethodData').value = base64url(JSON.stringify(threeDSMethodData)); // Отправка формы form.action = '<threeDSMethodURL>'; form.target = 'threeDSMethodIframe'; // id of iframe form.method = 'post'; form.submit();

AReq

Полученный в ответе aReq необходимо дополнить следующими полями:

Поле

Значение

Свойство

notificationURL

URL, на который отправляется сообщение CRes. Отправляет ACS через браузер держателя карты по завершении аутентификации.

browserIP

IP-адрес, с которого подключается браузер держателя карты.

browserAcceptHeader

Точное содержимое HTTP принимает заголовки, отправленные в 3DS Requestor из браузера держателя карты.

browserJavaEnabled

Логическое значение, которое представляет собой способность браузера держателя карты выполнять Java, обязательно если browserJavascriptEnabled=true.

navigator.javaEnabled

browserColorDepth

Битовая глубина цветовой палитры браузера пользователя, обязательно, если browserJavascriptEnabled true.

screen.colorDepth

browserScreenWidth

Общая ширина экрана держателя карты в пикселях.

screen.width

browserScreenHeight

Общая высота экрана держателя карты в пикселях.

screen.height

browserTZ

Смещение часового пояса в минутах между UTC и местным временем браузера держателя карты.

browserUserAgent

Точное содержимое заголовка HTTP user-agent.

browserLanguage

Значение, представляющее язык браузера, как определено в IETF BCP47.

navigator.language

browserJavascriptEnabled

Логическое значение, которое представляет собой способность браузера держателя карты выполнять JavaScript.

Запрос

{ "aReq": { "threeDSServerTransID": "be6e2b83-72d6-4807-a2d9-87965494a1de", "messageType": "AReq", "messageVersion": "2.1.0", "threeDSCompInd": "Y", "threeDSRequestorAuthenticationInd": "01", "threeDSRequestorID": "2200330101VEND_RID_12964", "threeDSRequestorName": "2200330101TT00001", "threeDSRequestorURL": "https://pgtest.bspb.ru", "threeDSServerOperatorID": "OperIdDS", "threeDSServerRefNumber": "DSRefNum", "threeDSServerURL": "http://217.195.86.190:6868", "acquirerBIN": "1234", "acquirerMerchantID": "VEND_RID_12964", "cardExpiryDate": "2612", "deviceChannel": "02", "mcc": "8062", "merchantCountryCode": "643", "merchantName": "TT00001", "messageCategory": "01", "purchaseAmount": "10000", "purchaseCurrency": "643", "purchaseExponent": "2", "purchaseDate": "20231219120515", "notificationURL": "https://pgtest.bspb.ru/cres/processCRes", "browserIP": "127.0.0.1", "browserAcceptHeader": "any", "browserJavaEnabled": true, "browserJavascriptEnabled": true, "browserColorDepth": "32", "browserScreenWidth": "1000", "browserScreenHeight": "1000", "browserTZ": "-300", "browserUserAgent": "Test", "browserLanguage": "RU" } }

Ответ

{ "aRes": { "threeDSServerTransID": "be6e2b83-72d6-4807-a2d9-87965494a1de", "dsReferenceNumber": "DSRefNum", "dsTransID": "96061cb5-5c7a-4101-a248-8c75adbda0fd", "messageType": "ARes", "messageVersion": "2.1.0", "acsChallengeMandated": "N", "acsOperatorID": "ACS-V210-PJSC_BANK_SAINT_P-39939", "acsReferenceNumber": "3DS_LOA_ACS_COPL_020100_00081", "acsTransID": "28da38e3-987c-475f-b118-f2a37fae6f82", "acsURL": "https://acstest.bspb.ru/3ds2/tx/", "authenticationType": "01", "transStatus": "C" }, "challengeRequired": true, "cReq": "eyJhY3NUcmFuc0lEIjoiMjhkYTM4ZTM....", "order": { "tdsV2AuthStatus": "Required", "status": "Preparing" } }

CReq

Запрос необходим, чтобы убедиться, что истинный держатель карты является частью авторизации. Challenge flow используется для предоставления способа аутентификации держателя карты, например, с помощью OTP.

Добавьте iframe в браузер держателя карты либо статически, либо с помощью JavaScript:

let displayBox = document.getElementById('displayBox'); let iframe = document.createElement('iframe'); iframe.name = "challengeIframe"; displayBox.appendChild(iframe);

Добавьте форму, содержащую необходимые элементы:

<form class="" id="challengeForm"> <input type="hidden" name="creq" id="creq"/> <!-- Может содержать до 1024 символов в кодировке Base64-URL --> <input type="hidden" name="threeDSSessionData" id="threeDSSessionData"/> </form>

Заполните входные данные формы и отправьте их на URL-адрес ACS в iframe.

// Создание объекта данных с необходимыми значениями let creq = JSON.stringify({ threeDSServerTransID: "be6e2b83-72d6-4807-a2d9-87965494a1de", acsTransID: "28da38e3-987c-475f-b118-f2a37fae6f82", messageVersion: "2.1.0", messageType: "CReq", challengeWindowSize: "01" }); // Получаем ссылку на форму let form = document.getElementById('challengeForm'); // Установка значения в input формы // Предупреждение: Значение Base64-URL не должно содержать '=' document.getElementById('creq').value = base64url(creq); // Отправка формы form.action = '<acsURL>'; // acsURL из ARes form.target = 'challengeIframe'; form.method = 'post'; form.submit();

CRes

На указанный в соответствующем поле notificationURL методом POST отправляется ответ на запрос в Base64-URL:

cres=eyJhY3NUcmFuc0lEIjoiODc3OTFjZWUtMjUxNC00MzZjLWJlZDgtYTYzYTg3Y....

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

{ "acsTransID": "28da38e3-987c-475f-b118-f2a37fae6f82", "challengeCompletionInd": "Y", "messageType": "CRes", "messageVersion": "2.1.0", "threeDSServerTransID": "be6e2b83-72d6-4807-a2d9-87965494a1de", "transStatus": "Y" }
15 мая 2026