Page History
...
Название | Обяза- тельное поле | Принимаемые значения | Значение по умолчанию | Описание | ||||
Merchant_ID | Да | Число | Идентификатор предприятия в системе АПК Ассист | |||||
Login | Да | Строка | Ваш логин | |||||
Password | Да | Строка | Ваш пароль | |||||
OrderNumber | Да/Нет | 128 символов | Номер заказа в системе расчетов предприятия. | |||||
OrderAmount | Да | Число, 15 знаков, два знака после разделителя (допустимые разделители «.», «,») | Сумма платежа в оригинальной валюте (например, 10.34) | |||||
OrderCurrency | Нет | 3 символа | Валюта юр.лица или предприятия | Код валюты, в которой указана сумма платежа OrderAmount (KZT, USD, EUR) | ||||
OrderComment | Нет | 4000 символов | Комментарий | |||||
Delay | Нет | 0 – - одностадийный механизм работы, | 0 | Признак авторизации банковской карты при двустадийном механизме работы | ||||
Language | Нет | RU – - русский | Язык юр.лица или предприятия | Язык авторизационных страниц | ||||
ClientIP | Нет/Да | IP адрес покупателя. Параметр является обязательным для протокола 3-D Secure версии 2. | ||||||
Cardtype | Нет | 1 – - VISA | Идентификатор типа карты для оплаты. | |||||
Cardnumber | Да | Номер карты | ||||||
Cardholder | Нет* | 70 символов без цифр. Разделитель – - пробел. | Держатель карты. | |||||
Expiremonth | Да | 1-12 | Месяц окончания действия карты | |||||
Expireyear | Да | Год в формате YYYY | Год окончания действия карты | |||||
Cvc2 | Да | CVC2 код | ||||||
Lastname | Нет* | 70 символов без цифр | Фамилия покупателя | |||||
Firstname | Нет* | 70 символов без цифр | Имя покупателя | |||||
Middlename | Нет | 70 символов без цифр | Отчество покупателя | |||||
Нет* | 128 символов | E-mail покупателя | ||||||
Address | Нет | 256 символов | Адрес покупателя | |||||
HomePhone | Нет | 64 символа | Домашний телефон покупателя | |||||
WorkPhone | Нет | 20 символов | Рабочий телефон покупателя | |||||
MobilePhone | Нет | 20 символа | Мобильный телефон покупателя | |||||
Country | Нет | 3 символа | Код страны покупателя | |||||
State | Нет | 3 символа | Код региона покупателя | |||||
City | Нет | 70 символа | Город покупателя | |||||
Zip | Нет | 25 символа | Индекс предприятия связи покупателя | |||||
isConvert | Нет | 0 - Не конвертировать в базовую валюту 1 - Не конвертировать при возможности 2 - Всегда конвертировать | 1 | Флаг конвертации валюты платежа в базовую валюту | ||||
Format | Нет | 1 – - CSV | 1 | Формат выдачи результата. Если запрос передан в формате SOAP или JSON, то ответ также будет в SOAP или JSON соответственно, в остальных случаях ответ выдается согласно переданному значению форматарезультатов. Передается только для запроса в формате POST (по умолчанию ответ будет выдан в формате CSV). Для других форматов ответ выдается в том же формате, в котором был выполнен запрос. | ||||
Signature | Нет | строка | Формируется строка по определенным правилам. На базе этой строки алгоритмом MD5 формируется дайджест. Дайджест подписывается закрытым RSA ключом мерчанта. Длина ключа - 1024. Полученная байтовая последовательность является подписью магазина. Подпись передается нам в виде дополнительного параметра, закодированного в виде строки BASE64. Внимание! Параметр необходим для того, чтобы обезопасить передаваемые данные от возможности их подмены злоумышленниками. Следует также включить настройку проверки кода или подписи в ЛК. | |||||
RecurringIndicator | Нет | 1 –рекуррентный - рекуррентный платеж 0 - обычный платеж | 0 | Признак рекуррентного платежа | ||||
RecurringMinAmount | Нет/Да | Число, 15 знаков, два знака после разделителя (допустимые разделители «.», «,») | Минимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |||||
RecurringMaxAmount | Нет/Да | Число, 15 знаков, два знака после разделителя (допустимые разделители «.», «,») | Максимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |||||
RecurringPeriod | Нет/Да | Число, 3 цифры | Периодичность рекуррентных платежей в днях. Параметр обязателен при RecurringIndicator = 1 | |||||
RecurringMaxDate | Нет/Да | Строковое представление даты в формате DD.MM.YYYY | Дата окончания рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |||||
CustomerNumber | Нет | 32 символа | Внутренний номер клиента предприятия (мерчанта) | |||||
SaveCard | Нет | 1 – - карта привязывается к данному номеру клиента; 0 – - карта не привязывается | 0 | В случае успешного платежа разрешает сохранять карту по данному номеру клиента для последующих платежей. Если карта для данного номера клиента уже была сохранена ранее, то параметр игнорируется. | ||||
Disable3DS | Нет | 0 – - проверять 3-D Secure согласно настройкам предприятия, 1 –- проводить платеж без 3-D Secure. | 0 | Признак отключения 3-D Secure.
| ||||
ChallengeResponseNotificationUrl | Нет | 255 символов | URL, на который отправляется результат прохождения 3ds и перенаправляется покупатель после Challenge. |
...
При оплате картой, требующей авторизации по 3D-Secure, АПК Ассист возвращает код ответа (responsecode) AS110. В пакет ответа по режиму silentpay также добавляются дополнительные поля, позволяющие ТСП обеспечить дополнительную аутентификацию плательщика по технологиям 3-D Secure (карты VISA и, Mastercard SecureCode.
В настоящее время для дополнительной аутентификации плательщика многие банки-эмитенты работают по версии 1 протокола 3-D Secure применяется версия протокола 2.0 для всех типов карт.
Для более надежного процесса аутентификации банки-эмитенты и платежные системы переходят на новую версию 2 и выше протокола для всех типов карт (VISA, Mastercard). Для поддержки протокола нового поколения предприятию нужно внести изменения в процесс аутентификации плательщика.Для начала оплаты заказа предприятие отправляет авторизационный запрос на сервер АПК Ассист. К обычным параметрам запроса необходимо добавить следующие данные об устройстве и браузере клиента. В новом протоколе 3-D Secure версии 2 эти данные являются обязательными.
Название | Принимаемые значения | Описание |
HEADER_HTTP_ACCEPT | Строка, 255 байт | Заголовок http запроса ACCEPT |
HEADER_HTTP_USER_AGENT | Строка, 255 байт | Заголовок http запроса USER-AGENT |
CLIENT_JAVA | Логическое (true, false) | navigator.javaEnabled() |
CLIENT_BROWSER_LANGUAGE | Строковый (5 байт) | navigator. language |
CLIENT_SCREEN_COLORS | Числовой (1, 4,8,15,16,24,32,48) | Screen.pixelDepth |
CLIENT_SCREEN_RES | Строковый, 16 символов | Screen.width + 'x' + screen.height |
ChallengeWindowSize | 2 символа (01 – - 250x400, 02 – - 390x400, 03 – - 500x600, 04 – - 600x400, 05 – - Full screen) | Размер iframe для прохождения проверки держателя карты |
ClientIP | Максимум 15 цифр, 4 разделителя «.» | IP адрес покупателя |
Anchor | ||||
---|---|---|---|---|
|
Expand | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||
3D-Secure авторизация по протоколу версии 1При оплате картой, требующей авторизации по протоколу версии 1, АПК Ассист возвращает код ответа (responsecode) AS110 и дополнительные поля pareq и acsurl в ответе на запрос авторизации. Клиент должен быть перенаправлен на сайт банка-эмитента по адресу, указанному в параметре acsurl (acsurl - значение, полученное в пакете результата режима silentpay от АПК Ассист). В форме должны содержаться следующие поля:
Пример запроса HTTP POST к банку-эмитенту:
Банк-эмитент возвращает следующие поля:
Для продолжения процесса авторизации по 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 запроса:
Возвращаемая информация: пакет результата режима silentpay. В случае возникновения ошибки:
|
3D-Secure авторизация по протоколу версии 2
...
Название | Принимаемые значения | Описание | В ответе сервиса1 |
version | Версия протокола 3-D Secure | 1,2 | |
threeDSServerTransID | Строка | ID транзакции в 3DS Server | 1,2 |
threeDSMethodURL | Строка, до 256 символов | URL на стороне банка-эмитента или платежной системы | 1 |
threeDSMethodData | Строка, до 256 символов | Закодированное в Base64 тело запроса | 1 |
alphaauthresult | Y - успешно, N - неуспешно, A - Attempt, U – - невозможно провести аутентификацию, R - отказ, E - ошибка, I - для информации | Результат аутентификации будет получен в ответе, если она произошла в одну стадию (Frictionless Flow) | 1,2 |
challenge | F - Frictionless Flow | Взаимодействие с держателем карты (C – - нужно, F – - не нужно, D - отложенная аутентификация) | 1,2 |
challengeurl2 | Полное доменное имя (URL) https://acs.... Длина максимум 2048 символов | URL банка-эмитента или платежной системы для проверки плательщика | 1,2 |
challengerequest2 | Сообщение, закодированное методом Base64, длина переменная | Данные запроса, отправляемого на challengeurl | 1,2 |
...
1Параметр может содержаться в ответе сервиса: 1- silentpay; 2 –- get3dsecver2.
Anchor | ||||
---|---|---|---|---|
|
2В случае авторизации без дополнительной проверки (Frictionless Flow) и для отложенной аутентификации (Decoupled authentication) параметры challengeurl и challengerequest не будут возвращены.
...
Ответ на запрос в этом случае будет содержать один из конечных кодов возврата (AS000 – - операция успешно завершена, AS100-AS109 – - отказ в авторизации), все поля ответа, описанные выше, и дополнительный блок данных threedsdata, в котором параметр challenge равен F, а поле alphaauthresult содержит результат аутентификации (Y, N, U, R, I).
Получение кода возврата AS110 в ответе на вызов сервиса get3dsecver2 означает, что нужна дополнительная проверка плательщика (Challenge Flow). Для сценария с дополнительной проверкой (Challenge Flow) в блоке данных threedsdata параметр challenge будет равен C, а параметры challengeurl и challengerequest будут заполнены (блок 8). Предприятие должно в этом случае сформировать на платежной странице объект HTML iFrame и отправить методом HTTP POST запрос проверки держателя карты к указанному URL (блок 11) с параметром creq, в котором передать полученное значение challengerequest. В этом iFrame отображается страница ACS банка-эмитента и плательщик вводит одноразовый пароль, полученный от банка.
В сценарии с отложенной аутентификацией в блоке данных threedsdata параметр challenge будет равен D, а параметры challengeurl и challengerequest будут отсутствовать (блок 8). Предприятие должно в этом случае оставить заказ в состоянии В Процессе и ожидать окончательного статуса оплаты.
Результат этой проверки АПК Ассист получит на свой сервер в асинхронном режиме. В зависимости от результата аутентификации и настроек процессинга и предприятия, АПК Ассист проведет транзакцию оплаты в процессинге или закроет операцию с ошибкой.
Для того, чтобы после прохождения дополнительной проверки плательщик смог вернуться обратно на сайт предприятия, следует сообщить службе поддержки АПК Ассист URL для возврата покупателя и приема результата прохождения дополнительной проверки. Для предприятия получение этого запроса будет означать, что дополнительная проверка завершена, и оно может в этот момент перенаправить браузер плательщика на страницу результата на своей стороне и ожидать завершения платежной транзакции в процессинге.
Получение результата платежа после дополнительной проверки отражено на схеме блоками 12, 13, 14.
Warning | ||
---|---|---|
| ||
Процесс получения результата дополнительной проверки на сервера АПК Ассист является асинхронным. Только после получения этого результата будет проведена (или не проведена) транзакция оплаты в процессинге, которая приведет к блокировке средств на карте клиента. Предприятию следует получить результат операции оплаты от АПК Ассист одним из стандартных способов. Предприятие может отправить запрос к сервису получения результата операции по номеру заказа, либо настроить на своей стороне получение результатов авторизации, отправляемых АПК Ассист на сервер предприятия. |
Пример блока данных threedsdata, в котором дополнительной проверки держателя не требуется (при этом код возврата responsecode будет отличен от AS110):
Code Block | ||
---|---|---|
| ||
<threedsdata>
<version>2.2</version>
<alphaauthresult>Y</alphaauthresult>
<challenge>F<challenge>
</threedsdata> |
Пример блока данных threedsdata, в котором требуется дополнительная проверка держателя (код возврата responsecode равен AS110):
Code Block | ||
---|---|---|
| ||
<threedsdata>
<version>2.2</version>
<challenge>С<challenge>
<challengeurl>https://acs.superbank.ru/version20/creq</challengeurl>
<challengerequest>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE3ZWJlMDU3LTg2ZjgtNGFmMS05MTJkHGNlYTc5Mzc0OWUxMiIsImFjc1RyYW5zSUQiOiI5ODhmOWZmYS1kNzYyLTQ0YjktOWI0OS01ZDRkMjU5YmRkZWQiLCJkc1RyYW5zSUQiOiJkMGJmZGQzYy00YzdhLTVmNjktODAwMC0wMDAwMDAwOGM3NjMiLCJtZXNzYWdlVHlwZSI6IkNSеZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0</challengerequest>
</threedsdata> |
Чтобы получить ответ веб-сервиса в формате JSON, нужно передать в запросе content-type=application/json или format=5.
Описание параметров всех веб-сервисов АПК Ассист для формата JSON содержится в файле swagger по адресу:
https://docs.assist.kz/swagger/
Пример ответа в формате JSON для операции без дополнительной аутентификации:
Code Block | ||
---|---|---|
| ||
{
"threedsdata": {
"version": "2.2",
"alphaauthresult": "Y",
"challenge": "F"
},
"silentpay": {
"customermessage": "Завершено успешно",
"message": "Завершено успешно",
"testmode": 0,
"operationtype": 100,
"orderdate": "05.04.2022 11:19:54",
"packetdate": "05.04.2022 11:19:58",
"orderamount": 31.79,
"ordercomment": "",
"cardexpirationdate": "12/23",
"ordercurrency": "KZT",
"recommendation": "",
"processingname": "Credx",
"meannumber": "554373****0010",
"orderstate": "Approved",
"rate": 1,
"amount": 31.79,
"responsecode": "AS000",
"meantypename": "MasterCard",
"protocoltypename": "NET",
"bankcountry": "Казахстан",
"customer": {
"lastname": "Test",
"firstname": "Auto",
"middlename": "",
"ipaddress": "127.0.0.1",
"email": "null@assist.kz"
},
"cardholder": "TEST",
"approvalcode": "489489",
"billnumber": "5817109255129315.1",
"issuebank": "BANK",
"currency": "KZT",
"ordernumber": "856a13d9-e9a0-4d3c-9d02-b82db6bae03e",
"meansubtype": "Platinum MasterCard Salary-Immediate Debit"
}
} |
Пример ответа для операции c дополнительной аутентификацией:
Code Block | ||
---|---|---|
| ||
{
"threedsdata": {
"version": "2.2.0",
"challengerequest": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjQxMWI2ODVjLWUzODAtNGZkYS05YmIzLWJiZjM2OTJiNGMyNiIsImFjc1RyYW5zSUQiOiJmY2FlMDMzNS0xODgwLTRlNjgtOWJjMy0wMDcyZDM4ZTkzODYiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDIiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0",
"challengeurl": "https://fake.3dss.t.paysecure.ru/acs/challenge",
"challenge": "C"
},
"MakePaymentResponse": {
"customermessage": "Создана Аутентификация клиента по технологии 3DSecure",
"message": "Создана Аутентификация клиента по технологии 3DSecure",
"testmode": 0,
"operationtype": 100,
"orderdate": "05.04.2022 11:19:32",
"packetdate": "05.04.2022 11:19:34",
"orderamount": 31.79,
"ordercomment": "",
"cardexpirationdate": "12/23",
"ordercurrency": "KZT",
"recommendation": "",
"processingname": "Credx",
"meannumber": "554373****6654",
"orderstate": "In Process",
"rate": 1,
"amount": 31.79,
"responsecode": "AS110",
"meantypename": "MasterCard",
"protocoltypename": "NET",
"bankcountry": "Казахстан",
"customer": {
"lastname": "Test",
"firstname": "Auto",
"middlename": "",
"ipaddress": "127.0.0.1",
"email": "null@assist.kz"
},
"cardholder": "TEST",
"approvalcode": "",
"billnumber": "5817109255129273.1",
"issuebank": "BANK",
"currency": "KZT",
"ordernumber": "6b510f3d-1327-4f3b-bc17-612daeed3aac",
"meansubtype": "Platinum MasterCard Salary-Immediate Debit"
}
} |