Назначение и основные особенности счетов
Сервисы выставления и оплаты счетов предоставляют предприятию простую возможность организовать оплату по ссылке, перейдя по которой клиент сможет оплатить заказ в системе АПК Ассист. Предприятие вызывает веб-сервис создания счета (с указанием номера счета, суммы, допустимого срока оплаты и т. д.), АПК Ассист формирует счет на оплату и платежный токен, соответствующий данному счету. Создание счета также возможно вручную из личного кабинета (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
Список параметров запроса:
Название | Обязательное поле | Принимаемые значения | Значение по умолчанию | Описание |
Merchant_ID | Да | Число | Идентификатор предприятия в АПК Ассист | |
Login | Да | 8 - 20 символов | Логин (лат. буквы и цифры, символ _) | |
Password | Да | 8 - 20 символов | Пароль (лат. буквы и цифры) | |
Bill | Да/Нет1 | 128 символов | Номер счета (при создании заказа будет использован в качестве OrderNumber) | |
Bill_amount | Да | Число, 15 цифр (разделитель «.») | Сумма счета (OrderAmount в заказе) | |
Bill_currency | Да | 3 символа | Валюта счета (OrderCurrency) | |
Bill_comment | Нет | 256 символов | Комментарий (OrderComment в заказе) | |
Customer_Name | Нет | 70 символов | Имя плательщика (FirstName в заказе) | |
Customer_Lastname | Нет | 70 символов | Фамилия плательщика (LastName в заказе) | |
Customer_Middlename | Нет | 70 символов | Отчество плательщика (MiddleName в заказе) | |
Customer_Email | Да/Нет2 | 128 символов | E-mail плательщика (Email в заказе) | |
Customer_Phone | Нет | 20 символов | Телефон плательщика (HomePhone в заказе) | |
Customer_Mobile | Нет | 20 символов | Мобильный телефон плательщика (MobilePhone в заказе) | |
Language | Нет | RU EN | Настройка базового языка аккаунта мерчанта | Язык платежных страниц |
Pay_until | Нет | Дата/время | 1 сутки | Крайний срок оплаты счета (дата и время в GMT): YYYYMMDDThhmm, если не передано - вычисляется на основе настройки мерчанта |
DelayPayment | Нет | Число | 0 | Флаг двустадийного платежа (параметр delay в заказе): 0- одностадийный, 1 - двустадийный режим оплаты. |
SendNotification | Нет | Число | В зависимости от настроек мерчанта | Признак отправки счета: 0 - не отправлять, 1 – отправлять ссылку по Email, 2 – отправлять ссылку в SMS, 3 – отправлять ссылку и по Emai, и в SMS. |
URL_RETURN | Нет | 255 символов | URL страницы, на которую должен вернуться покупатель после осуществления платежа в системе (должна быть активирована опция «Перейти на страницу магазина» в настройках мерчанта в Личном кабинете). В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS. | |
URL_RETURN_OK | Нет | 255 символов | Значение параметра URL_RETURN, а при его отсутствии – URL для возврата при успешной авторизации, указанный в Личном кабинете | URL страницы, куда должен вернуться покупатель после успешного осуществления платежа в системе АПК Ассист (должна быть активирована опция «Перейти на страницу магазина» в настройках мерчанта в Личном кабинете). В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS. |
URL_RETURN_NO | Нет | 255 символов | Значение параметра URL_RETURN, а при его отсутствии – URL для возврата, указанный в Личном кабинете | URL страницы, куда должен вернуться покупатель после неуспешного осуществления платежа в системе АПК Ассист или при отсутствии ответа об окончательном статусе платежа (текущий статус "В процессе"), подробнее см. "Возврат покупателя на страницу интернет-магазина после покупки". Должна быть активирована опция «Возвращаться в магазин по URL для возврата» в Личном кабинете. В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS. |
Checkvalue | Да/Нет | Строка | Контрольная сумма3 | |
CustomerNumber | Нет | Строка | Идентификационный номер клиента магазина (для организации платежей в режиме OneClick). |
1 Номер счета может не передаваться, если включена автоматическая генерация номера счета.
2 Если не передано значение адреса E-mail, то отправка счета по E-mail невозможна. Если не передан номер телефона, то отправка SMS невозможна. Примечание. Если признак отправки равен 3, то при отсутствии номера телефона ссылка на счет будет отправлена только по E-mail, а при отсутствии адреса E-mail нотификация вообще не будет выполнена.
3 Контрольная сумма формируется на основе формулы:
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>
Список параметров ответа:
Название | Значение |
Hash | Платежный токен/ID счета |
Пример результата запроса для создания счета в формате 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
Список параметров запроса: