Рекуррентные платежи
Веб-сервис предназначен для инициации оплаты за продолжение предоставления услуг по подписке. Возможность работы с этим сервисом определяется настройками процессинга банка-эквайера. Подробную информацию можно получить в службе поддержки Assist по адресу support@belassist.by.
Для инициации рекуррентного платежа необходимо в первоначальном запросе на авторизацию передать значение параметра RecurringIndicator=1 и значения параметров, задающих диапазон сумм последующих рекуррентных платежей, периодичность оплат (в днях) и дату окончания подписки.
Затем с указанной периодичностью предприятие инициирует платеж, задавая сумму, а необходимая платежная информация (данные банковской карты) берется из первоначальной оплаты.
URL запроса для рекуррентного платежа: https://<SERVER-NAME>/recurrent/rp.cfm.
Параметры передаются методом POST в теле запроса в формате «ключ=значение», SOAP запросом (в кодировке UTF-8), либо в формате JSON (swagger описание: https://docs.belassist.by/swagger/).
Список параметров запроса
Название | Обязательное поле | Принимаемые значения | Значение по умолчанию | Описание |
BillNumber | Да | 15 или 16 цифр | BillNumber первого заказа | |
OrderNumber | Да | 128 символов | Номер нового заказа для рекуррентного платежа | |
Merchant_ID | Да | Число | Идентификатор предприятия в АПК Ассист | |
Login | Да | 8 - 20 символов | Логин (лат. буквы и цифры, символ _) | |
Password | Да | 8 - 20 символов | Пароль (лат. буквы и цифры) | |
Amount | Да | Число, 15 цифр (разделители «.») | Сумма рекуррентного платежа, должна находиться в допустимом диапазоне между значениями максимальной и минимальной сумм рекуррентных платежей, переданных при первоначальном запросе на авторизацию инициирующего платежа. | |
Currency | Да | 3 символа | Валюта рекуррентного платежа, должна совпадать с валютой инициирующего, в противном случае заказ закрывается с ошибкой. | |
OrderComment | Нет | 4000 символов | Комментарий | |
Language | Нет | RU EN | EN | Язык вывода результатов |
Format | Нет | 1 – CSV | 1 | Формат выдачи результатов. Передается только для запроса в формате POST (по умолчанию ответ будет выдан в формате CSV). Для других форматов ответ выдается в том же формате, в котором был выполнен запрос. |
Все параметры, передаваемые в запросе, проходят автоматическую валидацию в АПК Ассист. Правила валидации описаны в табл. "Правила валидации входных параметров".
Пример запроса для формата HTTP POST:
<FORM ACTION="https://<SERVER-NAME>/recurrent/rp.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="BillNumber" VALUE="511111100000001.1"> <INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A1_R1"> <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="20"> <INPUT TYPE="HIDDEN" NAME="Currency" VALUE="BYN"> <INPUT TYPE="HIDDEN" NAME="Format" VALUE="3"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="EN"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Выполнить"> </FORM>
Список параметров ответа:
Название | Значение |
billnumber | Уникальный номер заказа в системе АПК Ассист, расширенный формат |
ordernumber | Номер заказа |
testmode | Тестовый режим |
ordercomment | Комментарий |
orderamount | Оригинальная сумма заказа |
ordercurrency | Оригинальная валюта заказа |
firstname | Имя плательщика |
lastname | Фамилия плательщика |
middlename | Отчество плательщика |
Email плательщика | |
orderdate | Дата заказа по Гринвичу (GMT) |
orderstate | Статус заказа |
packetdate | Дата формирования запроса по Гринвичу (GMT) |
signature | Значение X без разделителей, подписанное закрытым ключом АПК Ассист, закодированное в BASE64, где X - billnumber,ordernumber,responsecode,orderamount,ordercurrency,meannumber,approvalcode,orderstate,packetdate |
operationtype | Тип операции |
amount | Сумма операции |
currency | Валюта операции |
ipaddress | IP-адрес плательщика |
meantypename | Тип платежного средства |
meansubtype | Подтип платежного средства |
meannumber | Номер платежного средства |
cardholder | Держатель платежного средства |
cardexpirationdate | Срок действия карты |
issuebank | Название банка-эмитента |
bankcountry | Страна банка-эмитента |
rate | Курс валюты |
responsecode | Код возврата |
message | Сообщение о результате операции |
customermessage | Сообщение о результате для покупателя |
recommendation | Рекомендация |
approvalcode | Код авторизации |
protocoltypename | Протокол |
processingname | Процессинг |
В качестве значения поля <meannumber> возвращаются первые 6 и последние 4 цифры номера карты, остальные цифры скрыты символом *.
Автоматические рекуррентные платежи по расписанию
Для активации подписки и формирования расписания в дополнение к основным параметрам заказа предприятию необходимо передавать следующие параметры:
Название | Обязательное поле | Принимаемые значения | По умолчанию | Описание |
RecurringIndicator | Да | 1 – рекуррентный платеж 0 - нерекуррентный платеж | 0 | Признак рекуррентного платежа |
RecurringMinAmount | Нет | Число, 15 цифр (разделитель «.») | 0 | Минимальная сумма рекуррентного платежа. Проверяется при инициации платежа через веб-сервис |
RecurringMaxAmount | Да | Число, 15 цифр (разделитель «.») | Сумма каждого следующего автоматического рекуррентного платежа. | |
RecurringPeriod | Да | Число, 3 цифры | Периодичность рекуррентных платежей, по умолчанию в днях | |
RecurringMaxDate | Да | Строковое представление даты в формате DD.MM.YYYY | Дата окончания рекуррентных платежей | |
RecurringNextDate | Нет | Строковое представление даты в формате DD.MM.YYYY | К текущей дате прибавляется период | Дата следующего платежа. Передаваемая дата должна быть больше или равна текущей |
RecurringPeriodScale | Нет | 4 – день, 5 – неделя, 6 - месяц | 4 | Единица измерения периода рекуррентов |
При проведении первого рекуррентного платежа предприятие передает номер заказа OrderNumber (номер заказа в системе предприятия) в авторизационном запросе на сервер АПК Ассист. При проведении последующих рекуррентных платежей номер заказа будет сформирован автоматически по правилу:
OrderNumber_YYMMDD,
где YYMMDD – фактическая дата инициации рекуррентного платежа.
После инициации оплаты автоматического рекуррента производится пересчёт даты для следующего платежа в соответствии с переданным значением периода.
Внимание! Если операция оплаты автоматического платежа завершилась неуспешно (например, на счету карты клиента недостаточно средств), то повторная попытка оплаты автоматически не производится и дата следующего платежа не пересчитывается. В этом случае предприятию необходимо связаться с клиентом для решения вопроса. Инициировать повторную оплату предприятие может через веб-сервис или вручную откорректировать расписание через личный кабинет (например, установить текущую или завтрашнюю дату в качестве даты следующего платежа).
Необходимо обратить внимание на то, что для рекуррентного платежа с расписанием не запрещено проведение рекуррентного платежа через веб-сервис (если только это не ограничено правами пользователя). Вызов веб-сервиса не отменяет проведение очередного автоматического платежа и не изменяет расписание.