В том случае, если предприятию недостаточно только информации о статусе заказа (оплачен, отменен, ожидает подтверждения оплаты), а необходима также детальная информация об операциях (оплаты, подтверждения оплаты, возврата или отмены), совершенных по данному заказу, предприятие может воспользоваться веб-сервисом получения результатов операций по номеру заказа.
Для получения результата платежа по номеру заказа нужно отправить запрос на сервер АПК Ассист методом HTTP POST, SOAP (в кодировке UTF-8) или в формате JSON (swagger описание: https://docs.assist.kz/swagger/).
URL запроса для получения результата оплаты с перечнем операций по заказу:
https://<SERVER-NAME>/orderresult/orderresult.cfm.
Поиск заказа при помощи веб-сервиса производится только за указанный промежуток времени (во временной зоне GMT). По умолчанию за дату окончания выборки принимается текущая дата, а за дату начала выборки – текущая дата минус три дня. Выборка осуществляется по дате заказа.
Список параметров запроса:
Название | Обязательное поле | Принимаемые значения | Значение по умолчанию | Описание |
Ordernumber | Да | Строка, 128 символов | Номер заказа | |
Merchant_ID | Да | Число | Идентификатор предприятия в АПК Ассист | |
Login | Да | 8 - 20 символов | Логин (лат. буквы и цифры, символ _) | |
Password | Да | 8 - 20 символов | Пароль (лат. буквы и цифры) | |
StartYear | Нет | Год в формате YYYY | Минус 3 дня от текущей даты | Дата начала выборки по Гринвичу (GMT) |
StartMonth | Нет | 1-12 | Минус 3 дня от текущей даты | |
StartDay | Нет | 1-31 | Минус 3 дня от текущей даты | |
StartHour | Нет | 0-23 | Минус 3 дня от текущей даты | |
StartMin | Нет | 0-59 | Минус 3 дня от текущей даты | |
EndYear | Нет | Год в формате YYYY | Текущий год | Дата окончания выборки по Гринвичу (GMT) |
EndMonth | Нет | 1-12 | Текущий месяц | |
EndDay | Нет | 1-31 | Текущий день | |
EndHour | Нет | 0-23 | Текущий час | |
EndMin | Нет | 0-59 | Текущая минута | |
Language | Нет | RU EN | EN | Язык вывода результатов |
Format | Да/Нет | 3 – XML | 3 | Формат выдачи результатов. Передается только для запроса в формате POST (по умолчанию ответ будет выдан в формате XML). Для других форматов ответ выдается в том же формате, в котором был выполнен запрос. |
Все параметры, передаваемые в запросе, проходят автоматическую валидацию в АПК Ассист. Правила валидации описаны в табл. "Правила валидации входных параметров". |
Пример запроса для формата HTTP POST:
<FORM ACTION="https://<SERVER-NAME>/orderresult/orderresult.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="Ordernumber" VALUE="1001-01"> <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="Startyear" VALUE="2018"> <INPUT TYPE="HIDDEN" NAME="Startmonth" VALUE="04"> <INPUT TYPE="HIDDEN" NAME="Startday" VALUE="01"> <INPUT TYPE="HIDDEN" NAME="Starthour" VALUE="00"> <INPUT TYPE="HIDDEN" NAME="Startmin" VALUE="00"> <INPUT TYPE="HIDDEN" NAME="Endyear" VALUE="2018"> <INPUT TYPE="HIDDEN" NAME="Endmonth" VALUE="04"> <INPUT TYPE="HIDDEN" NAME="Endday" VALUE="02"> <INPUT TYPE="HIDDEN" NAME="Endhour" VALUE="00"> <INPUT TYPE="HIDDEN" NAME="Endmin" VALUE="00"> <INPUT TYPE="HIDDEN" NAME="Format" VALUE="3"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="EN"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Выполнить"> </FORM> |
Список параметров ответа:
Название | Значение |
Параметры заказа | |
billnumber | Уникальный номер заказа в системе АПК Ассист |
ordernumber | Номер заказа |
testmode | Тестовый режим |
ordercomment | Комментарий |
orderamount | Оригинальная сумма заказа |
ordercurrency | Оригинальная валюта заказа |
firstname | Имя плательщика |
lastname | Фамилия плательщика |
middlename | Отчество плательщика |
Email плательщика | |
orderdate | Дата заказа по Гринвичу (GMT) |
orderstate | Статус заказа |
errorcode2 | |
packetdate | Дата формирования запроса по Гринвичу (GMT) |
signature | 1) Для типа подписи MD5 - пусто 2) Для типа PGP – значение X, подписанное закрытым ключом АПК Ассист, закодированное в BASE64 |
checkvalue | 1) Для типа подписи PGP - пусто 2) Для типа MD5 – uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки параметров merchant_id, ordernumber, orderamount, ordercurrency, orderstate (без разделителей), + строковая склейка |
errorcategory3 | Категория ответов при неуспешных оплатах, полученная от VISA |
merchantadvicecode3 | |
Параметры операции | |
billnumber | Расширенный формат billnumber |
operationtype | Тип операции |
operationstate | Состояние операции |
amount | Сумма операции |
currency | Валюта операции |
ipaddress | IP-адрес плательщика |
clientip | IP-адрес совершившего операцию |
meantype_id | Тип платежного средства |
meansubtype | Подтип платежного средства |
meannumber | Номер платежного средства |
cardholder | Держатель платежного средства |
cardexpirationdate | Срок действия карты |
issuebank | Название банка-эмитента |
bankcountry | Страна банка-эмитента |
responsecode | Код возврата |
message | Сообщение о результате операции |
customermessage | Сообщение о результате для покупателя |
recommendation | Рекомендация |
approvalcode | Код авторизации |
protocoltypename | Протокол |
processingname | Процессинг |
operationdate | Дата и время операции (GMT) |
authresult | Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U – неизвестно, R- отказ, C – не завершено по каким-либо причинам, E - ошибка) |
authrequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – ошибка при определении вовлеченности) |
slipno | Номер финансовой транзакции, отправляемый в процессинг |
errorcode2 | |
chequeItems1 | Строка с позициями чека в JSON формате согласно разделу Работа с чеком. |
extrrn3 | Уникальный номер платежа в процессинге |
externalrefundid4 | Внешний идентификатор отмены |
Параметры 3DSecure | |
version | Версия протокола 3DSecure |
alphaauthresult | Результат авторизации (Y - успешно, N - неуспешно, A - Attempt, U – невозможно провести аутентификацию, R- отказ, C – не завершено по каким-либо причинам, E - ошибка, I - для информации) |
challenge | Взаимодействие с держателем карты (C – было, F – не было, D - отложенная аутентификация) |
eci | Electronic Commerce Indicator (5 – полная аутентификация, 6 – попытка аутентификации, 7 – без аутентификации) |
1Позиции заказа, передаются только при включенной настройке «Отправлять позиции заказа» в ЛК АПК Ассист.
2Для передачи параметра необходимо обратиться в службу поддержки (support@assist.kz).
Параметр полезен для заказов в статусах Declined и Timeout, он помогает идентифицировать ошибку оплаты (например, построить отчет по разным ошибкам), но не определяет статус оплаты. Он будет присутствовать как в блоке данных, относящихся к операции (operation), так и в блоке данных, относящихся к заказу (order). В большинстве случаев для заказа параметр errorcode будет иметь значение 0. Это не означает, что заказ успешно оплачен. Это означает, что нет кода ошибки на уровне заказа. Статус оплаты определяется статусом заказа orderstate и кодом возврата responsecode. Кроме того, может быть создан (и впоследствии закрыт с ошибкой) заказ, не содержащий операции. Пример результата запроса по заказу без операции:
Пример результата запроса по заказу с операцией:
|
3Для передачи параметра необходимо обратиться в службу поддержки (support@assist.kz).
4Параметр передается только в том случае, если он был передан в запросе на отмену с помощью сервиса wscancel и формат выдачи результатов запроса JSON или XML.
В рамках одного заказа может быть проведено несколько операций (оплаты, подтверждения оплаты, отмены). Более того, в рамках одного заказа может быть несколько операций оплаты, если некоторые из них были неуспешными. Успешная операция оплаты заказа может быть только одна. В этих случаях в ответе на запрос о результатах операций по номеру заказа может быть несколько вложенных операций для одного номера заказа. |
В полученном ответе необходимо проверить значение параметра 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 (order*)> <!ELEMENT order (ordernumber?,billnumber?,testmode?,ordercomment?,orderamount?,ordercurrency?,firstname?,lastname?,middlename?,email?,orderdate?,orderstate?,packetdate?,signature?,checkvalue?,operation*)> <!ELEMENT ordernumber (#PCDATA)> <!ELEMENT billnumber (#PCDATA)> <!ELEMENT testmode (#PCDATA)> <!ELEMENT ordercomment (#PCDATA)> <!ELEMENT orderamount (#PCDATA)> <!ELEMENT ordercurrency (#PCDATA)> <!ELEMENT firstname (#PCDATA)> <!ELEMENT lastname (#PCDATA)> <!ELEMENT middlename (#PCDATA)> <!ELEMENT email (#PCDATA)> <!ELEMENT orderdate (#PCDATA)> <!ELEMENT orderstate (#PCDATA)> <!ELEMENT packetdate (#PCDATA)> <!ELEMENT signature (#PCDATA)> <!ELEMENT checkvalue (#PCDATA)> <!ELEMENT operation (billnumber?,operationtype?,operationstate?,amount?,currency?,clientip?,ipaddress?,meantype_id?,meantypename?,meansubtype?,meannumber?,cardholder?,cardexpirationdate?,issuebank?,bankcountry?,responsecode?,message?,customermessage?,recommendation?,approvalcode?,protocoltypename?,processingname?,operationdate?,authresult?,authrequired?)> <!ELEMENT operationtype (#PCDATA)> <!ELEMENT operationstate (#PCDATA)> <!ELEMENT amount (#PCDATA)> <!ELEMENT currency (#PCDATA)> <!ELEMENT clientip (#PCDATA)> <!ELEMENT ipaddress (#PCDATA)> <!ELEMENT meantype_id (#PCDATA)> <!ELEMENT meantypename (#PCDATA)> <!ELEMENT meansubtype (#PCDATA)> <!ELEMENT meannumber (#PCDATA)> <!ELEMENT cardholder (#PCDATA)> <!ELEMENT cardexpirationdate (#PCDATA)> <!ELEMENT issuebank (#PCDATA)> <!ELEMENT bankcountry (#PCDATA)> <!ELEMENT responsecode (#PCDATA)> <!ELEMENT message (#PCDATA)> <!ELEMENT customermessage (#PCDATA)> <!ELEMENT recommendation (#PCDATA)> <!ELEMENT approvalcode (#PCDATA)> <!ELEMENT protocoltypename (#PCDATA)> <!ELEMENT processingname (#PCDATA)> <!ELEMENT operationdate (#PCDATA)> <!ELEMENT authresult (#PCDATA)> <!ELEMENT authrequired (#PCDATA)> <result firstcode='0' secondcode='0' count='1'> <order> <ordernumber>0001-01</ordernumber> <billnumber>511111100000001</billnumber> <testmode>1</testmode> <ordercomment>тестовый платеж</ordercomment> <orderamount>100.00</orderamount> <ordercurrency>KZT</ordercurrency> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>Testovich</middlename> <email>test@testpost.kz</email> <orderdate>01.01.2018 11:23:13</orderdate> <orderstate>Approved</orderstate> <packetdate>01.01.2011 12:05</packetdate> <signature></signature> <checkvalue></checkvalue> <operation> <billnumber>511111100000001.1</billnumber> <operationtype>100</operationtype> <operationstate>Success</operationstate> <amount>100.00</amount> <currency>KZT</currency> <clientip>111.23.11.23</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>1</meantype_id> <meantypename>VISA</meantypename> <meansubtype>Classic</meansubtype> <meannumber>411111****1111</meannumber> <cardholder>TEST</cardholder> <cardexpirationdate>12/20</cardexpirationdate> <issuebank>New Bank</issuebank> <bankcountry>Казахстан</bankcountry> <responsecode>AS000</responsecode> <message></message> <customermessage> </customermessage> <recommendation></recommendation> <approvalcode>F41412</approvalcode> <protocoltypename>NET</protocoltypename> <processingname>Name</processingname> <operationdate>01.01.2018 11:24:13</ operationdate> <authresult>Y</authresult> <authrequired>1</authrequired> <slipno>111111</slipno></operation> <threedsdata> <version>1.0.0</version> <alphaauthresult>Y</alphaauthresult> <challenge>C</challenge> <eci>5</eci> </threedsdata> <operation> <billnumber>511111100000001.2</billnumber> <operationtype>200</operationtype> <operationstate>Success</operationstate> <amount>100.00</amount> <currency>KZT</currency> <clientip>111.23.11.23</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>1</meantype_id> <meantypename>VISA</meantypename> <meansubtype>Classic</meansubtype> <meannumber>411111****1111</meannumber> <cardholder>TEST</cardholder> <cardexpirationdate>12/20</cardexpirationdate> <issuebank>New Bank</issuebank> <bankcountry>Казахстан</bankcountry> <responsecode>AS000</responsecode> <message></message> <customermessage> </customermessage> <recommendation></recommendation> <approvalcode></approvalcode> <protocoltypename></protocoltypename> <processingname>Name</processingname> <operationdate>01.02.2018 19:24:13</operationdate> <authresult></authresult> <authrequired></authrequired> </operation></order></result> |
Пример результата запроса в формате 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>/orderresult/orderresult.wsdl.
Если попытка оплаты заказа была неуспешной (не прошла авторизация платежного средства или превышено время ожидания), то при повторной попытке оплаты будет создан новый уникальный номер (billnumber) в АПК Ассист для того же номера заказа в интернет-магазине. При этом в ответе на запрос будут присутствовать все операции по данному заказу для всех соответствующих уникальных номеров в АПК Ассист в порядке их осуществления. |
Пример ответа в формате 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:orderresultResponse><orderresult> <order> <ordernumber>13032014_122</ordernumber> <billnumber>5500069208498005</billnumber> <testmode>1</testmode> <ordercomment>тестовый платеж</ordercomment> <orderamount>122.00</orderamount> <ordercurrency>KZT</ordercurrency> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>T.</middlename> <email>test@test.kz</email> <orderdate>13.03.2018 13:38:24</orderdate> <orderstate>Timeout</orderstate> <packetdate>13.03.2018 14:55</packetdate> <signature></signature> <checkvalue>863F176DC699131758B2230EA93BC911</checkvalue> </order> <order> <ordernumber>13032014_122</ordernumber> <billnumber>5500069208498070</billnumber> <testmode>1</testmode> <ordercomment>тестовый платеж</ordercomment> <orderamount>122.00</orderamount> <ordercurrency>KZT</ordercurrency> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>T.</middlename> <email>test@test.kz</email> <orderdate>13.03.2018 14:52:09</orderdate> <orderstate>Approved</orderstate> <packetdate>13.03.2018 14:55</packetdate> <signature></signature> <checkvalue>E458CD73F1AA3F994F4D97C40613FD0A</checkvalue> <operation> <billnumber>5500069208498070.1</billnumber> <operationtype>100</operationtype> <operationstate>Success</operationstate> <amount>122.00</amount> <currency>KZT</currency> <clientip>10.10.10.10</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>1</meantype_id> <meantypename>VISA</meantypename> <meansubtype>Busines</meansubtype> <meannumber>462710****4724</meannumber> <cardholder>TEST</cardholder> <cardexpirationdate>12/20</cardexpirationdate> <issuebank>Bank</issuebank> <bankcountry>Казахстан</bankcountry> <responsecode>AS000</responsecode> <message></message> <customermessage></customermessage> <recommendation></recommendation> <approvalcode>X53576</approvalcode> <protocoltypename>NET</protocoltypename> <processingname>Fake</processingname> <operationdate>13.03.2018 14:52:10</operationdate> <authresult></authresult> <authrequired>0</authrequired> <threedsdata> <version>1.0.0</version> <alphaauthresult>C</alphaauthresult> <challenge>C</challenge> <eci></eci> </threedsdata> </operation> <operation> <billnumber>5500069208498070.2</billnumber> <operationtype>200</operationtype> <operationstate>Success</operationstate> <amount>122.00</amount> <currency>KZT</currency> <clientip>10.10.10.10</clientip> <ipaddress>0.0.0.0</ipaddress> <meantype_id>1</meantype_id> <meantypename>VISA</meantypename> <meansubtype>Busines</meansubtype> <meannumber>462710****4724</meannumber> <cardholder>TEST</cardholder> <cardexpirationdate>12/20</cardexpirationdate> <issuebank>Bank</issuebank> <bankcountry>Казахстан</bankcountry> <responsecode>AS000</responsecode> <message></message> <customermessage></customermessage> <recommendation></recommendation> <approvalcode></approvalcode> <protocoltypename></protocoltypename> <processingname>Fake</processingname> <operationdate>13.03.2018 14:53:37</operationdate> <authresult></authresult> <authrequired>0</authrequired> <threedsdata> <version>1.0.0</version> <alphaauthresult>Y</alphaauthresult> <challenge>C</challenge> <eci>5</eci> </threedsdata> </operation> </order> </orderresult></ws:orderresultResponse></soapenv:Body></soapenv:Envelope> |
Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:
Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости. |