Cкрытый режим платежа, при котором все данные о заказе, о покупателе, о способе оплаты и платежном средстве передаются непосредственно предприятием, может быть выполнен с использованием карты или токена.
Передача параметров платежа
Для работы в данном режиме предусмотрен web-сервис silentpay.
URL запроса для скрытого режима оплаты:
https://<SERVER-NAME>/pay/silentpay.cfm
Параметры передаются методом POST в теле запроса в формате «ключ=значение», SOAP запросом, либо в формате JSON (swagger описание: https://docs.assist.kz/swagger/).
Список параметров, передаваемых в режиме silentpay:
Название | Обяза- тельное поле | Принимаемые значения | Значение по умолчанию | Описание |
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 соответственно, в остальных случаях ответ выдается согласно переданному значению формата. |
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. Использование такого режима работы возможно по согласованию с Assist. Для настройки необходимо обратиться в службу технической поддержки support@assist.kz При использовании параметра его необходимо добавлять и в подпись заказа, которая формируется по определенным правилам. |
ChallengeResponseNotificationUrl | Нет | 255 символов | URL, на который отправляется результат прохождения 3ds и перенаправляется покупатель после Challenge. |
*Передача данных покупателя не является обязательной, но при отсутствии поля email клиенту не будет отправлены уведомление об оплате и фискальный чек даже в том случае, если у мерчанта установлены соответствующие настройки. При отсутствии этих параметров также будут ограничены возможности работы системы СПМ и передача дополнительных параметров аутентификации по протоколу 3-D Secure версии 2.
Примечание
Для фискализации платежа в запросе могут передаваться дополнительные параметры для формирования корректного чека. Описание дополнительных параметров приведено в разделе "Режимы передачи данных чека".
Пример запроса 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="KZT"> <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="hidden" NAME="GenerateReceipt" VALUE="1"> <INPUT TYPE="hidden" NAME="Tax" VALUE="Идентификатор ставки налога"> <INPUT TYPE="hidden" NAME="ReceiptLine" VALUE="Наименование позиции чека"> <INPUT TYPE="hidden" NAME="FPMode" VALUE="Признак способа расчета"> <INPUT TYPE="Submit"></FORM>
Описание веб-сервиса для формата SOAP:
https://<SERVER-NAME>/pay/silentpay.wsdl
Список возвращаемых параметров:
Название | Значение |
ordernumber | Номер заказа |
billnumber | Полный уникальный номер операции в системе |
testmode | Тестовый режим |
ordercomment | Комментарий |
orderamount | Оригинальная сумма заказа |
ordercurrency | Оригинальная валюта заказа |
amount | Сумма операции |
currency | Валюта операции |
rate | Курс валюты |
firstname | Имя плательщика |
lastname | Фамилия плательщика |
middlename | Отчество плательщика |
Email плательщика | |
ipaddress | IP-адрес плательщика |
meantypename | Тип платежного средства |
Параметры карты покупателя | |
meansubtype | Подтип платежного средства |
meannumber | Номер платежного средства |
cardholder | Держатель платежного средства |
cardexpirationdate | Срок действия карты |
issuebank | Название банка-эмитента |
bankcountry | Страна банка-эмитента |
Параметры заказа | |
orderdate | Дата заказа по Гринвичу (GMT) |
orderstate | Статус заказа |
responsecode | Код возврата |
message | Сообщение |
customermessage | Сообщение о результате для покупателя |
recommendation | Рекомендации |
approvalcode | Код авторизации |
protocoltypename | Протокол |
processingname | Процессинг |
operationtype | Тип операции |
packetdate | Дата формирования запроса по Гринвичу (GMT) |
signature | Подпись. Создается по следующему алгоритму: 1. Формируется объединённая строка из параметров (в их строковом представлении, в формате как они переданы в ответе): billnumber, ordernumber, responsecode, orderamount, ordercurrency, meannumber, approvalcode, orderstate, packetdate (без разделителей) |
pareq | Пакет запроса по 3D-Secure авторизации |
ascurl | Адрес для переадресации плательщика для прохождения 3D-Secure авторизации |
Внимание!
При использовании сервиса имеются ограничения по производительности.
Результат запроса в зависимости от выбранного формата получения будет выглядеть следующим образом.
В формате CSV:
Название поля:Значение поля Название поля:Значение поля....Название поля:Значение поля
В формате XML:
<?xml version='1.0' encoding='UTF-8' standalone='yes'?> <!DOCTYPE result [ <result firstcode='Первый код' secondcode='Второй код' count='Кол-во объектов'> <orders><order> <ordernumber>Номер заказа</ordernumber> <responsecode>Код возврата</responsecode> <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.kz/ws/"> <soapenv:Header/> <soapenv:Body> <ws:SilentPayResponse> <return> <ordernumber xsi:type="xsd:string">Номер заказа</ordernumber> <responsecode xsi:type="xsd:string">Код возврата</responsecode> <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>
Результат запроса в формате 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.kz/ws/"> <soapenv:Header/> <soapenv:Body> <ws:SilentPayResponse> <return> <ordernumber>silent-test-101468</ordernumber> <billnumber>599093519074915.1</billnumber> <testmode>0</testmode > <ordercomment></ordercomment> <orderamount>31.79</orderamount> <ordercurrency>KZT</ordercurrency> <firstname>Auto</firstname> <lastname>Test</lastname> <middlename></middlename> <email>null@assist.kz</email> <orderdate>14.06.2022 11:39:19</orderdate> <orderstate>In Process</orderstate> <operationtype>100</operationtype> <amount>31.79</amount> <currency>KZT</currency > <rate>1</rate> <ipaddress>127.0.0.1</ipaddress> <meantypename>Visa</meantype> <responsecode>AS300</responsecode> <message>Сообщение пользователю</message> <customermassage>Сообщение пользователю</customermassage> <recommendation></recommendation> <protocoltypename>NET</protocoltypename> <processingname>Fake</processingname> <paketdate>14.06.2022 11:39:23</paketdate> <signature> </signature> </return> </ws:SilentPayResponse> </soapenv:Body> </soapenv:Envelope>
Результат запроса в формате JSON:
{"silentpay": {"meantypename":"Visa", "customermessage":"Сообщение пользователю", "message":"Сообщение пользователю", "testmode":0, "protocoltypename":"NET", "operationtype":100, "customer": {"lastname":"test", "firstname":"test", "middlename":"", "ipaddress":"127.0.0.1", "email":"null@assist.kz"}, "orderdate":"14.06.2022 11:40:43", "packetdate":"14.06.2022 11:40:46", "orderamount":1.99, "ordercomment":"", "ordercurrency":"KZT", "recommendation":"", "processingname":"Fake", "orderstate":"In Process", "rate":1, "billnumber":"599093519074916.1", "currency":"KZT", "amount":1.99, "ordernumber":"silent-test-198954", "responsecode":"AS300"}}
В случае успешной оплаты код возврата 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.
3D-Secure авторизация
Для магазинов, работающих по режиму silentpay, реализована возможность оплаты по картам, требующим 3D-Secure авторизации (в случае, если у магазина и процессинга выполнены соответствующие настройки).
При оплате картой, требующей авторизации по 3D-Secure, АПК Ассист возвращает код ответа (responsecode) AS110. В пакет ответа по режиму silentpay также добавляются дополнительные поля, позволяющие ТСП обеспечить дополнительную аутентификацию плательщика по технологиям 3-D Secure (карты VISA и, Mastercard SecureCode.
В настоящее время для дополнительной аутентификации плательщика многие банки-эмитенты работают по версии 1 протокола 3-D Secure для всех типов карт.
Для более надежного процесса аутентификации банки-эмитенты и платежные системы переходят на новую версию 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 адрес покупателя |
3D-Secure авторизация по протоколу версии 1
При оплате картой, требующей авторизации по протоколу версии 1, АПК Ассист возвращает код ответа (responsecode) AS110 и дополнительные поля pareq и acsurl в ответе на запрос авторизации.
Клиент должен быть перенаправлен на сайт банка-эмитента по адресу, указанному в параметре acsurl (acsurl - значение, полученное в пакете результата режима silentpay от АПК Ассист).
В форме должны содержаться следующие поля:
AcsUrl | Url банка-эмитента. Значение, полученное в пакете результата режима silentpay от АПК Ассист. |
PaReq | Значение, полученное в пакете результата режима silentpay от АПК Ассист. |
TermUrl | Url магазина для получения результата от банка эмитента. |
MD | Идентификатор, по которому в дальнейшем связывается результат, полученный от банка, и заказ. Данное поле возвращается от банка эмитента. |
Пример запроса HTTP 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>
Банк-эмитент возвращает следующие поля:
PaRes | Пакет результата |
MD | Идентификатор, введенный ранее |
Для продолжения процесса авторизации по 3D-Secure магазину необходимо передать в АПК Ассист пакет результата авторизации по 3D-Secure pares. Данная функциональность реализована в веб-сервисе get3DSec.
Get3DSec – веб-сервис передачи параметров авторизации карты по 3D-Secure
URL для передачи запроса:
https://<SERVER-NAME>/get3dsec/ws3dsec.cfm