Режим SilentPay

Cкрытый режим платежа, при котором все данные о заказе, о покупателе, о способе оплаты и платежном средстве передаются непосредственно предприятием, может быть выполнен с использованием карты или токена.

Передача параметров платежа

Для работы в данном режиме предусмотрен web-сервис silentpay.

URL запроса для скрытого режима оплаты:

https://<SERVER-NAME>/pay/silentpay.cfm

Параметры передаются методом POST в теле запроса в формате «ключ=значение», SOAP запросом, либо в формате JSON (swagger описание: https://docs.assist.ru/swagger/). 

Список параметров, передаваемых в режиме silentpay:

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

<FORM ACTION="https://SERVER-NAME/pay/silentpay.cfm " method="POST">
<INPUT TYPE="hidden" NAME="Merchant_ID" VALUE="Ваш Merchant_ID">
<INPUT TYPE="hidden" NAME="Login" VALUE="Ваш логин">
<INPUT TYPE="hidden" NAME="Password" VALUE="Ваш пароль">
<INPUT TYPE="hidden" NAME="OrderNumber" VALUE="011001-10">
<INPUT TYPE="hidden" NAME="OrderAmount" VALUE="22">
<INPUT TYPE="hidden" NAME="OrderCurrency" VALUE="BYN">
<INPUT TYPE="hidden" NAME="OrderComment" VALUE="оплата заказа 011001-10">
<INPUT TYPE="hidden" NAME="Delay" VALUE="0">
<INPUT TYPE="hidden" NAME="isConvert" VALUE="1">
<INPUT TYPE="hidden" NAME="Language" VALUE="RU">
<INPUT TYPE="hidden" NAME="ClientIP" VALUE="IP адрес покупателя">
<INPUT TYPE="hidden" NAME="Cardtype" VALUE="Тип карты">
<INPUT TYPE="hidden" NAME="Cardnumber" VALUE="Номер карты">
<INPUT TYPE="hidden" NAME="Cardholder" VALUE="Владелец карты">
<INPUT TYPE="hidden" NAME="Expiremonth" VALUE="срок действия карты - месяц">
<INPUT TYPE="hidden" NAME="Expireyear" VALUE=" срок действия карты - год">
<INPUT TYPE="hidden" NAME="Cvc2" VALUE="код CVC2 или CVV2">
<INPUT TYPE="hidden" NAME="Lastname" VALUE="Фамилия покупателя">
<INPUT TYPE="hidden" NAME="Firstname" VALUE="Имя покупателя">
<INPUT TYPE="hidden" NAME="Middlename" VALUE="Отчество покупателя">
<INPUT TYPE="hidden" NAME="Email" VALUE="Email покупателя">
<INPUT TYPE="hidden" NAME="Address" VALUE="Адрес покупателя ">
<INPUT TYPE="hidden" NAME="Homephone" VALUE="Домашний телефон покупателя">
<INPUT TYPE="hidden" NAME="Workphone" VALUE="Рабочий телефон покупателя">
<INPUT TYPE="hidden" NAME="Mobilephone" VALUE="Мобильный телефон покупателя">
<INPUT TYPE="hidden" NAME="Fax" VALUE="Факс покупателя">
<INPUT TYPE="hidden" NAME="Country" VALUE="Стана">
<INPUT TYPE="hidden" NAME="State" VALUE="Регион">
<INPUT TYPE="hidden" NAME="City" VALUE="Город">
<INPUT TYPE="hidden" NAME="Zip" VALUE="Индекс отделения связи">
<INPUT TYPE="hidden" NAME="TestMode" VALUE="Тестовый режим">
<INPUT TYPE="hidden" NAME="Format" VALUE="Формат представления результата">
<INPUT TYPE="Submit"></FORM>

Описание веб-сервиса для формата SOAP:

https://<SERVER-NAME>/pay/silentpay.wsdl

Список возвращаемых параметров:

Результат запроса в зависимости от выбранного формата получения будет выглядеть одним из следующих образов.

В формате CSV:

Название поля:Значение поля Название поля:Значение поля.…Название поля:Значение поля

В формате XML:

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<!DOCTYPE result [
<result firstcode='Первый код' secondcode='Второй код' count='Кол-во объектов'>
<orders><order>
<ordernumber>Номер заказа</ordernumber>
<responsecode>Код возврата</response_code>
<recommendation>Рекомендации</recommendation>
<message>Сообщение</message>
<ordercomment>Комментарий</ordercomment>
<orderdate>Дата и время платежа</orderdate>
<amount>Сумма платежа</amount>
<currency>Код валюты</currency>
<meantypename>Тип карты</meantype>
<meannumber>Номер карты</meannumber>
<lastname>Фамилия</lastname>
<firstname>Имя</firstname>
<middlename>Отчество</middlename>
<issuebank>Название банк-эмитента</ issuebank >
<email>Адрес элекртонной  почты</email>
<bankcountry>Код страны банка-эмитента</bankcountry>
<rate>Курс валюты</rate>
<approvalcode>Код авторизации</approvalcode>
<meansubtype>Подтип карты</meansubtype>
<cardholder>Держатель карты</cardholder>
<cardexpirationdate>Срок действия карты</cardexpirationdate>
<ipaddress>IP-адрес покупателя</ipaddress>
<protocoltypename>Тип протокола</protocoltypename>
<testmode>Указание на тестовы платеж</ testmode >
<customermassage> Сообщение пользователю</customermassage >
<orderstate>Состояние</orderstate>
<processingname>Название процессинга</ processingname>
<operationtype>Код операции</operationtype>
<billnumber>Номер платежа</billnumber>
<orderamount>Сумма платежа  в оригинальной валюте</orderamount>
<ordercurrency>Оригинальная валюта </ordercurrency>
<paketdate> Дата и время получения пакета </paketdate>
<signature> </signature>
<pareq>Значение pareq </pareq>
<ascurl>URL банка-эмитента </ascurl>
</order></orders></result>

В формате SOAP:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
<soapenv:Header/>
<soapenv:Body>
<ws:SilentPayResponse>
<return> 
<ordernumber xsi:type="xsd:string">Номер заказа</ordernumber>
<responsecode xsi:type="xsd:string">Код возврата</response_code>
<recommendation xsi:type="xsd:string">Рекомендации</recommendation>
<message xsi:type="xsd:string">Сообщение</message>
<ordercomment xsi:type="xsd:string">Комментарий</ordercomment>
<orderdate xsi:type="xsd:string">Дата и время платежа</orderdate>
<amount xsi:type="xsd:string">Сумма платежа</amount>
<currency xsi:type="xsd:string">Код валюты</currency>
<meantypename xsi:type="xsd:string">Тип карты</meantype>
<meannumber xsi:type="xsd:string">Номер карты</meannumber>
<lastname xsi:type="xsd:string">Фамилия</lastname>
<firstname xsi:type="xsd:string">Имя</firstname>
<middlename xsi:type="xsd:string">Отчество</middlename>
<issuebank xsi:type="xsd:string">Название банк-эмитента</ issuebank >
<email xsi:type="xsd:string">Адрес элекртонной  почты</email>
<bankcountry xsi:type="xsd:string">Код страны банка-эмитента</bankcountry>
<rate xsi:type="xsd:string">Курс валюты</rate>
<approvalcode xsi:type="xsd:string">Код авторизации</approvalcode>
<meansubtype xsi:type="xsd:string">Подтип карты</meansubtype>
<cardholder xsi:type="xsd:string">Держатель карты</cardholder>
<cardexpirationdate xsi:type='xsd:string'>Срок действия карты</cardexpirationdate>
<ipaddress xsi:type="xsd:string">IP-адрес покупателя</ipaddress>
<protocoltypename xsi:type="xsd:string">Тип протокола</protocoltypename>
<testmode xsi:type="xsd:string">Указание на тестовый платеж</ testmode >
<customermassage xsi:type="xsd:string">Сообщение пользователю</customermassage >
<orderstate xsi:type="xsd:string">Состояние</orderstate>
<processingname xsi:type="xsd:string">Название процессинга</processingname>
<operationtype xsi:type="xsd:string">Код операции</operationtype>
<billnumber xsi:type="xsd:string">Номер платежа</billnumber>
<orderamount xsi:type="xsd:string">Сумма платежа  в оригинальной валюте</orderamount>
<ordercurrency xsi:type="xsd:string">Оригинальная валюта</ordercurrency>
<paketdate xsi:type="xsd:string">Дата и время получения пакета</paketdate>
<signature xsi:type="xsd:string"> </signature>
<pareq xsi:type="xsd:string">Значение pareq </pareq>
<ascurl xsi:type="xsd:string">URL банка-эмитента </ascurl>
</return>
</ws:SilentPayResponse>
</soapenv:Body>
</soapenv:Envelope>

В случае успешной оплаты код возврата responsecode принимает значение AS000.

В случае неуспешной оплаты responsecode принимает значения AS100-AS998 (кроме специального кода AS110, если необходима авторизация по 3-D Secure, подробнее см. здесь).

Если запрос на оплату не может быть обработан, в результате вернутся ненулевые значения параметров firstcode, secondcode.

Если в ответе получен responsecode AS300, а статусы заказа (orderstate) и операции (operationstate) - In Process (В процессе), то актуальный статус оплаты можно получить позже через запрос к сервису получения результатов orderresult.

Если результат оплаты не получен (например, вследствие сетевых проблем), то его можно получить позже через запрос к сервису orderresult.

Пример результата запроса в формате XML, вернувшего ошибку (неправильный пароль):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
  <!DOCTYPE result [...]> 
  <result firstcode="7" secondcode="102" count="0"></result>

С описанием первого и второго кодов ошибок можно ознакомиться здесь.

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

Дополнительные параметры (для СПМ)

Для магазинов, работающих по режиму silentpay, есть возможность передавать расширенные данные о клиенте для использования их системой противодействия мошенничеству.

Дополнительно к основному списку параметров, передаваемых в режиме silentpay, магазин может передать следующие необязательные параметры:

3D-Secure авторизация

Для магазинов, работающих по режиму silentpay, реализована возможность оплаты по картам, требующим 3D-Secure авторизации (в случае, если у магазина и процессинга выполнены соответствующие настройки).

При оплате картой, требующей авторизации по 3D-Secure, АПК Ассист возвращает код ответа (response_code) AS110. В пакет ответа по режиму silentpay также добавляются дополнительные поля, позволяющие ТСП обеспечить дополнительную аутентификацию плательщика по технологиям 3-D Secure (карты VISA) и Mastercard SecureCode (карты Mastercard ).

В настоящее время для дополнительной аутентификации плательщика большинство банков-эмитентов работает по версии протокола 3-D Secure 1.0 по всем типам карт.

Для более надежного процесса аутентификации банки-эмитенты и платежные системы переходят на новую версию протокола 2.0 и выше для всех типов карт (VISA, Mastercard). Для поддержки протокола нового поколения предприятию нужно внести изменения в процесс аутентификации плательщика.

Для начала оплаты заказа предприятие отправляет авторизационный запрос на сервер АПК Ассист. К обычным параметрам запроса необходимо добавить следующие данные об устройстве и браузере клиента, если это еще не было сделано ранее для работы с СПМ. В новом протоколе 3-D Secure 2.0 эти данные являются обязательными.

3D-Secure авторизация по протоколу 1.0

При оплате картой, требующей авторизации по протоколу 1.0, АПК Ассист возвращает код ответа (response_code) AS110 и дополнительные поля pareq и acsurl в ответе на запрос авторизации.

Клиент должен быть перенаправлен на сайт банка-эмитента по адресу, указанному в параметре acsurl (acsurl - значение, полученное в пакете результата режима silentpay от АПК Ассист).

В форме должны содержаться следующие поля:

Пример запроса HPPT POST к банку-эмитенту:

<FORM ACTION="acsurl - значение, полученное от АПК Ассист в пакете режима silentpay" method="POST">
<INPUT TYPE="hidden" NAME="PaReq" VALUE="pareq - значение, полученное от АПК Ассист в пакете режима silentpay ">
<INPUT TYPE="hidden" NAME="TermUrl" VALUE="url магазина для получения результата от банка-эмитента">
<INPUT TYPE="hidden" NAME="MD" VALUE="любые данные магазина">
<INPUT TYPE="submit" NAME="Submit_3DS" class="button" VALUE="Продолжить">
</FORM>

Банк-эмитент возвращает следующие поля:

Для продолжения процесса авторизации по 3D-Secure магазину необходимо передать в АПК Ассист пакет результата авторизации по 3D-Secure pares. Данная функциональность реализована в веб-сервисе get3DSec.

Get3DSec – веб-сервис передачи параметров авторизации карты по 3D-Secure

URL для передачи запроса:

https://<SERVER-NAME>/get3dsec/ws3dsec.cfm

Формат запроса и ответа SOAP, wsdl-описание сервиса доступно по URL:

https://<SERVER-NAME>/get3dsec/get3dsec.wsdl

Магазин должен отправить в АПК Ассист значение параметра pares, полученное в ответе от банка-эмитента. Для этого необходимо отправить запрос в формате SOAP.

Входные параметры:

Метод: send3dsparams

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

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<send3dsparams xmlns="urn:assist-processor">
<merchant_id>Идентификатор предприятия</merchant_id>
<login>Ваш логин</login>
<password>Ваш пароль</password>
<ordernumber>Номер заказа</ordernumber>
<language>Язык</language>
<pares>Значение, полученное в пакете результата от банка-эмитента</pares>
</send3dsparams>
<s:Body>
<s:Envelope>

Возвращаемая информация: пакет результата режима silentpay.

В случае возникновения ошибки:

<?xml version="1.0" encoding="windows-1251" standalone="no" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Fault>
<faultcode>Первый код</faultcode>
<faultstring>Второй код</faultstring>
<detail />
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3D-Secure авторизация по протоколу 2.0

Важной особенностью новой версии протокола является тот факт, что плательщик может быть аутентифицирован без ввода дополнительного пароля (на основе дополнительных данных). Процесс аутентификации, при котором не происходит дополнительного взаимодействия с держателем карты, называется Frictionless Flow. Процесс аутентификации, при котором держателю карты требуется ввести дополнительный код подтверждения, называется процессом проверки (Challenge Flow).

Также перед аутентификацией по новому протоколу браузером клиента должен быть отправлен дополнительный запрос на ACS банка-эмитента (в дальнейшем мы будем называть его 3DSMethod).

Для работы с новым протоколом на стороне предприятию необходимо внести следующие изменения:

1. Проверять версию протокола 3D-Secure в ответе на авторизационный запрос к сервису Assist. Для версии 1.0 поддерживать описанную выше схему работы.
2. Для версии 2.0 сформировать скрытый iframe на платежной странице (детальное описание параметров см. ниже) и отправить на ACS банка-эмитента запрос 3DSMethod.
3. Для продолжения аутентификации вызвать веб-сервис ws3dsecver2 с дополнительными параметрами 3D-Secure. Если аутентификация произойдет без дополнительного взаимодействия с клиентом (Frictionless Flow), то АПК Ассист получит ее результат и отправит транзакцию авторизации в процессинг. В ответе предприятие получит полный результат оплаты, содержащий также и результат авторизации в процессинге. В случае необходимости дополнительной аутентификации клиента АПК Ассист вернет в ответе на запрос дополнительные поля для проведения проверки (Challenge Flow).
4. При наличии в ответе дополнительных полей, сообщающих о необходимости дополнительной проверки, предприятие на платежной странице формирует iFrame, в котором реализует отображение страницы ACS банка-эмитента для ввода одноразового пароля. Покупатель завершает аутентификацию.
5. Результат прохождения проверки АПК Ассист получит на сервер на своей стороне. В случае успешной проверки будет проведена транзакция оплаты в процессинге. В случае неуспешной проверки операция завершится с ошибкой.
6. Для того чтобы узнать окончательный результат оплаты заказа, предприятию необходимо использовать один из методов получения результата авторизации.

Логику работы нового протокола 2.0 отображает граф-схема. Текстовое описание ниже содержит ссылки на пронумерованные блоки граф-схемы.

Для начала оплаты заказа предприятие отправляет авторизационный запрос на сервер АПК Ассист и необходимые дополнительные параметры (блок 1). Также могут использоваться необязательные дополнительные параметры.

При оплате картой, требующей авторизации по протоколу 2.0 АПК Ассист вернет в ответе код возврата AS110 (блок 2) и дополнительный блок параметров threedsdata. Список параметров, которые могут содержаться в блоке threedsdata представлен в таблице ниже:

¹Параметр может содержаться в ответе сервиса: 1- silentpay; 2 – get3dsecver2.

²В случае авторизации без дополнительной проверки (Frictionless Flow) параметры challengeurl и challengerequest не будут возвращены.

В зависимости от содержания полученного блока threedsdata (блоки 3,4,5) аутентификация продолжается по-разному.

Основные сценарии работы:

• Для версии 3D-Secure 2.0 (блок 3) при наличии URL банка-эмитента threeDSMethodURL (блок 5) предприятие формирует скрытый HTML iFrame на платежной странице (блок 8), отправляет POST запрос с одним параметром threeDSMethodData на полученный адрес threeDSMethodURL, и далее вызывает сервис get3dsecver2 (блок 9).
• Для версии 3D-Secure 2.0 (блок 3) при наличии URL банка-эмитента threeDSMethodURL (блоки 5, 8, 9), но без необходимости дополнительного взаимодействия с держателем карты (блок 4) - Frictionless Flow (F), АПК Ассист сразу проводит транзакцию в процессинге или завершает операцию с ошибкой (блок 12).
• Для версии 3D-Secure 2.0 (блок 3) при наличии URL банка-эмитента threeDSMethodURL (блоки 5, 8, 9) и при необходимости дополнительного взаимодействия с держателем карты (блок 10) предприятие должно сформировать на платежной странице объект HTML iFrame и отправить методом HTTP POST запрос проверки держателя карты к указанному URL challengeurl (блок 11). В этом iFrame отображается страница ACS банка эмитента и плательщик вводит одноразовый пароль, полученный от банка. Это сценарий Challenge Flow (C).
• Для версии 3D-Secure 2.0 (блок 3) при отсутствии URL банка-эмитента threeDSMethodURL и когда дополнительное взаимодействие с держателем карты не требуется - Frictionless Flow (F), сразу же будет проведена транзакция в процессинге, и процесс оплаты будет завершен (блок 12).
• Для версии 3D-Secure 2.0 (блок 3), когда взаимодействие с держателем карты необходимо (блок 4), но URL банка-эмитента threeDSMethodURL отсутствует (Нет - пусто) предприятие должно сформировать на платежной странице объект HTML iFrame и отправить методом HTTP POST запрос проверки держателя карты к указанному URL challengeurl (блок 11). В этом iFrame отображается страница ACS банка эмитента и плательщик вводит одноразовый пароль, полученный от банка.

get3dsecver2 - веб-сервис продолжения аутентификации по 3D-Secure

После отправки запроса на адрес threeDSMethodURL для продолжения процесса аутентификации предприятию необходимо отправить запрос на новый сервис get3dsecver2 (блок 9).

Результат отправки запроса на  threeDSMethodURL может быть положительным (код HTTP 200), отрицательным (любой другой код HTTP) или тайм-аут отправки запроса (установить 10 секунд). 

URL для передачи запроса:

https://<SERVER-NAME>/get3dsec/get3dsecver2.cfm

Поддерживаемые форматы: SOAP, JSON.

Входные параметры:

АПК Ассист продолжает процесс аутентификации плательщика в платежной системе и банке-эмитенте через 3DS Server.

Если дополнительная проверка покупателя не требуется (Frictionless Flow) (блок 10), АПК Ассист  проводит транзакцию в процессинге или завершает операцию с ошибкой (в зависимости от настроек процессинга, предприятия и результата аутентификации) (блок 12).

Ответ на запрос в этом случае будет содержать один из конечных кодов возврата (AS000 – операция успешно завершена, AS100-AS109 – отказ в авторизации), все поля ответа, описанные выше, и дополнительный блок данных threedsdata, в котором параметр challenge равен F, а поле alphaauthresult содержит результат аутентификации (Y, N, U, R).

Получение кода возврата AS110 в ответе на вызов сервиса get3dsecver2 означает, что нужна дополнительная проверка плательщика (Challenge Flow). При этом в блоке данных threedsdata параметр challenge будет равен C, а параметры challengeurl и challengerequest будут заполнены (блок 10).

Предприятие должно в этом случае сформировать на платежной странице объект HTML iFrame и отправить методом HTTP POST запрос проверки держателя карты к указанному URL (блок 11) с параметром creq, в котором передать полученное значение challengerequest. В этом iFrame отображается страница ACS банка-эмитента и плательщик вводит одноразовый пароль, полученный от банка.