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).
...
Для того, чтобы после прохождения дополнительной проверки плательщик смог вернуться обратно на сайт предприятия, следует сообщить службе поддержки АПК Ассист 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"
}
} |