Назначение и основные особенности счетов
Сервисы выставления и оплаты счетов предоставляют предприятию простую возможность организовать оплату по ссылке, перейдя по которой клиент сможет оплатить заказ в системе АПК Ассист. Предприятие вызывает веб-сервис создания счета (с указанием номера счета, суммы, допустимого срока оплаты и т. д.), АПК Ассист формирует счет на оплату и платежный токен, соответствующий данному счету. Создание счета также возможно вручную из личного кабинета (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: