www.belassist.by

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

URL запроса для формата HTTP POST: https://<SERVER-NAME>/cancel/cancel.cfm

URL запроса для формата SOAP: https://<SERVER-NAME>/cancel/wscancel.cfm, параметры передаются SOAP запросом, либо в формате JSON (swagger описание: https://docs.belassist.by/swagger/). 

Если предприятие использует такие сценарии оплаты, при которых в одном заказе могут быть две успешные операции оплаты (например,  оплата с выполненной ранее предоплатой или оплата с предоставлением скидки), то для совершения отмены необходимо пользоваться сервисом wscancel, который возвращает в ответе результат отмены для каждой операции отдельно во вложенных секциях <operation>.

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

Название

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

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

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

Описание

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

Формат входных данных

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

Externalrefundid

Нет2

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


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

Customer

Нет3

Структура данных


Параметры покупателя


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


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


3Параметр необходим только для отмен платежей по ЕРИП.

В структуре передаются следующие параметры получателя:

Название

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

Тип значения

Описание

bankcode

Да

int

Условный номер участника расчетов, присваиваемый банкам национальной платежной системы РБ (банка получателя)

accountnumber

Да

string(50)

Номер лицевого счета клиента системы «Расчет».

firstname

Нет

string(29)

Имя клиента системы «Расчет».

lastname

Нет

string(29)

Фамилия клиента системы «Расчет»

secondname

Нет

string(29)

Отчество клиента системы «Расчет».

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

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

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

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

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

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

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

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

<FORM ACTION="https://<SERVER-NAME>/cancel/cancel.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

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

slipno

Номер финансовой транзакции, отправляемый в процессинг (обычно не используется)

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?, slipno?, 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 cardholder (#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 slipno (#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>06.07.2016 10:51:53</orderdate> 
<amount>100.00</amount> 
<currency>BYN</currency> 
<meantypename>VISA</meantypename> 
<meannumber>411111****1111</meannumber> 
<lastname>Testov</lastname> 
<firstname>Test</firstname> 
<middlename>Testovich</middlename> 
<issuebank>BANK</issuebank> 
<email>test@testpost.by</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>BYN</ordercurrency> 
<slipno></slipno>
<packetdate>06.07.2016 12:36:31</packetdate> 
<signature></signature> 
</order></orders></result>

Примечание. Поле <slipno> используется только для процессинга Мультикарта. Возможные значения этого параметра в ответах описаны в справочнике.

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

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
<!DOCTYPE result [...]> 
<result firstcode="7" secondcode="102" count="0"></result>

С описанием первого и второго кодов ошибок можно ознакомиться в справочнике. Также в справочниках описаны возможные статусы заказа, типы операций, коды возврата и коды валют соответственно. В качестве значения поля <meannumber> возвращаются первые 6 и последние 4 цифры номера карты, остальные цифры скрыты символом *.

Веб-сервис для формата SOAP (wscancel)

Описание веб-сервиса для формата 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="">BYN</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)

slipno

Номер финансовой транзакции, отправляемый в процессинг (обычно не используется)

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

packetdate

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

signature

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

1. Формируется объединённая строка из параметров (в их строковом представлении, в формате как они переданы в ответе): merchant_id, ordernumber, orderamount, ordercurrency, orderstate, packetdate (без разделителей)

2. Полученная строка подписывается закрытым ключом АПК Ассист.

3. Итоговая последовательность байт кодируется в BASE64.

Примечание. Поле <slipno> используется только для процессинга Мультикарта. Возможные значения этого параметра в ответах описаны в справочнике.

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
    <soapenv:Body><ws:WSCancelResponseParams>
        <order>
            <billnumber>500000210031071</billnumber>
            <ordernumber>14092012-002</ordernumber>
            <testmode>0</testmode>
            <ordercomment>тестовый платеж</ordercomment>
            <orderamount>4010.00</orderamount>
            <ordercurrency>BYN</ordercurrency>
            <rate>1</rate>
            <orderdate>06.07.2016 09:29:38</orderdate>
            <orderstate>Canceled</orderstate>
            <customer>
                <firstname>Testov</firstname>
                <lastname>Test</lastname>
                <middlename>T</middlename>
                <email>test@test.by</email>
            </customer>
            <operation>
                <billnumber>500000210031071.3</billnumber>
                <operationtype>300</operationtype>
                <operationstate>Завершено успешно.</operationstate>
                <amount>4010.00</amount>
                <currency>BYN</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>06.07.2016 09:33:51</operationdate>
                 <slipno></slipno>
            </operation>
        </order>
        <packetdate>06.07.2016 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.ru/ws/">
<firstcode>5</firstcode><secondcode>108</secondcode>
</ns:WSException></detail>
</soapenv:Fault></soapenv:Body></soapenv:Envelope>

Пример запроса для отмены оплаты по системе «Расчет» (АИС ЕРИП):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
   <soapenv:Body>
        <ws:WSCancelRequestParams>
            <billnumber>5481287255582736</billnumber>
            <merchant_id>481287</merchant_id>
            <login>login</login>
            <password>password</password>
            <amount>50</amount>
   <currency>BYN</currency>
   <bankcode>444</bankcode>
   <accountnumber>BY11AAAA1234123412341234123445</accountnumber>
   <firstname>Ivan</firstname>
   <lastname>Ivanov</lastname>

        </WSCancelRequestParams>
    </soapenv:Body>
</soapenv:Envelope>

Отмена возможна только после проведения ежедневной сверки с АИС ЕРИП. Попытка провести отмену до осуществления сверки вызывает появление ошибок «15 - Запрещенная операция» и «308 - Операция отмены».

Пример результата запроса, отправленного до сверки:

<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.ru/ws/">
                <firstcode>15</firstcode>
                <secondcode>308</secondcode>
            </ns:WSException>
          </detail>
      </soapenv:Fault>
</soapenv:Envelope>


Наверх