Общие положения

«Система «Расчет» – автоматизированная информационная система единого расчетного и информационного пространства (ЕРИП) создана Национальным банком Республики Беларусь в целях упрощения организации приема платежей от физических и юридических лиц.

Оплата через ЕРИП позволяет оплатить покупку со своего карт-счета, используя интернет-банк, банкоматы и инфокиоски многих банков Республики Беларусь. Рассчитаться наличными через ЕРИП можно в кассах банков либо через устройства приема наличных денег (cash-in).

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

С помощью ЕРИП можно проводить платежи по требованию или авансовые платежи.

Платежи по требованию

Платежи по требованию осуществляются покупателем единовременно при покупке товара/услуги. 


Оплата по счету, выставленному с помощью веб-сервиса

Веб-сервис для создания счета принимает параметры счета (форматы HTTP POST/SOAP) и возвращает (в случае успешного создания счета) платежный токен/ID, соответствующий данному счету. АПК Ассист отправляет по E-mail адресу покупателя, указанному в параметрах, уведомление с номером заказа (платежного токена/ID) для оплаты в системе ЕРИП.

Пример подобного уведомления:

Subj

Вам выставлен счет для оплаты

Text

Здравствуйте, Тестов Тест Тестович,


Сообщаем, что для вас был сформирован счет № 15912778124 на сумму 88.80 BYN

Вы можете оплатить его в срок до 11.09.2020 16:36:55 (GMT +03:00).


Для оплаты счета воспользуйтесь системой «Расчёт» (ЕРИП).

Для быстрого поиска используйте код услуги ЕРИП (481287)

Номер заказа в системе ЕРИП: 15912778124

По всем вопросам, связанным этим счетом, пожалуйста, обращайтесь в интернет-магазин №1 по адресу: shop1@testpost.by

_____________

С уважением,

Отдел технической поддержки

ASSIST

www.belassist.by

Шаблон уведомления необходимо обсудить со службой поддержки (support@belassist.by).

Покупатель может оплатить счет в системе ЕРИП в любое время в пределах указанного срока. Для настройки срока оплаты счетов предприятию следует обратиться в службу технической поддержки (support@belassist.by).

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

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

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

Название

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

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

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

Описание

Merchant_ID

Да

Число


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

Login

Да

8 - 20 символов 


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

Password

Да

8 - 20 символов


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

Bill

Да/Нет*

30 символов (цифры и латинские буквы)


Уникальный номер счета (при создании заказа будет использован в качестве OrderNumber, а также в качестве номера для оплаты в ЕРИП)

Bill_amount

Да

Число


Сумма счета (OrderAmount в заказе)

Bill_currency

Да

Строка


Валюта счета (OrderCurrency только BYN)

Bill_comment

Нет

Строка


Комментарий (OrderComment в заказе)

Customer_Name

Нет

Строка


Имя плательщика (FirstName в заказе)

Customer_Lastname

Нет

Строка


Фамилия плательщика (LastName в заказе)

Customer_Middlename

Нет

Строка


Отчество плательщика (MiddleName в заказе)

Customer_Email

Да/Нет**

Строка


E-mail плательщика (Email в заказе)

Customer_Phone

Нет

Строка


Телефон плательщика (HomePhone в заказе)

Customer_Mobile

Нет

Строка


Мобильный телефон плательщика (MobilePhone в заказе)

Language

Нет

RU

EN

Настройка базового языка аккаунта мерчанта

Язык платежных страниц

Pay_until

Нет

Дата/время

1 сутки

Крайний срок оплаты счета (дата и время в GMT): YYYYMMDDThhmm, если не передано - вычисляется на основе настройки мерчанта

SendNotification

Нет

Число

В зависимости от настроек мерчанта

Флаг отправки счета по Email: 0 - не отправлять, 1 - отправлять

Checkvalue

Да

Строка


Контрольная сумма***

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

** Если не передано значение адреса E-mail, то отправка счета невозможна и значение поля SendNotification игнорируется.

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

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

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

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

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

Пример запроса 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>

Оплата по счету, выставленному из Личного кабинета АПК Ассист

Раздел «Счета» предназначен для получения информации о выставленных и оплаченных счетах, также раздел позволяет создавать новые счета, аннулировать выставленные счета, отправлять выставленные счета по электронной почте покупателям, оплачивать выставленные счета и получать иную необходимую информацию о счетах и их оплате по предприятиям.

