Предприятие может также узнать результаты операций по заказам, проведенным за указанный период, с помощью веб-сервиса.
Для получения результатов авторизации нужно отправить запрос на сервер АПК Ассист методом HTTP POST или SOAP (в кодировке UTF-8), либо в формате JSON (swagger описание: https://docs.belassist.by/swagger/).
URL запроса для получения результатов авторизации:
https://<SERVER-NAME>/resultbydate/resultbydate.cfm.
Получить результаты операций при помощи веб-сервиса можно только за промежуток времени, не превышающий сутки. Для этого нужно указать такие значения параметров, задающих дату начала выборки, и параметров, задающих дату окончания выборки, чтобы разница между этими датами составляла не более суток. В противном случае для этих параметров будут использованы значения по умолчанию (за последние 3 часа). Иными словами, если параметры, определяющие дату начала и дату окончания выборки, не заданы или заданы неверно, в результате запроса будут выведены результаты операций, совершенных за последние три часа. Обратите внимание, что параметры, задающие дату и время выборки, необходимо передавать по Гринвичу (GMT/UTC). Выборка производится по дате заказа.
Если клиент прервал процесс оплаты раньше, чем выбрал тип платежного средства, то в системе АПК Ассист не будет создана операция оплаты, и выборке не будет операций по данному заказу.
Внимание! Запрашивать результаты операций можно за промежуток времени, не превышающий одни сутки, и не чаще, чем один раз в 10 минут.
Список параметров запроса:
Название | Обязательное поле | Принимаемые значения | Значение по умолчанию | Описание |
Merchant_ID | Да | Число | Идентификатор предприятия в АПК Ассист | |
Login | Да | 8 - 20 символов | Логин (лат. буквы и цифры, символ _) | |
Password | Да | 8 - 20 символов | Пароль (лат. буквы и цифры) | |
TestMode | Да | 0 – рабочий режим 1 – тестовый режим | 0 | Режим работы |
Language | Нет | RU EN | EN | Язык выдачи результатов |
Format | Да/Нет | 1 – CSV | 1 | Формат выдачи результатов. Передается только для запроса в формате POST (по умолчанию ответ будет выдан в формате CSV). Для других форматов ответ выдается в том же формате, в котором был выполнен запрос. |
MeanType_ID | Нет | 1 – VISA | По умолчанию выборка по всем значениям | Выборка по типам платежных средств |
Operationstate | Нет | N – создана; | По умолчанию выборка по всем значениям | Выборка по состояниям операций. Регистр должен быть верхний. |
Operationtype | Нет | A – оплата; | По умолчанию выборка по всем значениям | Выборка по типам операций. Регистр должен быть верхний. |
StartDay | Нет | 01-31 | По умолчанию – минус три часа от текущего времени на момент выборки | Дата начала выборки по Гринвичу (GMT) |
StartMonth | Нет | 01-12 | ||
StartYear | Нет | YYYY | ||
StartHour | Нет | 00-23 | ||
StartMin | Нет | 00-59 | ||
EndDay | Нет | 01-31 | По умолчанию - текущее время на момент выборки | Дата окончания выборки по Гринвичу (GMT) |
EndMonth | Нет | 01-12 | ||
EndYear | Нет | YYYY | ||
EndHour | Нет | 00-23 | ||
EndMin | Нет | 00-59 | ||
DateTimeMode | Нет | 0 – по дате заказа; | 0 | Тип даты - целевая дата для выборки данных |
ZipFlag | Нет | "0" - browser | 0 | Формат выдачи результатов |
Все параметры, передаваемые в запросе, проходят автоматическую валидацию в АПК Ассист. Правила валидации описаны в табл. "Правила валидации входных параметров".
На основании значений параметров, переданных на сервер АПК Ассист в запросе о результатах операций, производится выборка информации и определяется формат и вид результата.
Например, в результате запроса могут быть выведены только успешные операции оплаты по картам VISA.
Пример запроса HTTP POST для получения результатов, возвращающий информацию об успешных операциях оплаты по картам VISA в тестовом режиме с 07:00 до 11:00 (GMT) 06.07.2016 в формате XML:
<FORM ACTION="https://<SERVER-NAME>/resultbydate/resultbydate.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="TestMode" VALUE="1"> <INPUT TYPE="hidden" NAME="Language" VALUE="EN"> <INPUT TYPE="hidden" NAME="MeanType_ID" VALUE="1"> <INPUT TYPE="hidden" NAME="Operationstate" VALUE="S"> <INPUT TYPE="hidden" NAME="Operation type" VALUE="A"> <INPUT TYPE="hidden" NAME="StartDay" VALUE="06"> <INPUT TYPE="hidden" NAME="StartMonth" VALUE="07"> <INPUT TYPE="hidden" NAME="StartYear" VALUE="2016"> <INPUT TYPE="hidden" NAME="StartHour" VALUE="07"> <INPUT TYPE="hidden" NAME="StartMin" VALUE="00"> <INPUT TYPE="hidden" NAME="EndDay" VALUE="06"> <INPUT TYPE="hidden" NAME="EndMonth" VALUE="07"> <INPUT TYPE="hidden" NAME="EndYear" VALUE="2016"> <INPUT TYPE="hidden" NAME="EndHour" VALUE="11"> <INPUT TYPE="hidden" NAME="EndMin" VALUE="00"> <INPUT TYPE="hidden" NAME="DateTimeMode" VALUE="1"> <INPUT TYPE="hidden" NAME="Format" VALUE="3"> <INPUT TYPE="Submit"></FORM>
Список параметров ответа:
Название | Значение |
ordernumber | Номер заказа |
billnumber | Расширенный формат billnumber |
testmode | Тестовый режим |
ordercomment | Комментарий |
orderamount | Оригинальная сумма заказа |
ordercurrency | Оригинальная валюта заказа |
amount | Сумма операции |
currency | Валюта операции |
rate | Курс валюты |
lastname | Фамилия плательщика |
firstname | Имя плательщика |
middlename | Отчество плательщика |
Email плательщика | |
clientip | IP-адрес совершившего операцию |
ipaddress | IP-адрес плательщика |
meantype_id | ID платежного средства |
meantypename | Тип платежного средства |
meansubtype | Подтип платежного средства |
meannumber | Номер платежного средства |
cardholder | Держатель платежного средства |
issuebank | Название банка-эмитента |
bankcountry | Страна банка-эмитента |
orderdate | Дата заказа по Гринвичу (GMT) |
orderstate | Cтатус заказа |
responsecode | Код возврата |
message | Сообщение |
customermessage | Сообщение о результате для покупателя |
recommendation | Рекомендации |
approvalcode | Код авторизации |
protocoltypename | Протокол |
processingname | Процессинг |
operationtype | Тип операции |
operationdate | Дата и время операции (GMT) |
authresult | Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U – неизвестно) |
authrequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – ошибка при определении вовлеченности) |
slipno | Номер финансовой транзакции, отправляемый в процессинг (не используется) |
packetdate | Дата формирования запроса по Гринвичу (GMT) |
checkvalue | uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки параметров merchant_id, ordernumber, orderamount, ordercurrency, orderstate (без разделителей), + строковая склейка. |
cardexpirationdate | Срок действия карты |
Внимание! В полученном ответе необходимо проверить значение параметра testmode. Если платеж был выполнен в тестовом режиме (testmode=1), то отгружать товар или оказывать услугу по текущему заказу не требуется.
Пример полей вывода результата в XML формате:
<?xml version='1.0' encoding='utf-8' standalone='yes'?> <!DOCTYPE result [ <!ATTLIST result firstcode CDATA #REQUIRED secondcode CDATA #REQUIRED count CDATA #REQUIRED> <!ELEMENT result (payment*)> <!ELEMENT payment (ordernumber?,billnumber?,testmode?,ordercomment?,orderamount?,ordercurrency?,amount?,currency?,rate?,firstname?,lastname?,middlename?,email?,clientip?,ipaddress?,meantype_id?,meantypename?,meansubtype?,meannumber?,cardholder?,issuebank?,bankcountry?,orderdate?,orderstate?,responsecode?,message?,customermessage?,recommendation?,approvalcode?,protocoltypename?,processingname?,operationtype?,operationdate?,authresult?,authrequired?, slipno?,packetdate?,signature?,checkvalue?, cardexpirationdate?)> <!ELEMENT ordernumber (#PCDATA)> <!ELEMENT billnumber (#PCDATA)> <!ELEMENT testmode (#PCDATA)> <!ELEMENT ordercomment (#PCDATA)> <!ELEMENT orderamount (#PCDATA)> <!ELEMENT ordercurrency (#PCDATA)> <!ELEMENT amount (#PCDATA)> <!ELEMENT currency (#PCDATA)> <!ELEMENT rate (#PCDATA)> <!ELEMENT firstname (#PCDATA)> <!ELEMENT lastname (#PCDATA)> <!ELEMENT middlename (#PCDATA)> <!ELEMENT email (#PCDATA)> <!ELEMENT clientip (#PCDATA)> <!ELEMENT ipaddress (#PCDATA)> <!ELEMENT meantype_id (#PCDATA)> <!ELEMENT meantypename (#PCDATA)> <!ELEMENT meansubtype (#PCDATA)> <!ELEMENT meannumber (#PCDATA)> <!ELEMENT cardholder (#PCDATA)> <!ELEMENT issuebank (#PCDATA)> <!ELEMENT bankcountry (#PCDATA)> <!ELEMENT orderdate (#PCDATA)> <!ELEMENT orderstate (#PCDATA)> <!ELEMENT responsecode (#PCDATA)> <!ELEMENT message (#PCDATA)> <!ELEMENT customermessage (#PCDATA)> <!ELEMENT recommendation (#PCDATA)> <!ELEMENT approvalcode (#PCDATA)> <!ELEMENT protocoltypename (#PCDATA)> <!ELEMENT processingname (#PCDATA)> <!ELEMENT operationtype (#PCDATA)> <!ELEMENT operationdate (#PCDATA)> <!ELEMENT authresult (#PCDATA)> <!ELEMENT authrequired (#PCDATA)> <!ELEMENT slipno (#PCDATA)> <!ELEMENT packetdate (#PCDATA)> <!ELEMENT signature (#PCDATA)> <!ELEMENT checkvalue (#PCDATA)> <!ELEMENT cardexpirationdate (#PCDATA)>]> <result firstcode='0' secondcode='0' count='17'> <payment> <ordernumber>0001-01</ordernumber> <billnumber>511111100000001.1</billnumber> <testmode>1</testmode> <ordercomment>тестовый платеж</ordercomment> <orderamount>100.00</orderamount> <ordercurrency>BYN</ordercurrency> <amount>100.00</amount> <currency>BYN</currency> <rate>1</rate> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>Testovich</middlename> <email>test@testpost.by</email> <clientip>111.23.11.23</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>1</meantype_id> <meantypename>VISA</meantypename> <meansubtype>Corporate Purchasing Card</meansubtype> <meannumber>411111****1111</meannumber> <cardholder>TEST</cardholder> <issuebank>BANK </issuebank> <bankcountry>Russia</bankcountry> <orderdate>06.07.2016 08:39:25</orderdate> <orderstate>Approved</orderstate> <responsecode>AS000</responsecode> <message>Success </message> <customermessage>Success </customermessage> <recommendation></recommendation> <approvalcode>F31720</approvalcode> <protocoltypename>NET</protocoltypename> <processingname>Name</processingname> <operationtype>100</operationtype> <operationtdate>06.07.2016 06:39:42</operationdate> <authresult/> <authrequired>0</authrequired> </slipno> <packetdate>06.07.2016 10:55:51</packetdate> <checkvalue></checkvalue> <cardexpirationdate>12/20</cardexpirationdate></payment> <payment>… </payment> </result>
Пример полей вывода результата в формате CSV:
"ordernumber";"billnumber";"testmode";"ordercomment";"orderamount";"ordercurrency";"amount";"currency";"rate";"firstname";"lastname";"middlename";"email";"clientip";"ipaddress";"meantype_id";"meantypename";"meansubtype";"meannumber";"cardholder";"issuebank";"bankcountry";"orderdate";"orderstate";"responsecode";"message";"customermessage";"recommendation";"approvalcode";"protocoltypename";"processingname";"operationtype";"operationdate";"authresult";"authrequired";"slipno";"packetdate";"checkvalue";"cardexpirationdate";
"001-1";"500000000000000.1";"0";"тестовый платеж";"70.00";"USD";"137.26";"BYN";"1.9608";"Testov";"упр";"S.";"test@test.by";"10.20.10.00";"0.0.0.0";"1";"VISA";"Classic";"411111****1111";"TEST";"New Bank";"Россия";"06.07.2016 07:51:42";"Оплачен";"AS000";"Завершено успешно.";"Завершено успешно.";"";"X28577";"NET";"Fake";"100";"06.07.2016 06:39:42";"";"0";"";"06.07.2016 12:27:32";"5189407747A5435E9E7A0C06A7BC18CD";"12/20";
Пример результата запроса в формате XML, вернувшего ошибку (неправильный пароль):
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <!DOCTYPE result [...]> <result firstcode="7" secondcode="102" count="0"></result>
С описанием первого и второго кодов ошибок можно ознакомиться в Таблице "Коды ошибок". Также в соответствующих таблицах описаны возможные статусы заказа, типы операций, коды возврата и коды валют. В качестве значения поля <meannumber> возвращаются первые 6 и последние 4 цифры номера карты, остальные цифры скрыты символом *.
Описание веб-сервиса для формата SOAP можно увидеть на странице:
https://<SERVER-NAME>/resultbydate/resultbydate.wsdl
Пример ответа в формате SOAP:
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/"><soapenv:Body> <ws:resultbydateResponse><resultbydate><payment> <ordernumber>18062012_SDR</ordernumber> <billnumber>550000110000001.1</billnumber> <testmode>1</testmode> <ordercomment>тестовый платеж</ordercomment> <orderamount>21.00</orderamount> <ordercurrency>BYN</ordercurrency> <amount>21.00</amount> <currency>BYN</currency> <rate>1</rate> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>T.</middlename> <email>test@test.by</email> <clientip>10.10.10.10</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>2</meantype_id> <meantypename>MasterCard</meantypename> <meansubtype>Standart</meansubtype> <meannumber>546792****4128</meannumber> <cardholder>TEST</cardholder> <issuebank>Bank</issuebank> <bankcountry>RUS</bankcountry> <orderdate>06.07.2016 11:10:06</orderdate> <orderstate>Approved</orderstate> <responsecode>AS000</responsecode> <message>Завершено успешно. </message> <customermessage>Завершено успешно. </customermessage> <recommendation/> <approvalcode>X40334</approvalcode> <protocoltypename>NET</protocoltypename> <processingname>Fake</processingname> <operationtype>100</operationtype> <operationdate>06.07.2016 11:10:07</operationdate> <authresult/> <authrequired>0</authrequired> <slipno></slipno> <packetdate>06.07.2016 11:22:37</packetdate> <checkvalue>45A33F800F2BD16C02E3D2F5C81557A0</checkvalue> <cardexpirationdate>12/20</cardexpirationdate></payment> </resultbydate></ws:resultbydateResponse ></soapenv:Body></soapenv:Envelope>
Внимание!
Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:
- корневые сертификаты от GlobalSign (https://www.globalsign.com/repository/ca-certificates/):
- GlobalSign Root R3;
- GlobalSign ECC Root R5;
- GlobalSign Root R6;
- корневые сертификаты от Sectigo (https://www.sectigo.com/knowledge-base/detail/Sectigo-Root-Certificates/kA03l000000c4KV):
- USERTrust RSA Certification Authority;
- USERTrust ECC Certification Authority.
Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости.