www.assist.kz

Описание сервиса

URL запроса: https://<SERVER-NAME>/cancel/wscancel.cfm, при передаче параметров в формате JSON см. swagger описание: https://docs.assist.kz/swagger/https://docs.assist.ru/swagger/. 

Список параметров запроса:

Название

Обязательное поле

Принимаемые значения

Значение по умолчанию

Описание

Billnumber

Да

15 или 16 цифр

Расширенный формат


Номер платежа, соответствующий заказу в системе АПК Ассист, передача расширенного номера платежа допускается только в том случае, если в заказе не передается чек.

Merchant_ID

Да

Число


Идентификатор предприятия в АПК Ассист

Login

Да

8 - 20 символов


Логин (лат. буквы и цифры, символ _)

Password

Да

8 - 20 символов 


Пароль (лат. буквы и цифры)

Amount

Нет1

Число, 15 знаков, два знака после разделителя (допустимые разделители «.», «,»)

Сумма авторизации

Сумма возврата средств

Currency

Нет1

3 символа

Код валюты авторизации

Код валюты отмены или возврата средств. Может быть использован только код валюты авторизации

CancelReason

Нет

1 – Отказ магазина
2 – Отказ покупателя
3 – Мошенническая операция

2

Причина отмены или возврата

Language

Нет

RU – русский
EN – английский

RU

Язык выдачи результатов

ClientIP

Нет

Максимум 15 цифр, 4 разделителя «.»


IP компьютера оператора, производящего отмену/возврат.

Format

Нет

1 – CSV
3 – XML
4 – SOAP
5 - JSON 

4

Формат выдачи результата. Если запрос передан в формате SOAP или JSON, то ответ также будет в SOAP или JSON соответственно, в остальных случаях ответ выдается согласно переданному значению формата.

Externalrefundid2

Нет