Кнопка «Новый счет» позволяет оператору создать счет прямо из личного кабинета. После нажатия этой кнопки открывается новое окно для создания счета. Обязательные параметры отмечены звездочками.


Окно создания счета

Параметры создания нового счета

Название параметра

Комментарий

Общая информация

Мерчант

Выбор из выпадающего списка доступных текущему пользователю мерчантов.

Номер счета

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

Сумма счета

Сумма счета

Валюта счета

Валюта счета (выбор из выпадающего списка кодов валют).

Комментарий

Комментарий по счету

Язык

Язык покупателя, на котором ему будут приходить сообщения и открываться платежные страницы (по умолчанию язык мерчанта).

Оплатить до

Крайний срок оплаты счета (время в соответствии с часовым поясом предприятия), по умолчанию одни сутки.

Двухстадийный режим*

Чекбокс. Разрешает оплату в двухстадийном режиме по счетам данного мерчанта.

Информация о покупателе

Номер клиента

Номер покупателя в базе мерчанта

Фамилия*

Фамилия покупателя

Имя*

Имя покупателя

Отчество

Отчество покупателя

Телефон

Номер телефона покупателя

Мобильный телефон

Номер мобильного телефона покупателя

E-mail

Адрес электронной почты покупателя

Отправить счет*

Выбор из выпадающего списка: Не отправлять, Отправить по E-mail, Отправить по E-mail и SMS.

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

Нажатие на кнопку «Сохранить» вызывает создание счета и возврат к отображению таблицы списка счетов, в которой уже присутствует вновь созданный счет.

Выбор пункта «Просмотр счета» в контекстном меню таблицы счетов вызывает открытие нового окна «Детализация счета» для просмотра параметров счета. Здесь также можно отредактировать параметры выставленного счета. Работа в этом окне осуществляется аналогично действиям в окне «Создание счета».


Форма просмотра (детализации) счета

Внимание! Если у предприятия настроен шаблон уведомления покупателю о выставлении счета для оплаты в системе ЕРИП (см. пример), то покупатель сможет оплатить счет в течение указанного срока с использованием ЕРИП. Если же предприятие использует стандартный шаблон уведомления, то покупатель получит ссылку для оплаты счета с помощью не только ЕРИП, но и других средств оплаты. При этом на оплату с помощью ЕРИП отводится не более 48 часов. К такому же результату приведет передача покупателю ссылки по счету оператором каким-либо способом.

Платежи по требованию из Личного кабинета АПК Ассист

Платежи по требованию через платежные страницы

Для того, чтобы сервер АПК Ассист принял запрос на авторизацию платежа, со стороны предприятия нужно передать следующие параметры:

  • Merchant_ID – идентификатор предприятия в системе АПК Ассист;
  • OrderNumber – номер заказа в системе расчетов предприятия, соответствующий данному платежу;
  • OrderAmount – сумма покупки.

Это минимальный набор параметров платежа, который передается со стороны предприятия при перенаправлении покупателя на сервер АПК Ассист, после чего покупатель вводит на авторизационных страницах АПК Ассист персональные данные (ФИО, адрес, Email, телефон и т. п.) и данные о платежном средстве.

Пример кнопки, содержащей минимальный набор параметров:

<FORM ACTION="https://<SERVER-NAME>/pay/order.cfm" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Ваш Merchant_ID">
<INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="B20042011_27">
<INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="205.50">
<INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Пример оплаты заказа">
<INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Купить">
</FORM>

Достаточно часто покупатель вводит информацию о себе (ФИО, адрес, Email и др.) на страницах предприятия еще при регистрации. Предприятие может передать эти параметры вместе с параметрами платежа. В этом случае покупатель вводит на авторизационных страницах АПК Ассист только данные платежного средства.

Пример кнопки, содержащей параметры платежа и данные покупателя:

<FORM ACTION=" https://<SERVER-NAME>/pay/order.cfm" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Ваш Merchant_ID">
<INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A03032011_26">
<INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="66.66">
<INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="BYN">
<INPUT TYPE="HIDDEN" NAME="FirstName" VALUE="Test">
<INPUT TYPE="HIDDEN" NAME="LastName" VALUE="Testov">
<INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@test.by">
<INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Пример оплаты заказа">
<INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Оплатить">
</FORM>

URL авторизационного запроса:

https://<SERVER-NAME>/pay/order.cfm

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

Название

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

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

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

Описание

Merchant_ID

Да

Число


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

OrderNumber

Да

128 символов


Номер заказа в системе расчетов предприятия.

Delay

Нет

0 – одностадийный механизм работы
1- двустадийный механизм

0

Признак авторизации банковской карты при двустадийном механизме работы

Language

Нет

RU - русский,

EN - английский

Язык юр.лица или предприятия

Язык авторизационных страниц

OrderComment

Нет

256 символов


Комментарий (текст из этого поля будет отображен плательщику при оплате).

OrderAmount

Да

Число, 15 цифр (разделители «.», «,»)


Сумма платежа в оригинальной валюте (например, 10.34)

OrderCurrency

Нет

3 символа

Валюта юр.лица или предприятия

Код валюты, в которой указана сумма платежа OrderAmount (коды валют см. в Таблице кодов валют)

Lastname

Да

30 символов


Фамилия покупателя

Firstname

Да

30 символов


Имя покупателя

Middlename

Нет

30 символов


Отчество покупателя

Email

Нет

128 символа


E-mail покупателя

Address

Нет

256 символов


Адрес покупателя

HomePhone

Нет

64 символа


Домашний телефон покупателя

WorkPhone

Нет

20 символов


Рабочий телефон покупателя

MobilePhone

Нет

20 символов


Мобильный телефон покупателя

Fax

Нет

20 символов


Факс покупателя

Country

Нет

3 символа


Код страны покупателя

State

Нет

3 символа


Код региона покупателя

City

Нет

30 символов


Город покупателя

Zip

Нет

25 символов


Индекс предприятия связи покупателя

URL_RETURN

Нет

255 символов


URL страницы, на которую должен вернуться покупатель после осуществления платежа в системе (должна быть активирована опция «Перейти на страницу магазина» в настройках мерчанта в Личном кабинете). В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS.


URL_RETURN_OK

Нет

255 символов

Значение параметра URL_RETURN, а при его отсутствии – URL для возврата при успешной авторизации, указанный в Личном кабинете

URL страницы, куда должен вернуться покупатель после успешного осуществления платежа в системе АПК Ассист (должна быть активирована опция «Перейти на страницу магазина» в настройках мерчанта в Личном кабинете). В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS.

URL_RETURN_NO

Нет

255 символов

Значение параметра URL_RETURN, а при его отсутствии – URL для возврата, указанный в Личном кабинете

URL страницы, куда должен вернуться покупатель после неуспешного осуществления платежа в системе АПК Ассист или при отсутствии ответа об окончательном статусе платежа (текущий статус "В процессе"), подробнее см. "Возврат покупателя на страницу интернет-магазина после покупки". Должна быть активирована опция «Возвращаться в магазин по URL для возврата» в Личном кабинете. В целях безопасности рекомендуется использовать протокол с шифрованием HTTPS.

CardPayment

Нет

1 – использовать оплату по банковской карте,
0 – не использовать

1

Покупатель сможет сделать платеж с помощью банковской карты, если передано значение параметра 1 или параметр отсутствует (и оплата по банковским картам доступна для предприятия).

ERIPPayment

Нет

1 – использовать оплату по ЕРИП,
0 – не использовать

1

Покупатель сможет сделать платеж по ЕРИП, если передано значение параметра 1 или параметр отсутствует (и оплата по ЕРИП доступна для предприятия).

MobiconPayment

Нет

1 – использовать платежную систему Mobicon,
0 – не использовать

1

Покупатель сможет сделать платеж с помощью платежной системы Mobicon, если передано значение параметра 1 или параметр отсутствует (и оплата по Mobicon доступна для предприятия)

GooglePayPayment

Нет

1; 0

0

Признак оплаты через Google Pay (=1)

ApplePayPayment

Нет

1; 0

0

Признак оплаты через Apple Pay (=1)

SamsungPayPayment

Нет

1; 0

0

Признак оплаты через Samsung Pay (=1)

Signature

Нет*

строка


Формируется строка, сшитая из следующих параметров заказа:

Merchant_ID;OrderNumber;OrderAmount;

OrderCurrency

разделенных точкой с запятой.

На базе этой строки алгоритмом MD5 формируется дайджест.  Дайджест подписывается закрытым RSA ключом мерчанта. Длина ключа - 1024. Полученная байтовая последовательность является подписью магазина. Подпись передается нам в виде дополнительного параметра, закодированного в виде строки BASE64.

Внимание! Параметр необходим для того, чтобы обезопасить передаваемые данные от возможности их подмены злоумышленниками. Следует также включить настройку проверки кода или подписи в ЛК.

 

Checkvalue

Нет*

строка


Контрольный код. Строка формируется по следующей формуле: uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки параметров merchant_id, ordernumber, orderamount, ordercurrency разделенных точкой с запятой, + -строковая склейка.

Примечание. Если мерчант формирует контрольный код без разделителей, следует сообщить об этом в службу поддержки.

Внимание! Параметр необходим для того, чтобы обезопасить передаваемые данные от возможности их подмены злоумышленниками. Следует также включить настройку проверки кода или подписи в ЛК.

RecurringIndicator

Нет

1 – рекуррентный платеж
0 - нерекуррентный платеж

0

Признак рекуррентного платежа

RecurringMinAmount

Нет/Да

Число, 15 цифр (разделители «.», «,»)


Минимальная сумма рекуррентных платежей.  Параметр обязателен при RecurringIndicator = 1

RecurringMaxAmount

Нет/Да

Число, 15 цифр
(разделители «.», «,»)


Максимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator=1

RecurringPeriod

Нет/Да

Число, 10 цифр


Периодичность рекуррентных платежей в днях. Параметр обязателен при RecurringIndicator=1

RecurringMaxDate

Нет/Да

Строковое представление даты в формате DD.MM.YYYY


Дата окончания рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1

Disable3DS

Нет

0 – проверять 3-D Secure согласно настройкам предприятия,
1 – проводить платеж без 3-D Secure.

0

Признак отключения 3-D Secure.

Использование такого режима работы возможно по согласованию с Assist.  Для настройки необходимо обратиться в службу технической поддержки support@belassist.by

 

При использовании параметра его необходимо добавлять и в подпись заказа, которая формируется по определенным правилам.

*Для того, чтобы обезопасить передаваемые данные от возможности их подмены злоумышленниками, необходимо передать один из параметров (Signature или Checkvalue), также должна быть включена настройка проверки контрольного кода (или подписи) в ЛК.

В том случае, если более одного параметра, задающего тип платежного средства (CardPayment и т.п.), имеют значение 1, покупателю предоставляется возможность выбрать способ оплаты на платежной странице АПК Ассист. Если эти параметры не передаются, пользователь также сможет выбрать способ оплаты на платежной странице АПК Ассист из всех доступных для данного предприятия. Если все эти параметры имеют значение 0, это приводит к ошибке.

Пример кнопки, содержащей оптимальный набор параметров:

<FORM ACTION="https://<SERVER-NAME>/pay/order.cfm"METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Ваш Merchant_ID">
<INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A20042011_28">
<INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="237.40">
<INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="USD">
<INPUT TYPE="HIDDEN" NAME="Delay"VALUE="0">
<INPUT TYPE="HIDDEN" NAME="Language"VALUE="RU">
<INPUT TYPE="HIDDEN" NAME="Email"VALUE="test@test.by">
<INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Оплата заказа 28-A">
<INPUT TYPE="HIDDEN" NAME="URL_RETURN_OK" VALUE="http://www.URL.by/yes">
<INPUT TYPE="HIDDEN" NAME="URL_RETURN_NO" VALUE="http://www.URL.by/no">
<INPUT TYPE="HIDDEN" NAME="ERIPPayment"VALUE="1">
<INPUT TYPE="SUBMIT" NAME="Submit"VALUE="Купить">
</FORM>

После выполнения запроса на платежной странице отображается квитанция об оплате, в которой указан статус платежа «В процессе». Покупателю предлагается воспользоваться системой «Расчет» ЕРИП для завершения оплаты. Одновременно на электронный адрес покупателя отправляется письмо с номером заказа в ЕРИП и инструкцией по завершению платежа.

Платежи по требованию через веб-сервис

Специальный веб-сервис позволяет предприятию генерировать заказ в ЕРИП без перехода на платежную страницу.

Для работы в данном режиме предусмотрен web-сервис makeorder.

URL запроса для создания заказа в ЕРИП:

https://<SERVER-NAME>/pay/makeorder.cfm

Список параметров, передаваемых при создании заказа в ЕРИП:

Название

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

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

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

Описание

Merchant_ID

Да

Число


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

OrderNumber

Да/Нет

30 символов


Номер заказа в системе расчетов предприятия.

OrderAmount

Да

Число, 15 цифр (разделители «.», «,»)


Сумма платежа в оригинальной валюте (например, 10.34)

OrderCurrency

Да

3 символа

Валюта юр.лица или предприятия

Код валюты, в которой указана сумма платежа OrderAmount (RUB, USD, EUR)

OrderComment

Нет

256 символов


Комментарий (текст из этого поля будет отображен плательщику при оплате).

Language

Нет

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

Язык юр.лица или предприятия

Язык авторизационных страниц

Lastname

Да

30 символов без цифр


Фамилия покупателя

Firstname

Да

30 символов без цифр


Имя покупателя

Middlename

Нет

30 символов без цифр


Отчество покупателя

Email

Да

128 символов


E-mail покупателя

Address

Нет

90 символов


Адрес покупателя в формате: ул. <30 символов>, д. <10 символов>, корп. <10 символов>, кв. <10 символов>

City

Нет

30 символа


Город покупателя

Signature*

Нет

строка


Формируется строка, сшитая из следующих параметров заказа:

Merchant_ID;OrderNumber;OrderAmount;OrderCurrency, разделенных точкой с запятой. На базе этой строки алгоритмом MD5 формируется дайджест.  Дайджест подписывается закрытым RSA ключом мерчанта. Длина ключа - 1024. Полученная байтовая последовательность является подписью магазина. Подпись передается нам в виде дополнительного параметра, закодированного в виде строки BASE64

Checkvalue*

Нет

строка


Контрольный код. Строка формируется по следующей формуле: uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки параметров merchant_id, ordernumber, orderamount, ordercurrency разделенных точкой с запятой, + -строковая склейка.

Примечание. Если мерчант формирует контрольный код без разделителей, следует сообщить об этом в службу поддержки.

* Необходимо передавать, если предприятие использует параметр для обычных заказов.

Пример запроса HTTP POST:

<FORM ACTION="https://SERVER-NAME/pay/makeorder.cfm " method="POST">
<INPUT TYPE="hidden" NAME="Merchant_ID" VALUE="Ваш Merchant_ID">
<INPUT TYPE="hidden" NAME="OrderNumber" VALUE="011001-10">
<INPUT TYPE="hidden" NAME="OrderAmount" VALUE="22">
<INPUT TYPE="hidden" NAME="OrderCurrency" VALUE="BYN">
<INPUT TYPE="hidden" NAME="OrderComment" VALUE="оплата заказа 011001-10">
<INPUT TYPE="hidden" NAME="Language" VALUE="RU">
<INPUT TYPE="hidden" NAME="Lastname" VALUE="Фамилия покупателя">
<INPUT TYPE="hidden" NAME="Firstname" VALUE="Имя покупателя">
<INPUT TYPE="hidden" NAME="Middlename" VALUE="Отчество покупателя">
<INPUT TYPE="hidden" NAME="Email" VALUE="Email покупателя">
<INPUT TYPE="hidden" NAME="Address" VALUE="Адрес покупателя ">
<INPUT TYPE="hidden" NAME="Homephone" VALUE="Домашний телефон покупателя">
<INPUT TYPE="hidden" NAME="City" VALUE="Город">
<INPUT TYPE="Submit"></FORM>

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

Название

Значение

ordernumber

Номер заказа в системе предприятия

expirationtime

Дата, до которой можно завершить оплату в тайм-зоне GMT, передается в формате DD.MM.YYYY HH:MM:SS

orderstate

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

eripordernumber

Номер заказа в системе ЕРИП (покупатель должен ввести его для завершения оплаты)

Пример ответа в формате JSON после успешного создания заказа:

{"ordernumber":"ABC123", "expirationtime":"04.08.2017 13:06:00", "orderstate": "In Process", "eripordernumber":"21923958"}

Пример ответа в формате JSON после неуспешного создания заказа или проблем с параметрами:

{"errorCode":"51", "errorMessage":"Имя клиента должно быть указано. "}

Авансовые платежи

Предприятие может получать через ЕРИП либо авансовые платежи, либо платежи по требованию в зависимости от настроек системы.

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

