Работа со счетами

Назначение и основные особенности счетов

Сервисы выставления и оплаты счетов предоставляют предприятию простую возможность организовать оплату по ссылке, перейдя по которой клиент сможет оплатить заказ в системе АПК Ассист. Предприятие вызывает веб-сервис создания счета (с указанием номера счета, суммы, допустимого срока оплаты и т. д.), АПК Ассист формирует счет на оплату и платежный токен, соответствующий данному счету. Создание счета также возможно вручную из личного кабинета (https://account.paysec.by/). Ссылка с платежным токеном отправляется системой АПК Ассист покупателю по электронной почте или предприятие формирует URL с использованием полученного платежного токена и переадресовывает покупателя на страницу оплаты счета. Также предприятие самостоятельная может отправить ссылку покупателю с помощью E-mail, SMS или других средств связи. Ссылка на оплату счета имеет следующий вид: https://<SERVER_NAME>/bill/paybill.cfm?ID=c2RmZ2UzNXkyNXR5MjU0

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

В данном разделе описывается процесс подключения сервисов выставления и оплаты счетов для предприятия, а также освещаются вопросы настройки технического взаимодействия с этими сервисами АПК Ассист.

Порядок действий предприятия при подключении сервисов выставления и оплаты счетов

• сделать заявку для подключения к функционалу выставления и оплаты счетов в службу технической поддержки АПК Ассист support@belassist.by;
• получить подтверждение от службы технической поддержки АПК Ассист о том, что все необходимые технические настройки для функционирования сервисов выставления и оплаты счетов при оплате товаров и услуг данному предприятию выполнены.

Cоздание счета (createbill)

Веб-сервис для создания счета принимает параметры счета в формате HTTP POST/SOAP либо JSON (swagger описание: https://docs.assist.ru/swagger/) и возвращает (в случае успешного создания счета) платежный токен/ID, соответствующий данному счету. На основе этого платежного токена предприятие может сформировать ссылку на своей стороне для переадресации покупателя на страницу оплаты счета или для самостоятельной отправки ее покупателю (E-mail, SMS или другие средства связи), или АПК Ассист может отправить ее по E-mail адресу покупателя, указанному в параметрах.

URL запроса для создания счета:

https://<SERVER-NAME>/bill/createbill.cfm

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

¹ Номер счета может не передаваться, если включена автоматическая генерация номера счета.

² Если не передано значение адреса E-mail, то отправка счета по E-mail невозможна. Если не передан номер телефона, то отправка SMS невозможна. Примечание. Если признак отправки равен 3, то при отсутствии номера телефона ссылка на счет будет отправлена только по E-mail, а при отсутствии адреса E-mail нотификация вообще не будет выполнена.

³ Контрольная сумма формируется на основе формулы:

uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки всех переданных параметров счета (в последовательности по порядку следования параметров в таблице сверху вниз, не включая DelayPayment, SendNotification,  Checkvalue и CustomerNumber) через разделитель - точка с запятой(";"), '+' – строковая склейка.".

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

Если счет или заказ с указанным в запросе номером уже существует, то счет не создается и выдается сообщение об ошибке "Счет с указанным номером уже существует".

Если в запросе не переданы обязательные параметры или нарушены форматы передачи данных, то счет не создается и выдается сообщение об ошибке (аналогично ошибке при создании заказа с неверными/недостающими параметрами).

Если не удается создать уникальный платежный токен/ID, то счет не создается и выдается сообщение об ошибке "Не удалось сформировать уникальный платежный токен".

Информация об использовании протокола 3-D Secure 2.0 при создании платежа.

Пример запроса HTTP POST для создания счета:

<FORM ACTION="https://test.paysec.by/bill/createbill.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="Bill" VALUE="Номер счета">
<INPUT TYPE="hidden" NAME="Bill_amount" VALUE="Сумма счета">
<INPUT TYPE="hidden" NAME="Bill_currency" VALUE="Валюта счета">
<INPUT TYPE="hidden" NAME="Bill_comment" VALUE="Комментарий к счету">
<INPUT TYPE="hidden" NAME="Customer_Name" VALUE="Имя плательщика">
<INPUT TYPE="hidden" NAME="Customer_Lastname" VALUE="Фамилия плательщика">
<INPUT TYPE="hidden" NAME="Customer_Middleтame" VALUE="Отчество плательщика">
<INPUT TYPE="hidden" NAME="Customer_Email" VALUE="Email плательщика">
<INPUT TYPE="hidden" NAME="Customer_Phone" VALUE="Телефон плательщика">
<INPUT TYPE="hidden" NAME="Customer_Mobile" VALUE="Моб. телефон плательщика">
<INPUT TYPE="hidden" NAME="Language" VALUE="Язык платежных страниц">
<INPUT TYPE="hidden" NAME="Pay_until" VALUE="Срок оплаты счета">
<INPUT TYPE="hidden" NAME="SendNotification" VALUE="Флаг отправки счета">
<INPUT TYPE="hidden" NAME="Checkvalue" VALUE="Контрольная сумма">
<INPUT TYPE="Submit"></FORM>

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

Пример результата запроса для создания счета в формате CSV:

Hash: xKPWpz4ZzDe5A9anPhnN 

В формате XML:

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<result 
   firstcode="0" 
   secondcode="0" 
   count="1">
      <return>
          <Hash>akPWp08t84MTQ9anTy30</Hash>
      </return>
</result>

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

https://<SERVER_NAME>/bill/createbill.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>
        <CreateBill>
            <Bill>
                <merchant_id>423422</merchant_id>
                <login>login</login>
                <password>password</password>
                <bill>123456</bill>
                <bill_amount>100.00</bill_amount>
                <bill_currency>BYN</bill_currency>
                <bill_comment></bill_comment>
                <customer_name>Test</customer_name>
                <customer_lastname>Testov</customer_lastname>
                <customer_middlename>Testovich</customer_middlename>
                <customer_email>test@testpost.by</customer_email>
                <customer_phone></customer_phone>
                <language>RU</language>
                <pay_until>20150611T1212</pay_until>
                <sendnotification>0</sendnotification>
                <checkvalue> AA3BC3F48B7FE23988044B53AA98F169</checkvalue>
            </Bill>
        </CreateBill>
    </Body>
</Envelope>

Пример результата запроса создания счета:

<soapenv:Envelope 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <ASS-NS:BillResponse xmlns:ASS-NS="http://www.paysecure.ru/ws/">
            <return xsi:type="si:SOAPStruct" xmlns:si="http://www.paysecure.ru/type/">
                <Hash xsi:type="xsd:string">6CPV7F4a0aWQg9XsXhrS</Hash>
            </return>
        </ASS-NS:BillResponse>
    </SOAP-ENV:Body>

Запрос статуса счета (billstatus)

Сервис позволяет получить полные данные о счете, его оплате и отменам по его номеру или параметру billnumber.

Если счет не удалось найти по его номеру, выдается сообщение об ошибке "Счет не найден".

Если заказ не удалось найти по параметру billnumber, то выдается сообщение об ошибке "Счет не найден среди обработанных".

URL запроса статуса счета:

https://<SERVER-NAME>/bill/billstatus.cfm

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

* Обязательно должен быть передан один из параметров - Bill или BillNumber. Если в одном запросе переданы оба параметра, то поиск будет осуществляться по BillNumber.

Пример запроса HTTP POST для получения статуса счета:

<FORM ACTION="https://test.paysec.by/bill/createbill.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="Bill" VALUE="Номер счета">
<INPUT TYPE="hidden" NAME="BillNumber" VALUE="Номер платежа">
<INPUT TYPE="Submit"></FORM>

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

* Если при создании счета была запрошена отправка счета (с помощью передачи параметра SendNotification=1 или настроек в системе АПК Ассист), то после создания счета параметр SendNotification в ответе может иметь следующие значения:

1 - если отправка E-mail еще не состоялась (например, не указан адрес E-mail);

10 - если письмо уже было сформировано и отправлено (поставлено в очередь отправки).