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

3DS v.2.x

Используется для оплат по картам MIR, UnionPay.

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

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

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

  3. 3DS Method

  4. AReq

  5. CReq

  6. CRes

  7. Исполнение транзакции

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

Запрос

{ "order": { "typeRid": "Purchase", "amount": 100.00, "currency": "RUB", "title": "3DS Only Название заказа", "description": "3DS Only Описание заказа", "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, полученный в ответе на запрос set-src-token и 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'; // name 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" }

Исполнение транзакции

Запрос

{ "tran": { "phase": "Single", "amount": 100, "authentication": { "cvv2Block": { "data": "052" } } } }

Ответ

{ "tran": { "approvalCode": "066035", "approvedPartial": false, "match": { "tranActionId": "231220-13574626-003yof=", "ridByPmo": "231220502664847998" } } }
Last modified: 10 апреля 2024