После успешной оплаты клиентом по указанному лицевом счету в ЕРИП, оплаченный заказ отобразится в мониторинге заказов ЛК АПК Ассист.

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

Параметр

Обязательный

Тип, длина

Описание

Merchant_ID

Да

Число

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

PersonalAccount

Да

30 символов

Номер лицевого счета, ID покупателя и т.п. в системе предприятия (использование спецсимволов не допускается).

Примечание. Все буквенные символы, содержащиеся в номере лицевого счета, при загрузке в АПК Ассист преобразуются в прописные буквы. Поэтому номера счетов должны формироваться таким образом, чтобы исключить возможность появления неуникальных номеров счетов (например, последовательности символов в номере счета АВС, abc, Abc и т.п. будут считаться одинаковыми).

Debt

Нет

Число

Сумма задолженности (12,2 – два знака после разделителя, разделитель - запятая)

Lastname

Нет

30 символов

Фамилия покупателя

Firstname

Нет

30 символов

Имя покупателя

Middlename

Нет

30 символов

Отчество покупателя

Email

Да

128 символов

Email покупателя

City

Нет

30 символов

Город в адресе покупателя

Street

Нет

30 символов

Улица в адресе покупателя

House

Нет

18 символов

Номер дома в адресе покупателя

Building

Нет

10 символов

Номер корпуса в адресе покупателя

Apartment

Нет

10 символов

Номер квартиры в адресе покупателя

InfoLine*

Нет

999 символов

Дополнительная информация – договор, контракт, комментарий и т.д. (текст из этого поля будет отображен плательщику при оплате).

Date

Нет

DDMMYYYY HHMMSS

Дата реестра

* Для Info в ЕРИП разрешена вложенность, 1 строка не должна превышать 999 символов, все вместе 2000.

В первой строке файла должны быть перечислены названия параметров, в следующих – их значения. Разделитель данных – точка с запятой. Валюта всегда белорусские рубли BYN.

Пример данных в файле

MERCHANT_ID;PERSONALACCOUNT;DEBT;SURNAME;FIRSTNAME;EMAIL;INFOLINE
500069;DFG4567;100.01;Testov;Test;test@assist.by;договор 454566

Передача файла с реестром текущих лицевых счетов осуществляется по договоренности с предприятием с определенной периодичностью или по запросу.

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

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

Подготовленный файл с реестром можно загрузить в разделе «Абоненты» в Личном кабинете АПК Ассист.

Авансовые платежи с проверкой клиента на стороне предприятия

Предприятие может организовать пополнение личного кошелька клиента через ЕРИП. Средства кошелька клиент предприятия сможет использовать для последующей оплаты заказа. Для идентификации клиента возможно использование номера телефона, адреса Email или другого ID клиента. Верификация производится по заранее оговоренному ID (клиент должен знать, что именно требуется применять в качестве ID на стороне ЕРИП для начала пополнения своего кошелька).

Оплата осуществляется по следующему сценарию:

  • клиент находит предприятие в каталоге ЕРИП и указывает свой ID;
  • ЕРИП отправляет в АПК Ассист запрос с указанным клиентом ID;
  • АПК Ассист посылает запрос предприятию о том, есть ли у него клиент с таким ID. Если клиент есть, то АПК Ассист отвечает в ЕРИП успехом, если нет - сообщает об ошибке Абонент не найден;
  • клиент указывает сумму для пополнения кошелька и начинает процесс оплаты через ЕРИП;
  • ЕРИП посылает в АПК Ассист запрос, далее оплата проводится по существующему сценарию авансового платежа (номер заказа формируется автоматически), таблица абонентов не используется при наличии верификации от предприятия;
  • после проведения оплаты через ЕРИП АПК Ассист отправляет результат авторизации на сервер предприятия с идентификатором абонента и суммой зачисления, указанный в результате номер заказа/операции позволяет исключить дубли на стороне предприятия.

Для обеспечения проверки клиента на стороне предприятия должен быть реализован следующий сервис верификации:

Авторизация:

login/password в теле запроса или BasicAuth - на основе login/password в заголовке запроса

Запрос:

HTTP POST

Формат передачи данных:

JSON

Параметры запроса

Параметр

Обязательный

Формат

Описание

account

Да

Строка

Идентификатор клиента (номер лицевого счета)