От 10 до 100 символов (разрешенные символы [A-Za-z0-9\-_]


Внешний идентификатор отмены (уникальное значение в пределах одного заказа)


1 Параметры Amount, Currency могут присутствовать или отсутствовать в запросе только одновременно. В случае отсутствия параметров операция отмены оплаты будет проведена на полную сумму.


2Параметр используется только для форматов JSON и SOAP.

Примечание

Все параметры, передаваемые в запросе, проходят автоматическую валидацию в АПК Ассист. Правила валидации описаны в табл. "Правила валидации входных параметров".

Примечание

Для фискализации операции отмены в запросе могут передаваться дополнительные параметры для формирования корректного чека. Описание дополнительных параметров приведено в разделе "Режимы передачи данных чека".

Для совершения операции отмены можно передать параметр billnumber как в обычном формате (если по заказу была одна успешная операция оплаты), так и в расширенном формате. При использовании расширенного формата обязательно должен быть указан номер успешной операции оплаты (в некоторых случаях это может быть не первая по счету операция, например,5111111000965142.2). 

Внимание!

Передача расширенного номера платежа допускается только в том случае, если в заказе не передается чек.

Отмена или возврат средств является успешной, если код возврата операции отмены responsecode AS000 (операция успешно завершена), оба кода firstcode=0, secondcode=0, статус заказа при этом становится Canceled (Отменен) или PartialCanceled (Отменен частично).

Для неуспешной отмены код возврата responsecode принимает значения AS100-AS998. Если запрос на возврат или отмену не может быть обработан, в результате запроса вернутся ненулевые значения параметров firstcode, secondcode.

Тип совершаемой транзакции (on-line отмена, возврат средств (refund), отмена финансовой транзакции, частичная отмена) будет определен системой АПК Ассист автоматически в зависимости от суммы (полная или частичная отмена), процессинга, типа карты, наличия финансовой транзакции для родительской авторизации и причины возврата.

Если предприятие работает с чеком, отмены возможны только по позициям чека, отменяемые позиции чека необходимо передать в параметре ChequeItem, более подробно см. раздел о работе с чеком .

Интерфейс для формата HTTP POST 

Пример запроса HTTP POST для отмены оплаты по банковской карте:

<FORM ACTION="https://<SERVER-NAME>/cancel/wscancel.cfm" method="POST">
<INPUT TYPE="hidden" NAME="BillNumber" VALUE="511111100000001">
<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="Amount" VALUE="Сумма">
<INPUT TYPE="hidden" NAME="Currency" VALUE="Валюта">
<INPUT TYPE="hidden" NAME="ClientIP" VALUE="IP-адрес">
<INPUT TYPE="hidden" NAME="Language" VALUE="Язык выдачи результата">
<INPUT TYPE="hidden" NAME="Format" VALUE="Формат выдачи результата">
<INPUT TYPE="Submit"></FORM>

Список параметров ответа:

Название

Значение

ordernumber

Номер заказа

responsecode

Код возврата

recommendation

Рекомендации

message

Сообщение

ordercomment

Комментарий

orderdate

Дата заказа по Гринвичу (GMT)

amount

Сумма операции

currency

Валюта операции

meantypename

Тип платежного средства

meannumber

Номер платежного средства

lastname

Фамилия плательщика

firstname

Имя плательщика

middlename

Отчество плательщика

issuebank

Название банка-эмитента

Email

Email плательщика

bankcountry

Страна банка-эмитента

rate

Курс валюты

approvalcode

Код авторизации

meansubtype

Подтип платежного средства

cardholder

Держатель платежного средства

cardexpirationdate

Срок действия карты

ipaddress

IP-адрес плательщика

protocoltypename

Протокол

testmode

Тестовый режим

customermessage

Сообщение о результате для покупателя

orderstate

Cтатус заказа

processingname

Процессинг

operationtype

Тип операции

billnumber

Расширенный формат billnumber

orderamount

Оригинальная сумма операции

ordercurrency

Оригинальная валюта операции

packetdate

Дата формирования запроса по Гринвичу (GMT)

signature

Подпись. Формируется по следующему алгоритму:

1. Формируется объединённая строка из параметров (в их строковом представлении, в формате как они переданы в ответе): billnumber, ordernumber, responsecode, orderamount, ordercurrency, meannumber, approvalcode, orderstate, packetdate (без разделителей).
2. Полученная строка подписывается закрытым ключом АПК Ассист.
3. Итоговая последовательность байт кодируется в BASE64.

Пример результата запроса отмены платежа или возврата средств в формате 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 (orders?)>
<!ELEMENT orders (order)>
<!ELEMENT order (ordernumber?,
responsecode?, recommendation?, message?, ordercomment?, orderdate?, amount?,
currency?, meantypename?, meannumber?, lastname?, firstname?, middlename?,
issuebank?, email?, bankcountry?, rate?, approvalcode?, meansubtype?,
cardholder?, cardexpirationdate?, ipaddress?,
protocoltypename?, testmode?, customermessage?,
orderstate?, processingname?, operationtype?, billnumber?, orderamount?,
ordercurrency?, packetdate?, signature?, pareq?, acsurl?)>
<!ELEMENT ordernumber (#PCDATA)>
<!ELEMENT responsecode (#PCDATA)>
<!ELEMENT recommendation (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ELEMENT ordercomment (#PCDATA)>
<!ELEMENT orderdate (#PCDATA)>
<!ELEMENT amount (#PCDATA)>
<!ELEMENT currency (#PCDATA)>
<!ELEMENT meantypename (#PCDATA)>
<!ELEMENT meannumber (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!ELEMENT issuebank (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT bankcountry (#PCDATA)>
<!ELEMENT rate (#PCDATA)>
<!ELEMENT approvalcode (#PCDATA)>
<!ELEMENT meansubtype (#PCDATA)>
<!ELEMENT cardholder (#PCDATA)>
<!ELEMENT cardexpirationdate (#PCDATA)>
<!ELEMENT ipaddress (#PCDATA)>
<!ELEMENT protocoltypename (#PCDATA)>
<!ELEMENT testmode (#PCDATA)>
<!ELEMENT customermessage (#PCDATA)>
<!ELEMENT orderstate (#PCDATA)>
<!ELEMENT processingname (#PCDATA)>
<!ELEMENT operationtype (#PCDATA)>
<!ELEMENT billnumber (#PCDATA)>
<!ELEMENT orderamount (#PCDATA)>
<!ELEMENT ordercurrency (#PCDATA)>
<!ELEMENT packetdate (#PCDATA)>
<!ELEMENT signature (#PCDATA)>
<!ELEMENT pareq (#PCDATA)>
<!ELEMENT acsurl (#PCDATA)>]>
<result firstcode="0" secondcode="0" count="1">
<orders><order>
<ordernumber>0001-01</ordernumber>
<responsecode>AS000</responsecode>
<recommendation></recommendation>
<message>Завершено успешно.</message>
<ordercomment>тестовый платеж</ordercomment>
<orderdate>01.01.2018 10:51:53</orderdate>
<amount>100.00</amount>
<currency>KZT</currency>
<meantypename>VISA</meantypename>
<meannumber>411111****1111</meannumber>
<lastname>Testov</lastname>
<firstname>Test</firstname>
<middlename>Testovich</middlename>
<issuebank>BANK</issuebank>
<email>test@testpost.kz</email>
<bankcountry>Казахстан</bankcountry>
<rate>1</rate>
<approvalcode>F39530</approvalcode>
<meansubtype>Corporate Purchasing Card</meansubtype>
<cardholder>TEST</cardholder>
<cardexpirationdate>12/20</cardexpirationdate>
<ipaddress>10.23.23.23</ipaddress>
<protocoltypename></protocoltypename>
<testmode>1</testmode>
<customermessage>Завершено успешно.</customermessage>
<orderstate>Canceled</orderstate>
<processingname>Name</processingname>
<operationtype>300</operationtype>
<billnumber>511111100000001.2</billnumber>
<orderamount>100.00</orderamount>
<ordercurrency>KZT</ordercurrency>
<packetdate>01.01.2018 12:36:31</packetdate>
<signature></signature>
</order></orders></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

Описание веб-сервиса для формата SOAP можно увидеть на странице:

https://<SERVER-NAME>/cancel/wscancel.wsdl

Пример запроса для отмены оплаты по банковской карте:

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Header/>
    <Body>
        <WSCancelRequestParams>
            <merchant_id xmlns="">423422</merchant_id>
            <billnumber xsi:type="xsd:string" xmlns="">500000210031071.1</billnumber>
            <login xsi:type="xsd:string" xmlns="">login</login>
            <password xsi:type="xsd:string" xmlns="">password</password>
            <amount xsi:type="xsd:string" xmlns="">23.23</amount>
            <currency xsi:type="xsd:string" xmlns="">KZT</currency>
        </WSCancelRequestParams>
    </Body>
</Envelope>

Список параметров ответа:

Название

Значение

Параметры заказа (секция <order>)

billnumber

Уникальный номер заказа в системе АПК Ассист

ordernumber

Номер заказа

testmode

Тестовый режим

ordercomment

Комментарий

orderamount

Оригинальная сумма заказа

ordercurrency

Оригинальная валюта заказа

rate

Курс валюты

orderdate

Дата заказа по Гринвичу (GMT)

orderstate

Статус заказа

Данные о плательщике (секция <customer>)

firstname

Имя плательщика

lastname

Фамилия плательщика

middlename

Отчество плательщика

email

Email плательщика

Параметры операции (повторяющаяся секция <operation>)

billnumber

Уникальный номер операции (расширенный формат: billnumber.<номер операции>)

operationtype

Код типа операции

operationstate

Состояние операции

amount

Сумма операции

currency

Валюта операции

ipaddress

IP-адрес плательщика

meantype_id

Тип платежного средства

meansubtype

Подтип платежного средства

meannumber

Номер платежного средства

cardholder

Держатель платежного средства

cardexpirationdate

Срок действия карты

issuebank

Название банка-эмитента

bankcountry

Страна банка-эмитента

responsecode

Код возврата

message

Сообщение о результате операции

customermessage

Сообщение о результате для покупателя

recommendation

Рекомендация

approvalcode

Код авторизации

protocoltypename

Протокол

processingname

Процессинг

operationdate

Дата и время операции (GMT)

Свойства пакета данных (внутри <result>)

packetdate

Дата формирования запроса по Гринвичу (GMT)

signature

Подпись. Формируется по следующему алгоритму:

1. Формируется объединённая строка из параметров (в их строковом представлении, в формате как они переданы в ответе): billnumber, ordernumber, responsecode, orderamount, ordercurrency, meannumber, approvalcode, orderstate, packetdate (без разделителей).
2. Полученная строка подписывается закрытым ключом АПК Ассист.
3. Итоговая последовательность байт кодируется в BASE64.

Пример результата запроса отмены платежа или возврата средств:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ws="http://www.paysecure.kz/ws/">
<soapenv:Body><ws:WSCancelResponseParams>
        <order>
            <billnumber>500000210031071</billnumber>
            <ordernumber>14092012-002</ordernumber>
            <testmode>0</testmode>
            <ordercomment>тестовый платеж</ordercomment>
            <orderamount>4010.00</orderamount>
            <ordercurrency>KZT</ordercurrency>
            <rate>1</rate>
            <orderdate>14.09.2017 09:29:38</orderdate>
            <orderstate>Canceled</orderstate>
            <customer>
                <firstname>Testov</firstname>
                <lastname>Test</lastname>
                <middlename>T</middlename>
                <email>test@test.kz</email>
            </customer>
            <operation>
                <billnumber>500000210031071.3</billnumber>
                <operationtype>300</operationtype>
                <operationstate>Завершено успешно.</operationstate>
                <amount>4010.00</amount>
                <currency>KZT</currency>
                <ipaddress>10.10.10.10</ipaddress>
                <meantype_id>1</meantype_id>
                <meansubtype></meansubtype>
                <meannumber>411111****1111</meannumber>
                <cardholder>TEST</cardholder>
                <cardexpirationdate>12/20</cardexpirationdate>
                <issuebank>Bank T</issuebank>
                <bankcountry>Россия</bankcountry>
                <responsecode>AS000</responsecode>
                <message></message>
                <customermessage>Завершено успешно</customermessage>
                <recommendation></recommendation>
                <approvalcode>X34209</approvalcode>
                <protocoltypename></protocoltypename>
                <processingname>Fake</processingname>
                <operationdate>14.09.2017 09:33:51</operationdate>
            </operation>
        </order>
        <packetdate>14.09.2017 09:33:57</packetdate>
        <signature>kA0DAAIRzfHw5YyCW...bQnThrGPVGBK6gh9bxUl1w==</signature>
  </ws:WSCancelResponseParams></soapenv:Body>
</soapenv:Envelope>

Пример результата запроса, вернувшего ошибку (неверная сумма):

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><soapenv:Fault><faultcode>soapenv:Server.generalException</faultcode><faultstring/><detail><ns:WSException
xmlns:ns="http://www.paysecure.kz/ws/">
<firstcode>5</firstcode><secondcode>108</secondcode>
</ns:WSException></detail>
</soapenv:Fault></soapenv:Body></soapenv:Envelope>


Наверх