login

Нет

Строка

Логин для аутентификации

password

Нет

Строка

Пароль для аутентификации

amount

Нет

Число

Сумма (в запросе передается значение 0)

Ответ сервера предприятия

  • HTTP 200 в случае успешной обработки запроса. Ответ должен содержать следующие поля:

Параметр

Обязательный

Описание

status

Да

Статус обработки:

  • OK – аккаунт найден;
  • NotFound – указанного аккаунта не существует;
  • Error – произошла ошибка (дополнительно должна быть предоставлена информация об ошибке).

amount

Нет

Опциональный блок с информацией по сумме.

editable

Да

«editable»: <bool - разрешение редактировать сумму>

arrears

Да

«arrears»: <число, сумма задолженности>

min

Нет

«min»: <число, минимальная сумма>, имеет смысл только при editable=true, при editable=false поле игнорируется.

max

Нет

«max»:<число, максимальная сумма>, имеет смысл только при editable=true, при editable=false поле игнорируется

accountInfo

Нет

Опциональный блок параметров с информацией о клиенте, все параметры типа строка длиной до 30 символов.

 

fName

Нет

«fName»: <Имя>

 

lName

Нет

«lName»: <Фамилия>

 

mName

Нет

«mName”: <Отчество>

addressInfo

Нет

Опциональный блок параметров с адресом клиента.

 

city

Нет

«city»: <Город> - строка длиной до 30 символов

 

street

Нет

«street»: <Улица> - строка длиной до 30 символов

 

house

Нет

«house»: <Дом> - строка длиной до 10 символов

 

building

Нет

«building»: <Корпус> - строка длиной до 10 символов

 

apartment

Нет

«apartment»: <Квартира> - строка длиной до 10 символов

  • HTTP 400 в случае неверных входных параметров. Ответ содержит следующие поля:

status - string: "Error"

errorMessage - string: текст описания ошибки

  • HTTP 401 Unauthorized request (не прошла авторизация):

status - string: "Error"

errorMessage - string: текст описания ошибки

  • HTTP 403 в случае проблем с выполнение запроса. Ответ содержит следующие поля:

status - string: "Error"

errorMessage - string: текст описания ошибки

Пример запроса к веб-сервису:

{"account":"TEST400_1","login":"test","password":"test1","amount":0}

Пример успешного ответа:

{{
"status":"Ok",
"amount" :
{"editable": true, "arrears": 100.00, "min": 1.00, "max":100.00}
,
"accountInfo" :
{"fName" : "Имя","lName": "Фамилия","mName": "Отчество"}
,
"addressInfo" :
{"city": "Город","street": "Улица","house": 8,"building":"2","apartment":"34"}
}}

Пример ответа с ошибкой:

{"status":"Error","errorMessage":"текст описания ошибки 400"}

Пример ответа в случае отсутствия лицевого счета:

{"status":"NotFound","errorMessage":"account не найден"}

Оповещения о платежах

Для оповещения предприятия о результате платежа в режиме реального времени система АПК Ассист предоставляет сервис синхронной отправки результатов платежа на сервер предприятия. После завершения покупателем оплаты заказа (при помощи банковской карты или одного из средств электронной наличности) на сервер предприятия методом HTTP POST или SOAP отправляется сообщение с параметрами платежа.

Настроить отправку можно в Личном кабинете, указав URL для отправки результатов, тип протокола (POST или SOAP), тип подписи и секретное слово.

После активации и настройки сервиса на сервер предприятия будут отправляться результаты операций (оплат, подтверждений, отмен – в зависимости от настроек). Не отправляются результаты операций оплаты, завершенных по тайм-ауту.

В отправляемых с помощью сервиса результатах операций для авансовых платежей добавляется параметр personalaccount (по запросу в службу поддержки support@belassist.by) для того, чтобы предприятие могло определить, в адрес какого лицевого счета произведена оплата.

Подробнее о об отправке результатов платежей на сервер предприятия в соответствующем разделе документации.

Внимание! Если предприятие получает ежедневные реестры проведенных операций из АПК Ассист, для таких реестров также имеется возможность указания лицевых счетов в ЕРИП, по которым были проведены оплаты (при наличии у предприятия авансовых платежей). Для настройки таких реестров следует обращаться с запросом в службу технической поддержки АПК Ассист (support@belassist.by).


Наверх