Общие сведения

Данное руководство описывает процесс разработки платежного модуля для приема платежей в сети Интернет c помощью системы WEBPAY и использование тестовой среды (Sandbox) для тестирования разрабатываемого модуля.

Порядок разработки

  1. Внимательно ознакомиться с настоящим руководством.
  2. Зайти в Web-приложение среды для тестирования разрабатываемых модулей по адресу: https://sandbox.webpay.by, используя параметры, полученные в письме от персонального менеджера в компании WEBPAY.
  3. Ознакомиться с интерфейсом Sandbox и заполнить необходимые поля (Профайл компании).
  4. Приступить к разработке платежного модуля согласно данному руководству.
  5. Произвести тестирование модуля.
  6. Получить письмо с новыми параметрами для перевода платежного модуля из тестовой системы в реальную платежную систему (Переход из тестовой среды в реальную).
  7. Внести изменения в платежный модуль.

Интерфейс Web-приложения

Интерфейс Web-приложения тестовой системы Sandbox и реальной системы не отличаются. Обращаем Ваше внимание на адрес, используемой среды в браузере (для тестовой среды — https://sandbox.webpay.by, для реальной — https://billing.webpay.by). Перед началом разработки рекомендуется зайти в Web-приложение и ознакомиться с его содержимым (Личный кабинет).

Основной экран приложения

После входа в Web-приложение Вам будет отображена следующая страница:

Основной экран приложения

На данной странице отображается основная статистика по Вашему биллинг-аккаунту, тут же Вы сможете сформировать статистику за выбранный интервал времени. Слева находится панель навигации, которая предоставляет возможность управления Вашим аккаунтом, а также требуемой информацией по прошедшим транзакциям.

Установка секретного ключа

Секретный ключ необходим для формирования электронной подписи каждого Вашего платежа (Электронная подпись заказа). Этот параметр является обязательным к заполнению и без него невозможно будет проведение транзакций по оплате товаров/услуг. Для установки значения ключа необходимо заполнить поле SecretKey. Для этого необходимо перейти к разделу меню "Настройки" → "Компания". Это поле может содержать случайную последовательность символов за исключение знака &.

Установка секретного ключа

Просмотр финансовых операций

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

Просмотр платежей

Каждая такая транзакция привязана к Инвойсу (Счету), у инвойса может быть несколько типов транзакций, таких как:

  • Authorized — состояние авторизации платежа (денежные средства заблокированы на банковской карточке покупателя). В этом состоянии у покупателя данная сумма ещё не списана со счета (заблокирована) и данная сумма еще не перечислена на Ваш банковский счет.
  • Completed — денежные средства списаны с банковской карточки и будут зачислены на Ваш банковский счет в сроки, установленные банком-эквайером.
  • System — системная транзакция.

В поле "ID счета" содержится номер, к которому привязаны транзакции. Для просмотра всех транзакций, связанных с этим номером, а также значений, с которыми был совершен платеж, необходимо нажать на ссылку. В результате Вы перейдете на страницу с информацией о данном инвойсе.

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

Вход в персональный кабинет WEBPAY

Доступ в личный кабинет WEBPAY осуществляется посредством интернет-браузера по защищенному каналу связи.

Для входа в персональный кабинет WEBPAY необходимо указать следующий адрес:

https://billing.webpay.by — для реальной среды;

https://sandbox.webpay.by — для тестовой среды.

В открывшемся окне следует указать предоставленные персональным менеджером компании WEBPAY логин и пароль.

Вход в личный кабинет WEBPAY

Важно!

Обращаем Ваше внимание, что соединение должно быть защищенным, поэтому обязательно укажите https вместо http.

В случае успешной авторизации вы попадете на страницу панели мониторинга. Панель мониторинга условно разделена на пять блоков:

  • блок формирования статистики за промежуток дат — управляет отображением статистики за выбранный период времени;
  • блок статистики по счетам — отображается информация о счетах, которые уже оплачены, ожидают оплаты или просрочены, а также об общем количестве счетов. Еще из этого блока можно быстро перейти в раздел счета по кнопке "Счета" и создать новый счет по кнопке "Новый счет";
  • блок с курсами валют;
  • блок статистики по платежам — отображается баланс за выбранный промежуток времени, а также кнопка для быстрого перехода в раздел платежи. Поле "Текущий баланс биллинга" отображает общую сумму Завершенных платежей и Рекуррентных платежей за вычетом суммы Возвратов;
  • блок статистики по средствам оплаты — отображается процентное соотношение статистики по долям банковских карт.

В левой части экрана располагается скрывающееся меню, из которого можно попасть в разделы "Счета", "Платежи", "Журнал платежей", "Отчеты" и "Настройки".

Панель мониторинга

Заполнение параметров персонального кабинета WEBPAY ("Компания")

Перед началом работы необходимо проверить основные параметры Вашего биллинг-аккаунта. Для этого необходимо перейти в пункт меню "Настройки" → "Компания". В данном разделе Вы можете изменить данные о Вашей организации (адрес компании, город, почтовый индекс, контактный телефон). Также в данном разделе Вы можете произвести следующие настройки:

  • прописать значение "Секретного ключа" (ОБЯЗАТЕЛЬНОЕ значение при интеграции с сайтом. Перейти к разделу Интеграция платежей);
  • указать "URL для уведомлений", по которому система WEBPAY будет отсылать специально сформированный запрос с информацией по платежу;
  • изменить язык системы (по умолчанию используется русский);
  • установить формат даты и времени;
  • установить разрядность дробной части (количество знаков после запятой для цен в валюте EUR, USD, RUB).

Для изменения остальных данных (имя компании, наименование юридического лица, сайт компании) Вам необходимо связаться с персональным менеджером WEBPAY.

Параметры персонального кабинета WEBPAY

Создание учетной записи ("Учетные записи")

В открытом личном кабинете перейдите в пункт меню "Настройки" → "Пользователи". В данном разделе можно создавать, удалять и управлять учетными записями пользователей Вашей компании, которые имеют доступ к системе WEBPAY.

Учетные записи

Для создания нового пользователя необходимо нажать кнопку "Добавить пользователя" в меню "Настройки" → "Пользователи".

Добавление учетной записи

Перед Вами откроется форма, в которой нужно указать следующие обязательные параметры:

  • имя пользователя (логин от 4 до 12 латинских букв),
  • имя,
  • фамилия,
  • телефон,
  • email,
  • страна,
  • область,
  • почтовый индекс,
  • город,
  • адрес,
  • пароль,
  • подтверждение пароля.

Также следует указать, какими правами должен обладать владелец создаваемой учетной записи в списке "Группы":

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

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

Создание новой учетной записи
  • в поле "Мультилогин" оставьте "Да",
  • в поле "Активный" укажите "Нет" в случае, если планируете сделать учетную запись активной позже. Иначе оставьте "Да".

Для завершения создания новой учетной записи нажмите кнопку "Подтвердить".

Также Вы можете создать учетные записи для Ваших постоянных клиентов. Для этого необходимо выбрать из выпадающего списка группы "Покупатель". Тогда Вы можете выставлять счет данному покупателю, выбрав его из списка.

В меню "Пользователи" Вы всегда можете просмотреть уже созданные учетные записи или перейти к их редактированию. Для редактирования учетной записи нужно щелкнуть по интересующей записи и нажать кнопку "Изменить пользователя" в верхнем правом углу экрана.

Заполнение данных учетной записи

Просмотр информации о платежах

Все платежи, которые поступили в пользу Вашей компании при оплате банковской картой онлайн, Вы можете просматривать в меню "Платежи".

  • ID транзакции — уникальный номер транзакции (в случае если номер ID транзакции указан — транзакция завершена успешно),
  • ID счета,
  • способ платежа,
  • сумма,
  • статус 3DS — если карточка плательщика участвует в процедуре 3D-Secure, указывается "Да",
  • плательщик,
  • процессинг шлюз,
  • статус,
  • дата платежа.
Информация о платежах

Для удобства поиска и работы с информацией в списке "Платежи" и "Журнал платежей" можно произвести поиск платежей по интересующим Вас параметрам. Для этого следует воспользоваться окном сверху от списка. Окно можно раскрыть, получив расширенные опции поиска. По умолчанию используется сортировка по дате платежа. Поиск можно осуществить по следующим параметрам:

  • указать временной интервал поиска, выбрав необходимый период;
  • указать RRN (уникальный номер транзакции, присваиваемый процессинговым центром) платежа;
  • указать Email, привязанный к транзакции;
  • указать ID счета;
  • указать ID транзакции;
  • указать номер карты;
  • выбрать статус транзакции.
Расширенный поиск по параметрам

Все счета, которые были выставлены Вашей компанией, включая оплаченные, Вы можете просматривать в меню "Счета". В списке доступна следующая информация:

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

При нажатии на счет раскрывается дополнительная информация:

Дополнительная информация о выставленных счетах

Журнал платежей

Все попытки оплаты, осуществленные по банковской карте, включая не успешные, с указанием текстовой информации о результате проведения операции отображаются в меню "Журнал платежей". В списке доступна следующая информация:

  • ID — номер запроса в системе WEBPAY;
  • ID транзакции — уникальный номер транзакции (в случае если номер ID транзакции указан — транзакция завершена успешно);
  • дата создания;
  • дата платежа;
  • способ платежа;
  • тип — платежная система банковской карточки;
  • платежное средство — частично скрытый номер банковской карточки;
  • код ответа — код ответа процессингового центра;
  • текст ответа — расшифровка ответа процессингового центра;
  • ID аккаунта;
  • статус 3DS — если карточка плательщика участвует в процедуре 3D-Secure, указывается "Да".
Журнал платежей

Если кликнуть на поле "ID транзакции", то откроется окно "Журнал операций по платежу". Также здесь можно найти ссылку на чек, который получил плательщик после успешной оплаты.

Журнал операций по платежу

Отчетность по совершенным платежам

Для получения отчетов по платежам, совершенным через АИС "Расчет" (ЕРИП) и/или интернет-эквайринг, и результатов сверки поступления средств Вам необходимо зайти в систему отчетности по адресу https://merchant-sandbox.webpay.by для тестовой среды и по адресу https://merchant.webpay.by для реальной среды. Логин и пароль тот же, что и для входа в персональный кабинет WEBPAY.

Отчеты из этого кабинета Вы можете экспортировать в Excel. Также можно, не заходя в систему отчетности, получать отчеты на email в Excel-файле или в формате JSON.

Вход в систему отчетности

Отчетность по транзакциям, совершенным через АИС "Расчет" (ЕРИП)

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

Отчет ЕРИП → Результаты платежей
Описание полей
НазваниеОписание
Статус платежа

Результат выполнения платежа. Возможные значения:

Успешный платеж — система WEBPAY подтвердила успешное выполнение платежа.

Сбой платежа — система WEBPAY не подтвердила успешное выполнение платежа.

Не подтверждено WEBPAY — отчет сверки ЕРИП содержит информацию по несуществующей операции.

Статус сверки

Статус сверки данных WEBPAY с данными из отчетов ЕРИП. Возможные значения:

Не подтверждено банком (ЕРИП) — для успешной транзакции в системе WEBPAY не пришло подтверждение из ЕРИП.

Успешная сверка — для успешной транзакции в системе WEBPAY пришло подтверждение из ЕРИП.

Ошибка сверки — для успешной транзакции в системе WEBPAY пришло подтверждение из ЕРИП, но существует несоответствие в параметрах платежа.

Время платежаДата совершения платежа в системе WEBPAY.
Лицевой счетЗначение, идентифицирующее потребителя услуги или товара.
Id запроса ЕРИПЕдиный идентификатор последовательности запросов на оплату в ЕРИП.
Id транзакции ЕРИПУчетный номер операции в центральном узле ЕРИП.
Номер услугиНомер услуги Магазина.
Код расчетного агентаТри последние цифры кода МФО расчетного агента.
СуммаСумма платежа в системе WEBPAY.
ВалютаВалюта платежа в системе WEBPAY.
Тип авторизации

Способ платежа. Возможные значения:

MS — карточка с магнитной полосой.

BC — карточка БЕЛКАРТ.

NONE — плательщик не идентифицирован.

CASH — оплата наличными в РКЦ.

CASHIN — оплата наличными в платежно-справочном терминале.

Id транзакции WEBPAYИдентификатор ЕРИП в рамках платежных запросов.
Код отправителя сообщенияКод абонента регионального узла.
Номер сообщенияНомер сообщения ЕРИП.
Дата формирования сообщенияДата формирования сообщения ЕРИП.
Номер платежного документаНомер платежного документа ЕРИП.
Дата перечисления средствДата перечисления средств по данным ЕРИП.
Лицевой счет расчетного агентаЛицевой счет расчетного агента, с которого производился расчет с производителем услуг.
Перечисленная суммаПеречисленная сумма по данным ЕРИП для текущего платежа.
ВалютаВалюта текущего платежа в ЕРИП.
Дата совершения операцииДата совершения платежа по данным ЕРИП.
Номер операции в расчетном агентеНомер операции ЕРИП в расчетном агенте.
Средство авторизации суммыИнформация о платежном средстве.

Чтобы просмотреть все транзакции АИС "Расчет" ЕРИП, необходимо выбрать пункт меню "ЕРИП" → "Журнал транзакций". В результате отобразится отчет, который содержит информацию об этапах оплаты заказа и возврате средств в режиме реального времени. Оплата производится в три этапа:

  • Service Info (Информационный запрос),
  • Transaction Start (Старт оплаты),
  • Transaction Result (Результат оплаты).

Возврат средств производится в два этапа:

  • Storn Start (Запрос сторнирования),
  • Storn Result (Результат сторнирования).
Описание полей отчета
НазваниеОписание
ID запросаЕдиный идентификатор последовательности запросов на оплату в ЕРИП.
Статус операции

Результат выполнения операции. Возможные значения:

Успешная операция — система WEBPAY подтвердила успешное выполнение операции.

Ошибка выполнения — система WEBPAY не подтвердила успешное выполнение операции.

Дубликат операции — в системе WEBPAY уже содержится данная операция.

Тип операции

Тип операции в соответствии с протоколом ЕРИП:

SERVICE_INFO (Информационный) — получение данных о заказе.

TRANSACTION_START (Старт оплаты) — начало оплаты заказа.

TRANSACTION_RESULT (Результат оплаты) — результат оплаты заказа.

STORN_START (Запрос сторнирования) — начало запроса на возврат средств.

STORN_RESULT (Результат сторнирования) — результат запроса на возврат средств.

Дата запросаДата формирования запроса в ЕРИП.
ID транзакции ЕРИПУчетный номер операции в центральном узле ЕРИП.
ID транзакции WEBPAYИдентификатор ЕРИП в рамках платежных запросов.
Лицевой счет WEBPAYЗначение, идентифицирующее потребителя услуг или товар.
Номер услугиНомер услуги Магазина.
СуммаСумма платежа в системе WEBPAY.
ВалютаВалюта платежа в системе WEBPAY.
Тип авторизацииТип авторизации средств при оплате заказа.
Расчетный агентКод расчетного агента.

Отчетность по транзакциям, совершенным через интернет-эквайринг

Выберите пункт меню "Платежи" → "Отчет сверки". В итоге отобразится отчет, который содержит результат оплаты заказа и информацию о сверке оплаты с банком-эквайером. Запись в отчете появляется сразу же после оплаты.

Описание полей отчета:
НазваниеОписание
Статус счета

Результат выполнения платежа. Возможные значения:

Авторизация — денежные средства заблокированы на карте плательщика.

Сброс авторизации — денежные средства разблокированы на карте плательщика.

Частичный сброс авторизации — часть денежных средств разблокирована на карте плательщика.

Финансовое завершение — денежные средства списаны со счета плательщика.

Полный возврат средств — денежные средства списаны с р/с Магазина и возвращены на карту плательщика.

Частичный возврат средств — часть денежных средств списано с р/с Магазина и возвращена на карту плательщика.

Статус сверки

Статус сверки данных WEBPAY с данными из отчетов банка. Возможные значения:

Не подтверждено банком — для успешной транзакции в системе WEBPAY не пришло подтверждение из банка.

Успешная сверка — для успешной транзакции в системе WEBPAY пришло подтверждение из банка.

Ошибка сверки — для успешной транзакции в системе WEBPAY пришло подтверждение из банка, но существует несоответствие в параметрах платежа.

ID мерчантаИдентификатор магазина в системе WEBPAY.
Сайт торговцаСайт, подключенный к системе WEBPAY.
Номер заказа торговцаУникальный идентификатор заказа, присваиваемый Магазином.
Номер счета WEBPAYНомер заказа в системе WEBPAY.
Номер терминалаНомер терминала, установленный банком-эквайером.
ПроцессингНомер процессинга банка-эквайера.
Дата и время авторизацииДата совершения платежа в системе WEBPAY.
СуммаСумма платежа в системе WEBPAY.
ВалютаВалюта платежа в системе WEBPAY.
RRN процессинга банка-эквайераУникальный номер транзакции, присваиваемый процессинговым центром.
Код авторизации банка-эмитентаКод авторизации, присвоенный банком-эмитентом.
Дата и время финансового списанияДата финансового завершения платежа в системе WEBPAY.
Сумма финансового завершенияСумма финансового завершения платежа в системе WEBPAY.

В случае если Вашим банком-эквайером является "Приорбанк" ОАО, ЗАО "МТБанк", ОАО "Дабрабыт" Вы можете воспользоваться пунктом меню "Платежи" → "Поступление средств", чтобы просмотреть информацию об отражении денежных средств в банке-эквайере. В результате отобразится отчет, который содержит информацию об успешных транзакциях, отраженных в банке.

Описание полей отчета
НазваниеОписание
Дата учета платежа/возврата в банкеДата отражения денежных средств в банке-эквайере.
Сумма к перечислениюСумма за вычетом комиссии, которая поступит на р/с Магазина.
Валюта перечисленияВалюта, в которой зачисляются денежные средства.
Номер заказа торговцаУникальный идентификатор заказа, присваиваемый Магазином.
Номер терминалаНомер терминала, установленный банком-эквайером.
ID мерчантаИдентификатор магазина в системе WEBPAY.
Сайт торговцаСайт, подключенный к системе WEBPAY.
Номер заказа WEBPAYНомер заказа в системе WEBPAY.
Код авторизации банка-эмитентаКод авторизации, присвоенный банком-эмитентом.
RRNУникальный номер транзакции, присваиваемый процессинговым центром.
Сумма возмещенияСумма платежа в системе WEBPAY.
Комиссия возмещенияКомиссионное вознаграждение банку.
Дата и время авторизацииДата совершения платежа в системе WEBPAY.

Расширенные настройки платежной страницы

Важно!

Для внесения изменений в оформление платежной страницы, необходимо обратиться к менеджеру компании WEBPAY по адресу managers@webpay.by

Возможности изменений:

  • размещение логотипа компании,
  • использование цвета бренда в кнопке и линиях,
  • выбор шрифта страницы,
  • изменение подложки карты (цвет или изображение),
  • изменение фона страницы (цвет или изображение),
  • изменение текста кнопки оплаты,
  • размещение дополнительного текста на странице.
Возможности для изменений платежной страницы

9.1. Логотип

Логотип должен быть в формате png. Максимальная высота изображения 100px (пикселей), а размер не более 500 KB. Рекомендуем использовать прозрачный фон.

9.2. Цвет бренда

Цвет передается в шестнадцатеричном коде — Hex Code (значение цвета представлено в виде "#XYXYXY"). Данным цветом будут отображаться:

  • кнопка оплаты,
  • подложка карты,
  • нижние границы полей ввода данных,
  • надписи "Оплата картой", "Оплата ЕРИП", "EN", "RU".

9.3. Шрифт страницы

Можно выбрать из пяти доступных шрифтов:

  • Montserrat,
  • Roboto,
  • Segoe UI,
  • ProximaNova,
  • Helvetica.

9.4. Подложка карты

В качестве подложки карты можно использовать либо цвет, либо изображение. Цвет передается в шестнадцатеричном коде — Hex Code (значение цвета представлено в виде "#XYXYXY"). ! Цветом подложки карты является цвет бренда. Изображение должно быть в формате png. Максимальная высота изображения 285px (пикселей), максимальная ширина 430px (пикселей), а размер файла не более 500 KB. Рекомендуется использовать прозрачный фон.

9.5. Фон страницы

Вы можете задать фон платежной страницы — цвет или изображение. Цвет фона передается в цветовом шестнадцатеричном коде — Hex Code (значение цвета представлено в виде "#XYXYXY"). Изображение должно быть в формате png. Максимальный размер файла не более 1 MB. Изображение масштабируется с сохранением пропорций таким образом, чтобы целиком поместиться внутри страницы.

9.6. Изменение текста кнопки оплаты

9.7. Размещение дополнительного текста на странице

Статусы счета и типы транзакций в системе WEBPAY

Статусы счетов

Ознакомиться со статусом счета можно выбрав в меню пункт "Счета". В системе WEBPAY по статусу счета делятся на следующие группы:

Ожидание оплаты — данный статус счет получает сразу после формирования и отправки уведомления на email плательщика. Вы можете увидеть в поле "Сумма заказа" сумму, на которую был выставлен счет.

Ожидание оплаты

Авторизован — счет получает данный статус после успешной авторизации, т.е. денежные средства заблокированы на банковской платежной карточке покупателя, но еще не списаны. Транзакция приобретет статус "Authorized".

Авторизованная транзакция

Оплачен — счет получает данный статус после успешной оплаты, т.е. денежные средства списаны с карточки покупателя. В поле "Оплачено" отобразится сумма, которая была оплачена плательщиком и транзакция приобретет статус "Completed".

Финансово завершенная транзакция

Не оплачен — оплата по счету не была произведена в установленный при создании срок. Для продления срока на оплату счета, следует нажать на кнопку "Изменить счет".

Не оплаченный счет

Сброшенный после авторизации — сброшенная после авторизации оплата, т.е. денежные средства разблокированы на карт-счете покупателя. Транзакция приобретает статус "Voided".

Сброшенная после авторизации транзакция

Частичная отмена — инициирован частичный возврат денежных средств на карт-счет покупателя. В поле "Оплачено" сумма равна разнице между суммой заказа и возврата. Транзакция приобретает статус "Refunded".

Частично отмененная транзакция

Отменен — инициирован возврат денежных средств на карт-счет покупателя. В поле "Оплачено" сумма равна нулю. Транзакция приобретает статус "Refunded".

Отмененная транзакция

Рекуррентный — рекуррентный (CoF) платеж. Платеж, осуществленный по привязанной карте без участия плательщика.

Рекуррентная транзакция

Важно!

Обращаем Ваше внимание, что при осуществлении оплаты через АИС "Расчет" (ЕРИП), счета будут приобретать только статусы: "Ожидание оплаты", "Оплачен" и "Не оплачен".

Типы операций в системе WEBPAY

В случае возникновения каких-либо претензий относительно качества предоставляемого товара или услуги, покупатель имеет право обратиться в интернет-магазин с просьбой произвести отмену платежа.

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

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

Важно!

Обратите внимание, что в системе WEBPAY возврат/отмену можно осуществить только по платежам, оплаченным через интернет-эквайринг. Оплаты через АИС "Расчет" (ЕРИП) возврату/отмене не подлежат.

Подтверждение и отмена авторизации

В момент оплаты происходит блокировка требуемой суммы на карточке плательщика, которая становится недоступна для использования. В системе WEBPAY такой платеж отмечается в списке платежей статусом "Authorized".

Реальное списание денежных средств с карточки плательщика происходит после финансового подтверждения платежа. После того, как финансовое подтверждение совершено, денежные средства с карточки клиента зачисляются на р/с Вашей компании в установленные договором интернет-эквайринга сроки.

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

В системе WEBPAY платеж, по которому осуществлено финансовое подтверждение отмечается в списке платежей статусом "Completed".

В системе WEBPAY существует две стадии прохождения платежей:

  1. Одностадийные платежи — платежи, по которым сразу же происходит финансовое завершение (статус транзакции Completed), т.е. денежные средства с карты плательщика сразу же списываются. Преимуществом этого способа работы является то, что денежные средства на расчетный счет организации поступают в период, установленный банком-эквайером. Минусом является то, что возврат денежных средств на карту плательщика может достигать 30 дней в зависимости от банка-эмитента.
  2. Двухстадийные платежи — платежи, по которым сначала денежные средства блокируются на карте плательщика (статус транзакции Authorized), затем через оговоренный срок наступает финансовое завершение (статус транзакции Completed). Преимуществом является то, что у организации существует дополнительное время на проверку наличия товара/возможности оказать услугу. При отмене заказа денежные средства будут сразу же разблокированы на карте плательщика. Минусом такого способа является то, что существует задержка поступления денежных средств на расчетный счет на срок, равный сроку авторизации плюс срок зачисления, установленный банком-эквайером.
Список успешных транзакций

Авторизованные платежи в системе WEBPAY могут быть финансово завершены или сброшены (отменены).

Процедура отмены платежа включает следующие этапы:

  • зайдите в раздел "Платежи";
  • нажмите на необходимый платеж, чтобы раскрыть его и нажмите кнопку "Сбросить", после чего авторизация по сделке будет отменена.

После нажатия кнопки "Сбросить" платеж отклонится, вся оплаченная сумма разблокируется на карточке плательщика и станет доступной для использования. При этом транзакция приобретет статус "Сброшенная после авторизации" (Voided).

Осуществление сброса авторизации

В случае нажатия кнопки "Завершение", авторизация по банковской карте подтверждается, транзакция завершается и денежные средства списываются с карты плательщика, а транзакция приобретает статус "Оплачен" (Completed).

Финансовое завершение авторизации

Полный и частичный возврат денежных средств

В том случае, если платеж уже был завершен, т.е. транзакция получила статус "Completed", произвести сброс платежа не получится. В данном случае необходимо будет произвести "Возврат" либо "Частичный возврат" денежных средств.

Процедура возврата платежа включает следующие этапы:

  • зайдите в раздел "Платежи";
  • нажмите на необходимый платеж, чтобы раскрыть его;
  • нажмите на кнопку "Возврат";
  • на открывшейся странице в поле сумма возврата выберите полный или частичный возврат средств. При частичном возврате введите сумму, которая будет возвращена плательщику на ту карту, с которой производилась оплата;
  • нажмите кнопку "Вернуть".

После этого денежные средства возвращаются на карточку плательщика. Зачисление средств на карточку плательщика осуществляется, как правило, в течение недели, по карточкам, выпущенным белорусскими банками. По карточкам зарубежного банка срок возврата может достигать одного месяца. Данный параметр во многом зависит от банка, выпустившего карточку. После успешного возврата, транзакция приобретает статус "Частичная отмена/отменен" (Refunded).

Осуществление возврата по операции

Введение в среду разработки Sandbox

WEBPAY Sandbox — это самостоятельное Web-приложение, являющееся прототипом реальной системы и предназначенное для тестирования и ознакомления с возможностями реальной системы WEBPAY. По своим функциональным возможностям она ничем не отличается от рабочей копии, за исключением того, что не выполняет реального процессинга банковских карточек, т.е. никакие действия не приводят к реальному перемещению средств на карточках. Разработку и тестирование платежных модулей всегда необходимо производить в тестовой среде.

Параметры тестовой среды

НазваниеОписание
URL адрес тестовой среды:https://sandbox.webpay.by
Имя пользователя (login):высылается в письме
Пароль:высылается в письме
Уникальный идентификатор магазина (wsb_storeid):высылается в письме

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

тип: VISA

номер: 434179xxxxxx0051 (данное поле по умолчанию недоступно для редактирования)

CVV/CVC2: любые три цифры

срок действия карточки: любой. Для совершения оплаты с ошибкой введите декабрь месяц и год — текущий плюс 1. Например: текущий год 2019, значит значение должно быть 12/20.

Переход из тестовой среды в реальную

Обращаем Ваше внимание, что при переходе из тестовой в реальную среду проведения платежей необходимо выполнить ряд условий.

Смена адреса платежной страницы

Для совершения реальной оплаты заказа необходимо сформировать форму со специальными полями и POST методом перенаправить покупателя на страницу оплаты по адресу https://payment.webpay.by.

Адреса платежных страниц:

НазваниеОписание
Тестоваяhttps://securesandbox.webpay.by
Реальнаяhttps://payment.webpay.by

Важно!

В реальной среде обращение к https://payment.webpay.by должно осуществляться с доменного имени, которое было указано в договоре интернет-эквайринга. При этом по правилам платежных систем поддомен считается отдельным ресурсом. То есть, если Вы указали в договоре сайт https://test.by, то и перенаправление на нашу платежную страницу должно осуществляться с https://test.by. В случае если перенаправление будет с ресурса https://bill.test.by — транзакция будет заблокирована. Referer URL регулярно проверяется в соответствии с требованиями платежных систем и банков-эквайеров. В случае если Вы намереваетесь использовать адрес сайта отличный от заявленного в договоре, обратитесь, пожалуйста, к персональному менеджеру WEBPAY.

Также меняется адрес интерфейса Web-приложения:

НазваниеОписание
Тестоваяhttps://sandbox.webpay.by
Реальнаяhttps://billing.webpay.by

Смена идентификатора магазина

Значение идентификатора магазина в системе WEBPAY передается в поле wsb_storeid. Данный параметр создается при регистрации и высылается в письме персональным менеджером в компании WEBPAY. Необходимо заменить его на значение идентификатора магазина (wsb_storeid) из реальной среды.

Смена флага тестового платежа

При проведении платежей в тестовой среде в качестве флага о том, что оплату по заказу необходимо провести не через реальную систему, а с использованием эмулятора платежной системы, отвечало поле wsb_test со значением равным 1. Для проведения платежей через реальную систему, необходимо установить значение поля равным 0.

Интеграция платежей

Разработка платежного модуля осуществляется на стороне сервера подключаемого клиента и предполагает создание либо внесение изменений в исходный код скриптов дорабатываемого Web-приложения.

Карточные операции

Способы формирования заказа

Система WEBPAY предусматривает два способа формирования заказов на оплату:

  1. JSON API https://docs.webpay.by/payment-json.html.
  2. Создание HTML-страницы с обыкновенной HTML-формой.

Принцип формирования и оплаты заказа

  1. Формирование заказа путем создания запроса с использованием JSON API либо путем создания HTML-страницы с обыкновенной HTML-формой (Поля формы оплаты).
  2. Осуществление перехода на платежную страницу системы WEBPAY (https://securesandbox.webpay.by), для ввода реквизитов платежной карточки (переход осуществляется POST методом).
  3. Ввод данных платежной карточки.
  4. Оплата заказа.
  5. Возврат на html-страницу модуля оплаты (системой WEBPAY будет отправлен нотификатор (Нотификатор об оплате).
  6. Проверка параметров платежа.
  7. Оказание услуги (доставка товара).

Формирование заказа для оплаты

Для оплаты заказа необходимо сформировать JSON API запрос либо HTML форму со специальными полями, значения и описание полей представлены в разделе Поля формы оплаты, и POST методом перенаправить покупателя на страницу оплаты. Для тестирования необходимо указать адрес https://securesandbox.webpay.by, для совершения реальных платежей — https://payment.webpay.by.

Поля формы оплаты

Важно!

Все текстовые поля должны быть в кодировке UTF-8.

Основные поля формы оплаты

Название поляОбязательное полеОписание поляПримечание
*scartдаПоле не содержит значения и обозначает тип запроса.
wsb_storeidдаИдентификатор магазина в системе WEBPAY. Данный идентификатор создается при регистрации в системе WEBPAY и высылается в письме.
wsb_storeнетНазвание магазина, которое будет отображаться на форме оплаты. По умолчанию берется из настроек биллинг-аккаунта.Максимальная длина поля 64 символа.
wsb_order_numдаУникальный идентификатор заказа, присваиваемый магазином.Максимальная длина поля 64 символа. При оплате через ЕРИП значение поля не может начинаться на 0 (ноль).
wsb_currency_idдаИдентификатор валюты. Буквенный трехзначный код валюты согласно ISO4271.Допустимые значения: BYN, USD, EUR, RUB.
wsb_versionдаВерсия формы оплаты.Текущий номер версии: 2.
wsb_language_idнетИдентификатор языка формы оплаты.Допустимые значения: russian, english. При отсутствии значения определяется по настройкам браузера.
wsb_seedдаСлучайная последовательность символов, участвующих в формировании подписи заказа.Перейти к разделу: Электронная подпись заказа.
wsb_signatureдаКонтрольное значение (электронная подпись) заказа — результат выполнения функции SHA1 (для версии 2, см. поле wsb_version) либо MD5, если версия протокола не указана. Данное значение является hex-последовательностью.Перейти к разделу: Электронная подпись заказа.
wsb_return_urlнетURL адрес, на который возвращается покупатель в случае успешной оплаты.К данному URL добавляются значения Идентификатора заказа (wsb_order_num) и номера транзакции (wsb_tid) в системе WEBPAY.
wsb_cancel_return_urlнетURL адрес, на который возвращается покупатель в случае не успешной оплаты.К данному URL добавляются значение Идентификатора заказа (wsb_order_num).
wsb_notify_urlнет

Данный URL вызывается вне зависимости от того, был ли переход по URL в поле wsb_return_url или нет. Основное назначение этого URL оповестить сайт об успешной оплате в случае, если пользователь не нажал кнопку "Вернуться на сайт" на форме оплаты. По умолчанию берется из настроек биллинг-аккаунта.

Внимание! Отправка нотификаторов возможна только на стандартные порты: 80 (http), 443 (https), 8080 (http_alt), 8443(pcsync-https).

Перейти к разделу: Нотификатор об оплате.
wsb_testда

Поле, указывающее на проведение тестовой оплаты.

1 — производить тестовую оплату;

0 — производить реальную оплату.

В тестовой среде Sandbox значение данного поля должно быть равным 1.
wsb_customer_nameнетНаименование получателя товара/услуги.Максимальная длина поля 255 символов.
wsb_customer_addressнетАдрес получателя товара/услуги.Максимальная длина поля 255 символов.
wsb_service_dateнетСроки предоставления товаров/услуг/работ.Максимальная длина поля 255 символов.

Поля для формирования корзины товаров/услуг

Название поляОбязательное полеОписание поляПримечание
wsb_invoice_item_name[{n}]даНаименование единицы товара.Индекс {n}, должен начинаться с 0 и увеличиваться на 1 для каждой последующей позиции.
wsb_invoice_item_quantity[{n}]даКоличество единиц товара. Целое число, обозначающее количество единиц товара каждого наименования.Индекс {n}, должен начинаться с 0 и увеличиваться на 1 для каждой последующей позиции.
wsb_invoice_item_price[{n}]даЦена единицы товара. Число, определяющее стоимость каждой единицы товара (BYN, USD, EUR, RUB с 2 знаками после запятой или точки).Индекс {n}, должен начинаться с 0 и увеличиваться на 1 для каждой последующей позиции.
wsb_taxнетПоле, значением которого является сумма налога в белорусских рублях, добавляемая к общей сумме заказа.При оплате через ЕРИП это поле не учитывается (сумма налога добавляется к сумме единицы товара).
wsb_shipping_nameнетПоле определяющее наименование (способ) доставки.Максимальная длина поля 255 символов.
wsb_shipping_priceнетПоле, значением которого является сумма доставки, добавляемая к общей сумме заказа.
wsb_discount_nameнетПоле с описанием скидки.Максимальная длина поля 255 символов.
wsb_discount_priceнетПоле, значением которого является сумма скидки, вычитаемая из общей суммы заказа.Значение должно быть положительным числом (без знака "-" минус).
wsb_discount_promo_codeнетПоле содержит значение промокода скидки для заказа при работе со скидочными программами VISA и MASTERCARD.Максимальная длина поля 32 символа.
wsb_totalда

Данное поле является вычисляемым. Значение этого поля является общей суммой оплаты заказа. Правило вычисления общей суммы:

wsb_total = wsb_invoice_item_quantity[0] * wsb_invoice_item_price[0] + wsb_invoice_item_quantity[1] * wsb_invoice_item_price[1] +

...

wsb_invoice_item_quantity[n] * wsb_invoice_item_price[n] + wsb_tax + wsb_shipping_price - wsb_discount_price.

Оплата не будет произведена, если wsb_total и посчитанное значение товаров не будет совпадать. Покупателю будет отображена ошибка.

Дополнительные поля

Название поляОбязательное полеОписание поляПримечание
wsb_order_tagнетМетка заказа. Используется для отнесения заказа к определенной категории, группировки заказов или других нужд.Максимальная длина поля 64 символов.
wsb_emailнетЭлектронный адрес покупателя.Значение данного поля будет автоматически подставлено в соответствующее поле формы оплаты.
wsb_phoneнетНомер телефона покупателя.
wsb_order_contractнетНомер договора с заказчиком услуги/плательщиком.
wsb_tabнетОпределение активной вкладки с нужным платежным инструментом (оплата картой/ЕРИП).Возможные значения: erip, cardPayment. При отсутствии поля порядок вкладок стандартный — оплата картой, потом ЕРИП.
wsb_card_number_shortнет

Определение возможности осуществления оплаты указанной плательщиком карты.

Системой WEBPAY производится сверка данных номера карты (первые 6 и последние 4 цифры) между переданным номером карты в данном поле и тем, что ввел плательщик при оплате.

Если первые 6 и последние 4 цифры номера карты совпадают, то оплата разрешается, иначе попытка оплаты откланяется и плательщику выводится ошибка.

Значением является целое число, которое состоит из первых 6 и последних 4 цифр номера карты. Например: 1234561234.

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="1">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_customer_name" value="Иванов Петр Петрович">
  <input type="hidden" name="wsb_customer_address" value="Минск ул. Шафарнянская д.11 оф.54">
  <input type="hidden" name="wsb_service_date" value="Доставка до 1 января 2016 года">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="31.40">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="266e9c04a24dfb5fc75775c42a831a49488f8303">
  <input type="hidden" name="wsb_tax" value="10.50">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_order_contract" value="Договор №152/12-1 от 12.01.19">
  <input type="submit" value="Купить">
</form>

Параметры регулирования платежной сессии

Существует механизм регулирования времени отведенного на оплату со стороны Интернет-ресурса. Для этого в авторизационном запросе необходимо передать параметр, который будет указывать, с какого времени производить отсчет отведенного для оплаты интервала (по умолчанию 20 минут). В авторизационном запросе необходимо передать параметр wsb_startsessdatetime со значением типа DateTime (например, 2020-10-22T16:20:01+03:00) или параметр wsb_startsesstime, который содержит значение в формате UnixTimestamp (например, 1603383601). При передаче двух параметров, приоритетным считается wsb_startsessdatetime.

Например, транзакция начинается 22.10.2020 16:33:01, Интернет-ресурс хочет, чтобы платежная сессия действовала 7 мин., в POST запросе необходимо передать время 22.10.2020 16:20:01

Пример кода

<input type="hidden" name="wsb_startsesstime" value="1603383601">
<input type="hidden" name="wsb_startsessdatetime" value="2020-10-22T16:20:01+03:00">

Электронная подпись заказа

Электронная подпись формируется для предотвращения изменений в форме платежа и должна присутствовать в каждой форме заказа. Все заказы без электронной подписи не будут рассматриваться системой WEBPAY.

Для формирования электронной подписи необходимо установить значение поля "Секретный ключ" в настройках Вашего биллинг-аккаунта (Установка секретного ключа).

В каждой форме заказа необходимо указывать поля:

wsb_seed — случайная последовательность символов (можно использовать текущее значение времени, к примеру, Unix Timestamp);

wsb_signature — непосредственно сама электронная подпись. Она должна быть сформирована согласно следующему правилу из значений следующих полей:

  • wsb_seed
  • wsb_storeid
  • wsb_order_num
  • wsb_test
  • wsb_currency_id
  • wsb_total
  • SecretKey

Поля должны быть объединены в одну строку, порядок объединения не должен быть нарушен.

Далее в зависимости от указанной версии протокола (wsb_version), считается MD5 (если версия не указана), либо SHA1 (для версии 2) объединенной строки.

Пример кода

$wsb_seed = 1242649174;
$wsb_storeid = 11111111;
$wsb_order_num = "ORDER-12345678";
$wsb_test = 1;
$wsb_currency_id = "BYN";
$wsb_total = 21.90;
$SecretKey = "12345678901234567890";
// Значение объединенной строки:
// 124264917411111111ORDER-123456781BYN21.9012345678901234567890
// для версии протокола 2 (wsb_version = 2)
$wsb_signature = sha1($wsb_seed.$wsb_storeid.$wsb_order_num.$wsb_test.$wsb_currency_id.$wsb_total.$SecretKey);
// 338d1647833079f9353907ad266ec0bb5264c0d9
// если версия не указана
$wsb_signature = md5($wsb_seed.$wsb_storeid.$wsb_order_num.$wsb_test.$wsb_currency_id.$wsb_total.$SecretKey);
// 5b712daa1743d1a62dfdb7054b3978a1

Оплата заказа

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

После успешной оплаты заказа покупатель должен нажать кнопку "Вернуться на сайт", в этом случае форма оплаты перенаправит его по URL-адресу, указанному в поле wsb_return_url.

При ошибке оплаты и нажатии кнопки "Назад" покупатель будет перенаправлен на URL-адрес, указанный в поле wsb_cancel_return_url. В каждом из этих случаев к URL-адресу будут дописаны значения wsb_order_num, а в случае успешной оплаты, будет также дописано значение номера транзакции в системе WEBPAY.

Важно!

Возможны ситуации, при которых покупатель не нажмет кнопку "Назад" на форме оплаты. Для уведомления об успешной операции система WEBPAY, через некоторое время, отсылает специальный нотификатор (Нотификатор об оплате).

Оплата заказа

Нотификатор об оплате

В случае успешной оплаты, при возврате на страницу Интернет-ресурса (используется значение, указанное в поле wsb_return_url), система передает в параметрах GET запроса номер заказа (значение поля wsb_order_num) и номер транзакции (поле wsb_tid), соответствующие проведенному платежу.

Также система известит Интернет-ресурс о проведенной операции по адресу wsb_notify_url (если он указан в поле формы) либо на "URL для уведомлений", значение которого можно установить в настройках биллинг-аккаунта в разделе меню "Настройки" → "Компания".

Отправка нотификаторов от системы WEBPAY осуществляется с адреса: 178.163.225.84.

Установка URL для уведомлений

В случае если адрес для получения нотификатора будет указан и в поле формы (wsb_notify_url), и в настройках биллинг-аккаунта, то будет использован адрес из POST-запроса, указанный в поле wsb_notify_url.

Интернет-ресурс, в случае оповещения, должен ответить кодом 200 ("HTTP/1.0 200 OK"). Через 30 дней, если Интернет-ресурс так и не смог принять уведомление, отсылка запросов прекращается.

При разработке необходимо учесть, что может прийти как и извещение о платеже (wsb_notify_url), так и покупатель может вернуться на страницу Интернет-ресурса, указанную в поле (wsb_return_url).

Важно!

Обращаем внимание, что время платежной сессии составляет 20 минут и плательщик в течение этого времени может производить оплату, в связи с этим нотификатор не приходит сразу же после направления в систему WEBPAY авторизационного запроса на оплату.

Нотификатор отправляется только после получения системой WEBPAY результата оплаты. По умолчанию нотификатор отправляется только по успешным операциям. В случае необходимости получения нотификаторов и по неуспешным оплатам, рекомендуем обратиться в техническую поддержку WEBPAY.

Если в течении 20 минут после отправки Интернет-ресурсом авторизационного запроса плательщик не был перенаправлен по адресам wsb_return_url или wsb_cancel_return_url и/или Интернет-ресурсом не был получен нотификатор, то рекомендуем воспользоваться методом GetTransactionStatus API для управления карточными операциями либо обратиться в службу поддержки WEBPAY на support@webpay.by для уточнения статуса по операции.

Получение извещения об успешной оплате

Для получения извещения об оплате доступно два способа:

  1. Стандартный POST-запрос, отправляемый с АПК WEBPAY на wsb_notify_url (используется по умолчанию).
  2. Через механизм SOAP (может быть включен по запросу).

Стандартный POST-запрос, отправляемый с АПК WEBPAY на wsb_notify_url

После совершения удачного платежа, система WEBPAY отсылает специально сформированный POST-запрос по адресу, указанному в поле wsb_notify_url Интернет-ресурса. В этом запросе содержится информация по платежу. Полученную информацию Интернет-ресурс должен проверить в соответствии с требованиями выполнения заказа и ответить на запрос кодом 200 ("HTTP/1.0 200 OK").

Поля, содержащиеся в запросе:

НазваниеОписание
batch_timestampВремя совершения транзакции
currency_idВалюта транзакции
amountСумма транзакции
payment_methodМетод совершения транзакции. Возможные значения:
  • test — совершена без реального процессинга карточки
  • cc — банковская карточка
  • erip — ЕРИП
  • apple — оплата Apple Pay
order_idНомер заказа в системе WEBPAY
site_order_idНомер (имя) заказа, присвоенное магазином
transaction_idНомер транзакции
payment_typeТип транзакции. Успешной оплате соответствуют значения: 1 и 4
rrnНомер транзакции в системе VISA/MASTERCARD/БЕЛКАРТ
wsb_signatureЭлектронная подпись (вычисляется в случае, если в настройках биллинг-аккаунта указан "Секретный ключ")
actionКод платежа процессинга
rcВнутренний код WEBPAY результата операции
approvalКод операции процессинга
country_alpha_three_codeКод страны банка-эмитента в ISO 3166-1 alpha-3. Для включения данного поля в нотификатор необходимо обратиться в support@webpay.by

wsb_signature представляет собой hex-последовательность и является результатом выполнения функции MD5. В качестве аргумента функции MD5 служит текстовая последовательность, полученная путем простой конкатенации следующих полей:

  • batch_timestamp
  • currency_id
  • amount
  • payment_method
  • order_id
  • site_order_id
  • transaction_id
  • payment_type
  • rrn
  • SecretKey

В случае необходимости можно самостоятельно отправить повторно нотификатор по авторизованной транзакции. Для этого в биллинг-аккаунте в разделе "Платежи" найдите интересующую транзакцию и нажмите кнопку "Отправить нотификатор".

Пример кода

application/x-www-form-urlencoded

{batch_timestamp=1562591640&currency_id=USD&amount=300&payment_method=cc&order_id=127386&site_order_id=16&transaction_id=858578101&
payment_type=4&rrn=786755995452&wsb_signature=001a1e46c8ba6c9934dc60975ecc9f75&action=0&rc=W0001%2800%29&approval=786755&
country_alpha_three_code=USA}

Механизм SOAP

Для механизма SOAP (может быть включен по запросу), система WEBPAY отсылает специально сформированный SOAP-запрос по адресу, указанному в поле wsb_notify_url Интернет-ресурса. Структура нотификатора описана в xsd схеме:

WsbSignature представляет собой hex-последовательность и является результатом выполнения функции MD5. В качестве аргумента функции MD5 служит текстовая последовательность, полученная путем простой конкатенации следующих полей:

  • batch_timestamp
  • currency_id
  • amount
  • payment_method
  • order_id
  • site_order_id
  • transaction_id
  • payment_type
  • rrn
  • card
  • SecretKey

Поля должны быть объединены в указанном порядке.

Важно!

Поле SecretKey учитывается при формировании подписи только в реальной среде.

Пример кода

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://ws.webpay.by/notifier">
  <xs:element name="NotifierRequest">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="1" maxOccurs="1" name="BatchTimestamp" type="xs:int"/>
        <xs:element minOccurs="1" maxOccurs="1" name="CurrencyId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="Amount" type="xs:decimal"/>
        <xs:element minOccurs="1" maxOccurs="1" name="PaymentMethod" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="OrderId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="SiteOrderId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="TransactionId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="PaymentType" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="RRN" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="WsbSignature" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="Action" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="RC" type="xs:string"/>
        <xs:element minOccurs="0" name="Card" type="xs:string"/>
        <xs:element minOccurs="0" name="CountryAlphaThreeCode" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Пример запроса, согласно схеме

Пример кода

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
      <ns2:NotifierRequest xmlns:ns2="http://ws.webpay.by/notifier">
        <ns2:BatchTimestamp>1550480633</ns2:BatchTimestamp>
        <ns2:CurrencyId>BYN</ns2:CurrencyId>
        <ns2:Amount>547.5</ns2:Amount>
        <ns2:PaymentMethod>cc</ns2:PaymentMethod>
        <ns2:OrderId>117524</ns2:OrderId>
        <ns2:SiteOrderId>19020402513459776</ns2:SiteOrderId>
        <ns2:TransactionId>610030693</ns2:TransactionId>
        <ns2:PaymentType>4</ns2:PaymentType>
        <ns2:RRN>145043593722</ns2:RRN>
        <ns2:WsbSignature>e71ceb051ff142c843bc3d520ac35a21</ns2:WsbSignature>
        <ns2:Action>0</ns2:Action>
        <ns2:RC>W0001(00)</ns2:RC>
        <ns2:Approval>145043</ns2:Approval>
        <ns2:Card>434444xxxxxx0001</ns2:Card>
        <ns2:Cardholder>pv</ns2:Cardholder>
        <ns2:CountryAlphaThreeCode>USA</ns2:CountryAlphaThreeCode>
        <ns2:OrderTag>onlinePayment</ns2:OrderTag>
      </ns2:NotifierRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Полученную информацию Интернет-ресурс должен проверить в соответствии с требованиями выполнения заказа и ответить на запрос кодом 200.

Пример кода

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://ws.webpay.by/notifier">
  <xs:element name="NotifierResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="code" type="xs:string"/>
        <xs:element name="codeDescription" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

В ответе в поле code должно быть значение, равное 200 в случае, если нотификатор обработан. Если код будет не 200 — будет повторная отправка нотификатора. Значение в поле codeDescription может быть произвольным.

В случае необходимости можно самостоятельно отправить повторно нотификатор по авторизованной транзакции. Для этого в биллинг-аккаунте в разделе "Платежи" найдите интересующую транзакцию и нажмите кнопку "Отправить нотификатор".

Пример кода

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns2:NotifierResponse xmlns:ns2="http://ws.webpay.by/notifier">
      <ns2:code>200</ns2:code>
      <ns2:codeDescription>OK</ns2:codeDescription>
    </ns2:NotifierResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Проверка платежа

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

Для проверки платежа при возврате на страницу Интернет-ресурса, указанную в поле wsb_return_url, необходимо выполнить API команду биллинга "get_transaction" (только для интернет-эквайринга).

Необходимо учитывать, что запрос к тестовой среде необходимо отсылать на адрес https://sandbox.webpay.by, а к реальной среде https://billing.webpay.by.

Пример запроса

<!-- API Request -->
$postdata = '*API=&API_XML_REQUEST='.urlencode('
  <?xml version="1.0" encoding="ISO-8859-1" ?>
    <wsb_api_request>
      <!-- Название метода -->
      <command>get_transaction</command>
      <authorization>
        <!-- Логин от личного кабинета WEBPAY -->
        <username>your_username</username>
        <!-- Пароль от личного кабинета WEBPAY, зашифрованный в MD5 -->
        <password>your_md5_password</password>
      </authorization>
      <fields>
        <!-- ID транзакции, по которой осуществляется проверка.
          Значение приходит в нотификаторе -->
        <transaction_id>123456789</transaction_id>
      </fields>
    </wsb_api_request>
');

$curl = curl_init ("https://sandbox.webpay.by");
curl_setopt ($curl, CURLOPT_HEADER, 0);
curl_setopt ($curl, CURLOPT_POST, 1);
curl_setopt ($curl, CURLOPT_POSTFIELDS, $postdata);
curl_setopt ($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($curl, CURLOPT_SSL_VERIFYHOST, 0);
$response = curl_exec ($curl); curl_close ($curl);
echo $response;

В результате выполнения запроса приходит XML-документ, содержащий следующие поля:

НазваниеОписание
transaction_idНомер транзакции
batch_timestampВремя совершения транзакции
currency_idВалюта транзакции
amountСумма транзакции
payment_methodМетод совершения транзакции. Возможные значения:
  • test — совершена без реального процессинга карточки
  • cc — банковская карточка
  • apple — оплата Apple Pay
payment_typeТип транзакции. Успешной оплате соответствуют значения: 1 и 4
order_idНомер заказа в системе WEBPAY
rrnНомер транзакции в системе VISA/MASTERCARD/БЕЛКАРТ
wsb_signatureЭлектронная подпись (вычисляется в случае, если в настройках биллинг-аккаунта указан "Секретный ключ")

wsb_signature представляет собой hex-последовательность и является результатом выполнения функции MD5. В качестве аргумента функции MD5 служит текстовая последовательность, полученная путем простой конкатенации следующих полей:

  • transaction_id
  • batch_timestamp
  • currency_id
  • amount
  • payment_method
  • payment_type
  • order_id
  • rrn
  • SecretKey

Поля должны быть объединены в указанном порядке.

Важно!

В случае если по каким-либо причинам не был получен ответ от системы WEBPAY рекомендуем повторять отправку запроса с увеличивающейся периодичностью до 1 часа. Если система WEBPAY так и не отдала ответ, то отмечать такие операции и направлять их на support@webpay.by.

Типы транзакций

По типу транзакции (поле payment_type) делятся на следующие группы:

ТипЗначениеОписание
1CompletedЗавершенная
2DeclinedОтклоненная
3PendingВ обработке
4AuthorizedАвторизованная
5Partial RefundedЧастично возвращенная
6SystemСистемная
7VoidedСброшенная после авторизации
8FailedОшибка в проведении операции
9Partial VoidedЧастичный сброс
10RecurrentРекуррентный платеж (CoF)
11RefundedВозвращенная

Важно!

При написании кода обработки дополнительных извещений следует учитывать тип транзакции. Данный тип уведомления предназначен для извещения Интернет-ресурса об успешно завершенных транзакциях и о транзакциях, которые впоследствии отменены самим Интернет-ресурсом (возврат денег покупателю).

Таким образом, успешной оплате соответствуют следующие типы:

ТипЗначениеОписание
1CompletedЗавершенная
4AuthorizedАвторизованная
10RecurrentРекуррентный платеж (CoF)

А отмененным платежам (возврату денег), соответствуют следующие типы:

ТипЗначениеОписание
5Partial RefundedЧастично возвращенная
7VoidedСброшенная после авторизации
9Partial VoidedЧастичный сброс
11RefundedВозвращенная

Следует также обратить внимание на то, что для тестовой среды и для реальной, суммы максимальной и минимальной транзакции различны. Для тестовой среды минимальная сумма платежа составляет 0.1 BYN, максимальной – 10 000 BYN. В реальной среде лимит транзакции устанавливается согласно с условиями договора банка-эквайера.

Упрощенный платеж

Описание процесса работы

Упрощенный платеж — это метод оплаты с использованием банковской карточки, у которого, для набора параметров Учетная запись и Платежная карта Покупателя в рамках Поставщика услуг, нет необходимости вводить все платежные реквизиты. Полностью заполнить все данные необходимо только при выполнении первоначального платежа для инициирования привязки услуги к карте. Для подключения этой услуги необходимо обратиться в техническую поддержку WEBPAY support@webpay.by и внести небольшие изменения в сценарий взаимодействия приложения Поставщика услуг с программным комплексом WEBPAY. Эта опция сделает оплату товаров для Покупателя более удобной, что, в свою очередь, повысит привлекательность ресурса.

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

Привязка карты осуществляется на стороне программного комплекса WEBPAY. Данные покупателя — маска номера карты, имя как на карте, срок действия карты, email и телефон — хранятся в привязке к уникальному номеру Покупателя. Новая карта может быть привязана Покупателем в один клик после любого успешного платежа в пользу Поставщика услуг.

Инициирующий платеж при сценарии Упрощенный платеж

Привязанная к карте услуга "Упрощенный платеж", при следующем приобретении товаров, позволит избежать лишнего ввода информации. Достаточно будет выбрать карту для оплаты из списка и ввести лишь CVV/CVC.

Повторная оплата при сценарии Упрощенный платеж

Важно!

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

Осуществление оплаты

Для внедрения услуги "Упрощенный платеж" Поставщику услуг достаточно внести минимальные изменения в запросе JSON API или HTML-форме из раздела Формирование заказа для оплаты для перехода к выполнению оплаты. Стоит обратить внимание, что оплата в тестовой среде по умолчанию производится всегда по одной карте, которая подставляется автоматически. Для того, чтобы была возможность ввести разные карты и произвести их привязку, параметру wsb_test необходимо установить значение равное 0.

Также добавляется одно новое поле — wsb_customer_id — это поле, содержит уникальный номер зарегистрированного Покупателя на стороне Поставщика услуг (максимальная длина поля 64 символа).

Данный параметр должен участвовать в формировании подписи заказа. Таким образом, изменяется алгоритм расчета подписи заказа. Электронная подпись wsb_signature должна быть сформирована согласно следующему правилу из значений следующих полей:

  • wsb_seed
  • wsb_storeid
  • wsb_customer_id
  • wsb_order_num
  • wsb_test
  • wsb_currency_id
  • wsb_total
  • SecretKey

Поля должны быть объединены в одну строку, порядок объединения не должен быть нарушен. Далее, в зависимости от указанной версии протокола (wsb_version), считается MD5 (если версия не указана), либо SHA1 (для версии 2) объединенной строки.

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="7bba5020b4033e9086e5f4240a24163dc0d4562b">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_customer_id" value="1234567">
  <input type="submit" value="Купить">
</form>

Важно!

  1. Если не внести изменения в протокол взаимодействия с программным комплексом WEBPAY, то все оплаты будут проводиться по стандартной схеме.
  2. Для того, чтобы была возможность ввести разные карты и произвести их привязку, параметру wsb_test необходимо установить значение равное 0.
  3. При тестировании можно указывать любые 16-значные номера карт VISA или MASTERCARD. Создать набор таких карт можно с помощью ресурса http://www.getcreditcardnumbers.com.

Рекуррентный платеж

Описание процесса работы

В системе WEBPAY существует два способа осуществления оплаты без участия Держателя карты:

  1. Рекуррентные платежи — это платежи с определенной периодичностью, осуществляемые без участия Держателя карты, по требованию Магазина: при наступлении определенных событий либо на регулярной основе. В качестве требования Магазина выступает специально сформированный запрос, отправляемый на ресурс платежного сервиса.
  2. Credential on File (CoF) — это платежи, осуществляемые по привязанной карте, в которых не соблюдается периодичность списаний. Инициатором таких списаний может выступать:
    • Магазин,
    • Держатель карты.

До проведения рекуррентных (CoF) платежей необходимо осуществить инициирующий платеж, служащий контрактом, с участием Держателя карты и с вводом всех данных карты по стандартному сценарию. Дальнейшее осуществление рекуррентных (CoF) платежей происходит без участия Держателя карты и без передачи CVV/CVC. Инициирующий платёж поддерживает 3D-Secure (3DS). Рекуррентные (CoF) платежи не имеют возможности обеспечить поддержку 3DS.

Сумма рекуррентного (CoF) платежа может не совпадать с суммой инициирующего платежа. Настройки типа транзакции осуществляются на стороне WEBPAY в зависимости от бизнес-процесса Магазина.

Сценарий использования рекуррентных (Credential on File) платежей

Держатель карты осуществляет переход с ресурса Магазина POST-запросом на ресурс платежного сервиса, после чего Держателю карты предлагается ввести реквизиты банковской платежной карты и дополнительные параметры. Далее осуществляется стандартный сценарий проведения платежа, включая, при необходимости, прохождение 3DS.

В случае успешного завершения платежа сервис привязывает карту к Держателю карты Магазина, идентифицируемого описанным далее способом.

По завершении платежа возможен переход на ресурс Магазина на один из URL, указанных Магазином (для случаев успешного (параметр wsb_return_url) и неудачного (параметр wsb_cancel_return_url) завершения платежа). Дополнительно отправляется нотификатор на еще один URL (параметр wsb_notify_url). Нотификатор с сообщением о результате инициирующего платежа содержит идентификатор пользователя, маскированный номер карты и срок действия подписки на механизм рекуррентных (CoF) платежей.

При успешном инициирующем платеже Магазин может проводить рекуррентные (CoF) платежи.

Идентификацонный номер держателя карты, параметры привязки карты

Держатель карты должен быть зарегистрирован на ресурсе Магазина. Магазин присваивает ему уникальный идентификатор, передаваемый в запросах на проведение платежей как параметр wsb_сustomer_id. К данному идентификатору для данного Магазина (wsb_storeid) будет осуществлена привязка карты.

Поля формы оплаты для рекуррентных платежей

Система WEBPAY предусматривает два способа формирования заказов на оплату:

  1. JSON API https://docs.webpay.by/payment-json.html.
  2. Создание HTML-страницы с обыкновенной HTML-формой.

При работе с HTML-формой с описанием основных полей для осуществления POST-запроса можно ознакомиться в разделе Поля формы оплаты.

Для указания в авторизационном запросе использования рекуррентных (CoF) платежей необходимо дополнительно использовать следующие поля:

Важно!

Все текстовые поля должны быть в кодировке UTF-8.

Название поляОбязательное полеОписание поляПримечание
wsb_customer_idдаУникальный идентификатор пользователя в Магазине.Максимальная длина поля 64 символа.
wsb_operation_typeдаОбозначает тип запроса.Допустимые значения:
  • recurring_bind — привязать карту к аккаунту;
  • recurring_pay — осуществить рекуррентный (CoF) платеж;
  • recurring_unbind — отвязать карту от аккаунта.
wsb_recurring_tokenдаУникальный токен привязки карты к идентификатору пользователя в Магазине (wsb_customer_id).Значение данного поля соответствует значению поля recurring_token, переданного в нотификаторе после привязки карты.

Адреса платежного сервиса для осуществления запросов

Для осуществления рекуррентных (CoF) запросов в тестовом режиме необходимо использовать адрес https://securesandbox.webpay.by, для совершения реальных платежей https://payment.webpay.by.

Инициирующий платеж

Для осуществления инициирующего платежа можно воспользоваться JSON API либо сформировать форму со специальными полями, значения и описания которых представлены в разделе Поля формы оплаты и Дополнительные поля формы оплаты. Затем POST-методом перенаправить покупателя на страницу платежного сервиса.

Для того, чтобы в тестовой среде был доступен ввод разных номеров карт, необходимо параметр wsb_test передать со значением 0.

Для предотвращения несанкционированных изменений в форме платежа должна присутствовать электронная подпись заказа, параметр wsb_signature. Попытки осуществить платежи без электронной подписи не будут рассматриваться платежной системой.

Важно!

Для формирования электронной подписи необходимо установить значение поля "Секретный ключ" (SecretKey) в настройках Вашего биллинг-аккаунта (ознакомиться можно в разделе Установка секретного ключа).

Подпись вычисляется по следующему алгоритму:

  1. Указанные поля должны быть объединены в одну строку, порядок объединения не должен быть нарушен:
    • wsb_seed
    • wsb_storeid
    • wsb_customer_id
    • wsb_order_num
    • wsb_test
    • wsb_currency_id
    • wsb_total
    • wsb_operation_type
    • SecretKey
  2. Далее в зависимости от указанной версии протокола (wsb_version), считается MD5 (если версия не указана), либо SHA1 (для версии 2) объединенной строки.

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="ebefd130602a41f95238b5bd5cd1f3f803456093">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_customer_id" value="aA1217Zz">
  <input type="hidden" name="wsb_operation_type" value="recurring_bind">
  <input type="submit" value="Купить">
</form>

Оповещение после инициирующей оплаты

После успешной оплаты Плательщику отправляется email с чеком оплаты и сообщением о подписке. Магазину отправляется нотификатор в виде специально сформированного POST-запроса. Поля содержащиеся в нотификаторе представлены ниже.

НазваниеОписание
batch_timestampВремя совершения транзакции
currency_idВалюта транзакции
amountСумма транзакции
payment_methodМетод совершения транзакции. Возможные значения: сс — банковская карточка; test — совершена без реального процессинга карточки
order_idНомер заказа в системе WEBPAY
site_order_idНомер (имя) заказа, присвоенный Магазином
transaction_idНомер транзакции
payment_typeТип транзакции. Подробнее можно ознакомиться в разделе Типы транзакций
rrnНомер транзакции в системе VISA/MASTERCARD
wsb_signatureЭлектронная подпись
actionКод платежа процессинга
rcВнутренний код WEBPAY результата операции
approvalКод операции процессинга
rc_textТекстовое представление внутреннего кода WEBPAY
cardМаскированный номер карты, по которой осуществлены платеж и привязка
customer_idИдентификатор пользователя в системе Магазина
operation_typeНаименование выполненной операции: recurring_bind — привязать карту к аккаунту; recurring_pay — осуществить рекуррентный (CoF) платеж; recurring_unbind — отвязать карту от аккаунта
recurring_tokenТокен привязки карты, предназначенный для выполнения последующих рекуррентных (CoF) платежей
offer_exp_dateСрок действия карты в формате YYYY-MM-DD (например, 2020-10-31)

Параметр wsb_signature сформирован согласно следующему правилу. Значения следующих полей должны быть объединены в одну строку, порядок объединения не должен быть нарушен:

  • batch_timestamp
  • currency_id
  • amount
  • payment_method
  • order_id
  • site_order_id
  • transaction_id
  • payment_type
  • rrn
  • card
  • customer_id
  • operation_type
  • recurring_token
  • offer_exp_date
  • SecretKey

По умолчанию считается MD5 строки.

Важно!

В случае если по каким-либо причинам не был получен нотификатор, а плательщик утверждает, что оплата была осуществлена успешно, рекомендуем воспользоваться методом GetTransactionStatus API для управления карточными операциями либо обратиться в службу поддержки WEBPAY на support@webpay.by для уточнения статуса по операции.

Рекуррентный платеж (Credential on File)

При работе с JSON API следует использовать следующий запрос.

При работе с HTML-формой относительно инициирующего платежа производятся следующие изменения:

Параметр wsb_recurring_token включается в подпись после параметра wsb_operation_type:

  • wsb_seed
  • wsb_storeid
  • wsb_customer_id
  • wsb_order_num
  • wsb_test
  • wsb_currency_id
  • wsb_total
  • wsb_operation_type
  • wsb_recurring_token
  • SecretKey

При получении запроса для оплаты заказа, система WEBPAY проверяет срок действия рекуррентного (CoF) платежа. Если срок подписки истек, платеж совершен не будет. При валидном сроке подписки карты для данного пользователя происходит оплата услуги без отображения платежной страницы.

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="d1a5110dc27d38a5fed50f98def59029ed5e1564">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_customer_id" value="aA1217Zz">
  <input type="hidden" name="wsb_operation_type" value="recurring_pay">
  <input type="hidden" name="wsb_recurring_token" value="123456789">
  <input type="submit" value="Купить">
</form>

Оповещение после рекуррентного платежа

После успешной оплаты Магазину отправляется нотификатор с аналогичными полями, описанными в предыдущем разделе, с некоторыми исключениями. Запрос не содержит поле offer_exp_date и соответственно данное поле не участвует в расчете подписи.

Также в ответ на запрос на оплату рекуррентного платежа Магазин получает оповещение.

Пример ответа

// Ответ об успешном рекуррентном платеже

Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586712564&currency_id=BYN&amount=15&payment_method=cc&order_id=294088281&site_order_id=ORDER-15&transaction_id=650449721&
payment_type=10&rrn=210476022664&wsb_signature=66e6be413ea2d8638174e3b69f1ffd32&action=0&rc=W0001%2800%29&approval=210476&
rc_text=Операция завершена успешно&card=516052xxxxxx9495&customer_id=test_1&operation_type=recurring_pay&recurring_token=650449721

// Ответ об ошибке рекуррентного платежа

Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586714748&currency_id=BYN&amount=35&payment_method=cc&order_id=0&site_order_id=ORDER-16&transaction_id=0&payment_type=2&
rrn=&wsb_signature=25ac063bbf766c4401858439f3fbd61c&action=4&rc=W0319&approval=&rc_text=Ошибка&card=516052xxxxxx9495&customer_id=test_1&
operation_type=recurring_bind&recurring_token=0&offer_exp_date=2022-10-31

Отвязка карты от рекуррентных (Credential on File) платежей

Для осуществления отвязки карты от рекуррентных (CoF) платежей с помощью JSON API следует использовать следующий запрос.

При работе с HTML-формой запрос на отвязку карты от рекуррентных (CoF) платежей должен состоять из следующего набора полей:

  • wsb_version
  • wsb_seed
  • wsb_storeid
  • wsb_customer_id
  • wsb_operation_type
  • wsb_recurring_token
  • wsb_signature

Параметр wsb_signature вычисляется путем объединения в одну строку, следующих полей:

  • wsb_seed
  • wsb_storeid
  • wsb_customer_id
  • wsb_operation_type
  • wsb_recurring_token
  • SecretKey

Порядок объединения полей не должен быть нарушен. Далее в зависимости от указанной версии протокола (wsb_version), считается MD5 (если версия не указана), либо SHA1 (для версии 2) объединенной строки.

Пример кода

<!DOCTYPE html>
  <html>
    <head>
      <title></title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <?php
      $secret_key = 'jPwe3d5nmN';
      $wsb_storeid = '507990464';
      $wsb_seed = time();
      $wsb_customer_id = '111333';
      $operation_type = 'recurring_unbind';
      $wsb_recurring_token = 904928145;
      $wsb_signature = sha1($wsb_seed.$wsb_storeid.$wsb_customer_id.$operation_type.$wsb_recurring_token.$secret_key);
    ?>
    <body>
      <form action="http://securesandbox.webpay.by" method="post" target="_blanc">
        <input type="hidden" name="*scart">
        <input type="hidden" name="wsb_version" value="2" />
        <input type="hidden" name="wsb_seed" value="<?=$wsb_seed?>">
        <input type="hidden" name="wsb_storeid" value="<?=$wsb_storeid?>">
        <input type="hidden" name="wsb_customer_id" value="<?= $wsb_customer_id ?>">
        <input type="hidden" name="wsb_operation_type" value="<?= $operation_type ?>">
        <input type="hidden" name="wsb_recurring_token" value="<?= $wsb_recurring_token ?>">
        <input type="hidden" name="wsb_signature" value="<?= $wsb_signature ?>">
        <input type="submit" value="Отказ от подписки на рекуррентные платежи">
      </form>
      </body>
  </html>

Оповещение после отвязки карты от рекуррентных платежей

После каждого запроса на отвязку система WEBPAY отправляет ответ об успешной либо ошибочной отвязке.

Пример ответа

// пример ответа об успешной отвязке

Content-Type: application/json; charset=utf-8
{"batch_timestamp":1586734397,"customer_id":"test_1","operation_type":"recurring_unbind","recurring_token":"606799416","rc":"0",
"rc_text":"Operation success"}

// пример ответа об ошибке

Content-Type: application/json; charset=utf-8
{"batch_timestamp":1586734514,"customer_id":"test_12","operation_type":"recurring_unbind","recurring_token":"606799416","rc":"1018",
"rc_text":"Operation failed"}

Полный или частичный возврат денежных средств

После успешной привязки карты или рекуррентной (CoF) оплаты через систему WEBPAY, в зависимости от выбранного Магазином банка-эквайера, платежи принимают следующие статусы:

Банк-эквайерТип транзакцииСтатус транзакции
"Приорбанк" ОАОИнициирующийAuthorized → Completed
РекуррентныйRecurrent
Credential on FileCompleted
ЗАО "МТБанк"
ОАО "Белагропромбанк"
ОАО "БПС-Сбербанк"
ИнициирующийAuthorized → Completed
РекуррентныйAuthorized → Completed

В случае возникновения ситуации, когда необходимо совершить полный или частичный возврат денежных средств, следует воспользоваться API (раздел Управление операциями). Предварительно необходимо направить запрос в службу поддержки компании WEBPAY на support@webpay.by, указав IP адрес, с которого будут производиться запросы. В зависимости от банка-эквайера и типа транзакции, будет использоваться различный API-запрос на осуществление сброса/возврата.

Банк-эквайерТип транзакцииВид запросаСтатус транзакции
"Приорбанк" ОАОИнициирующий, РекуррентныйTransactionCancel (с указанием суммы, которая должна быть возвращена держателю карты)Voided
Credential on FileTransactionRefund (с указанием суммы, которая должна быть возвращена держателю карты)Refunded
"МТБанк" ЗАО
"Белагропромбанк" ОАО
"БПС-Сбербанк" ОАО
ИнициирующийTransactionCancel (с указанием суммы, которая должна быть возвращена держателю карты)Voided
РекуррентныйTransactionComplete (частичное финансовое завершение на сумму, которая должна быть зачислена Магазину)Completed
TransactionRefund (с указанием суммы, которая должна быть возвращена держателю карты)Refund

Карты рассрочек

Совершение платежей по картам рассрочки "Приорбанк" ОАО и ЗАО "МТБанк"

Для совершения платежей по картам рассрочки "Приорбанк" ОАО или ЗАО "МТБанк" (Халва) достаточно сформировать JSON API запрос либо стандартный авторизационный запрос (HTML-форму) согласно разделу Формирование заказа для оплаты.

Товары, оплачиваемые по картам рассрочки "Приорбанк" ОАО или ЗАО "МТБанк" (Халва), попадают под определенный тип рассрочки. У поставщика услуг может быть несколько типов рассрочки (1 месяц, 3 месяца и т.п.). Каждому из типов рассрочки соответствует номер терминала, заведенный в "Приорбанк" ОАО или ЗАО "МТБанк" (Халва) для поставщика услуг. Указание, какой именно тип рассрочки необходимо использовать для переданного заказа, происходит на стороне поставщика услуг. Предположим, что существует два активных типа рассрочки:

Тип рассрочкиНомер терминала
1 месяц90000001
3 месяца80000003

Для указания в авторизационном запросе используемого типа рассрочки необходимо дополнительно передать параметр wsb_terminal, который должен содержать номер терминала в соответствии с типом рассрочки. Данное значение передается банком-эквайером Магазину при заключении договора. В примере ниже указан запрос для заказа с типом рассрочки 3 месяца.

Данный параметр должен участвовать в формировании подписи заказа. Таким образом, при указании типа рассрочки в авторизационном запросе, изменяется алгоритм расчета подписи заказа. Электронная подпись wsb_signature должна быть сформирована согласно следующему правилу из значений следующих полей:

  • wsb_seed
  • wsb_storeid
  • wsb_order_num
  • wsb_test
  • wsb_currency_id
  • wsb_total
  • wsb_terminal
  • SecretKey

Поля должны быть объединены в одну строку, порядок объединения не должен быть нарушен. Далее, в зависимости от указанной версии протокола (wsb_version), считается MD5 (если версия не указана), либо SHA1 (для версии 2) объединенной строки.

Особенности работы с картами рассрочки "Приорбанк" ОАО

При отправке запроса будет начат сценарий платежа, при котором для оплаты разрешено ввести только карту рассрочки "Приорбанк" ОАО. При работе только с одним типом рассрочки поле wsb_terminal можно не передавать.

Особенности работы с картами рассрочки ЗАО "МТБанк" (Халва)

При отправке запроса будет начат сценарий платежа, при котором для оплаты разрешено ввести только карту рассрочки ЗАО "МТБанк" (Халва либо ИКС карта, к которой привязана карта рассрочки Халва). При работе только с одним типом рассрочки поле wsb_terminal можно не передавать. Система WEBPAY определит вводимую плательщиком карту и на ее основании оплата будет произведена по соответствующему терминалу.

Если у клиента подключена возможность на прием оплат по картам рассрочки ЗАО "МТБанк" (Халва), то отобразиться страница с блоком информации для оплаты.

Платежная страница для оплаты по карте рассрочки Халва

При вводе плательщиком банковской карты, соответствующей продукту ЗАО "МТБанк" ИКС карта, после нажатия кнопки "Оплатить", плательщику будет предложен выбор способа оплаты из привязанных карт к данному продукту.

Выбор способа оплаты для X-карты

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="950f99293b3aa0d26ab11f69af7f4ba5441e42b5">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_terminal" value="80000003">
  <input type="submit" value="Купить">
</form>

Совершение платежей по карте Халва Плюс

Для совершения платежей по карте Халва Плюс достаточно сформировать стандартный авторизационный запрос согласно разделу Формирование заказа для оплаты. При вводе на платежной странице карты Халва Плюс и имеющемся разрешении на оплату накопленными бонусными баллами, покупатель увидит отдельную страницу с выбором типа платежа. На данной странице, он сможет выбрать каким образом произвести оплату заказа.

Выбор способа оплаты при оплате картой Халва Плюс

Если разрешение на оплату накопленными бонусными баллами отсутствует, то страница с выбором способа платежа показана не будет и автоматически произойдет обычная оплата в BYN с карты Халва Плюс.

Платежи Apple Pay

Описание

Технология оплаты Apple Pay — платёжный метод для оплаты товаров и услуг с использованием карт, сохранённых в устройствах Apple. При использовании Apple Pay аутентификация пользователей выполняется с помощью Face ID, Touch ID или пароля, а платежи проводятся с применением токенизированных данных карт.

Преимущества технологии Apple Pay по сравнению с карточными операциями:

  • удобство клиента — все данные карты уже сохранены в устройстве Apple и пользователю достаточно выбрать карту из списка, чтобы начать процесс оплаты;
  • повышенная конверсия — аутентификация платежа проводится по лицу или отпечатку пальца. Пользователю не нужно ожидать и вводить смс-пароль. Тем самым снижается риск ошибок платежа и отказа клиента от оплаты и растет конверсия.

Поддержка Apple Pay на устройствах

Технология оплаты Apple Pay поддерживается на устройствах:

  • iPhone — модели iPhone с функцией Face ID, Touch ID (кроме iPhone 5s);
  • iPad — Модели iPad Pro, iPad Air, iPad и iPad mini с функцией Touch ID или Face ID;
  • Apple Watch — Apple Watch Series 1 и Apple Watch Series 2, а также более поздние модели;
  • Mac — модели компьютеров Mac с Touch ID.

Выполнение платежа

При переходе на платежную страницу пользователь поддерживаемого устройства Apple видит дополнительную кнопку "Оплатить Apple Pay"

Вид платежной страницы

Нажатие на кнопку начинает процесс оплаты с подключенной к устройству картой пользователя. Также сохраняется возможность ввести номер карты для оплаты без использования технологии Apple Pay.

Подключение

Для подключения технологии платежа Apple Pay не требуется дополнительных действий на стороне Магазина. WEBPAY автоматически подключает Apple Pay для все своих клиентов. В случае если на платежной странице Вашего магазина не появляется кнопка Apple Pay это может быть вызвано следующими причинами:

  • банк-эквайер пока не поддерживает платежи Apple Pay;
  • Вам поступают пожертвования;
  • Ваш магазин продает товары или услуги, запрещенные к продаже через Apple Pay (сигареты, оружие, криптовалюты и пр);
  • Ваш магазин замечен в нарушениях условий использования Apple Pay.

Для урегулирования вопроса Вы можете обратиться к Вашему менеджеру. Он подскажет необходимы шаги по активации платежей Apple Pay для Вашего магазина.

Использование промокода для скидочной программы VISA и MASTERCARD

Описание скидочной программы VISA/MASTERCARD

Механизм предназначен для совершения платежей по заказам поставщика услуг, который участвует в скидочной программе платежной системы VISA/MASTERCARD. Данная программа предусматривает предоставление скидки по заказу, если оплата будет совершена с использованием любой карты VISA/MASTERCARD. Также предусмотрена возможность участия в скидочных программах VISA при оплате премиальными типами карт. Плательщик на стороне поставщика услуг выражает свое желание об оплате заказа с использованием одной из премиальных карт. Компания WEBPAY контролирует, чтобы оплата была произведена указанным типом карты.

Описание механизма работы с промокодом VISA и MASTERCARD:

  1. Плательщик на стороне поставщика услуг выражает свое желание об оплате заказа с использованием любой карты платежной системы VISA/MASTERCARD либо премиальной картой VISA. Компания WEBPAY контролирует, чтобы оплата была произведена указанной платежной системой либо указанным типом премиальной карты VISA.
  2. В соответствии с выбранным типом платежной системы поставщик услуг определяет значение скидки и промокода. Сумма скидки передается в поле wsb_discount_price (перейти к разделу Поля для формирования корзины товаров/услуг) и должна учитываться при расчете общей суммы заказа. Так же можно передать текст для описания скидки в поле wsb_discount_name. При работе с JSON API используйте следующий запрос.
  3. Если значение промокода передано и поставщик услуг участвует в скидочной программе VISA или MASTERCARD, то система WEBPAY проверяет карту плательщика на соответствие промокоду. Если найдено расхождение, то происходит запрет на проведение платежа.

Значения возможных промокодов для карт VISA/MASTERCARD, которые передаются в поле wsb_discount_promo_code, указаны в таблице ниже:

Тип картыЗначение промокода
VISAvisa
MASTERCARD (не входят карты MAESTRO и БЕЛКАРТ-MAESTRO)mastercard

Значения возможных промокодов для премиальных карт VISA, которые передаются в поле wsb_discount_promo_code, указаны в таблице ниже:

Тип картыЗначение промокода
VISA Goldgold
VISA Platinumplatinum
VISA Infiniteinfinite

Например, если выбрана оплата по премиальной карте VISA Gold, авторизационный запрос будет выглядеть следующим образом.

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

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_customer_name" value="Иванов Петр Петрович">
  <input type="hidden" name="wsb_customer_address" value="Минск ул. Шафарнянская д.11 оф.54">
  <input type="hidden" name="wsb_service_date" value="Доставка до 1 января 2016 года">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="31.40">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="bc8ea3bee19c247d090c79c8bbb7974f9484db96">
  <input type="hidden" name="wsb_tax" value="10.50">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_order_contract" value="Договор №152/12-1 от 12.01.19">
  <input type="hidden" name="wsb_discount_promo_code" value="gold">
  <input type="submit" value="Купить">
</form>

Тестирование скидочной программы VISA/MASTERCARD

Процесс выполнения тестовых запросов на оплату аналогичен описанному JSON API либо в разделе Формирование заказа для оплаты за некоторым исключением:

  1. Необходимо обратиться в техническую поддержку WEBPAY support@webpay.by для включения для Вашей учетной записи возможности работы по скидочной программе VISA/MASTERCARD.
  2. Для того, чтобы в тестовой среде был доступен ввод разных номеров карт, необходимо параметр wsb_test передать со значением 0.
  3. При тестировании можно указывать любые 16-значные номера карт VISA или MASTERCARD. Создать набор таких карт можно с помощью ресурса http://www.getcreditcardnumbers.com. При генерации номеров премиальных карт используйте следующие первые 6 цифр карты (BIN карты):
Тип картыBIN карты
VISA Gold480066
VISA Platinum417685
VISA Infinite455674

Операции через систему АИС "Расчет" (ЕРИП)

Сценарий выполнения платежей через систему АИС "Расчет" (ЕРИП)

Для совершения платежей с возможностью оплаты через систему АИС "Расчет" (ЕРИП) необходимо сформировать JSON API запрос либо стандартный авторизационный запрос (Формирование заказа для оплаты). Для тестирования необходимо указать адрес https://securesandbox.webpay.by, для совершения реальных платежей — https://payment.webpay.by.

При необходимости создания счета, с возможностью его оплаты до определенной даты, в авторизационном запросе необходимо передать поле wsb_due_date. Значение данного поля должно содержать метку времени в Unix Timestamp, до которой счет будет доступен для оплаты.

После выполнения запроса отобразится страница с реквизитами платежа.

Если клиент подключен на прием оплат по заказам только через систему АИС "Расчет" (ЕРИП), отобразиться страница с блоком информации для оплаты.

Платежная страница при ЕРИП

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

Также можно определить активную вкладку с платежным инструментом (Оплата картой / Оплата ЕРИП). При передаче в POST-запросе поля wsb_tab со значением erip активной вкладкой будет выступать "Оплата ЕРИП".

Платежная страница при ЕРИП и интернет-эквайринге

У плательщика есть возможность сохранить информацию по заказу для совершения платежа позже. Для этого ему необходимо нажать кнопку "Оплатить позже". В результате, на указанный электронный ящик поступит информация о заказе.

Отложенная оплата заказа

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

Если у клиента настроен прием только платежей через систему АИС "Расчет" (ЕРИП).

Уведомление при отложенной оплате ЕРИП

Если у клиента настроена оплата и банковской карточкой онлайн, и через систему АИС "Расчет" (ЕРИП).

Уведомление при отложенной оплате ЕРИП и интернет-эквайринг

Пример кода

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="Название Вашего магазина">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="1">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Товар 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Товар 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="266e9c04a24dfb5fc75775c42a831a49488f8303">
  <input type="hidden" name="wsb_shipping_name" value="Стоимость доставки">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Скидка на товар">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_due_date" value="1586684975">
  <input type="submit" value="Купить">
</form>

Нотификатор об оплате

При оплате платежей через систему АИС "Расчет" (ЕРИП) система WEBPAY извещает Интернет-ресурс о проведенной операции по адресу wsb_notify_url (если он указан в поле формы, либо задан в настройках биллинг-аккаунта). Передаваемые поля аналогичны тем, которые описаны в разделе Стандартный POST-запрос, отправляемый с АПК WEBPAY на wsb_notify_url за некоторым исключением. Так, поле payment_method будет содержать значение erip. Интернет-ресурс, в случае оповещения, должен ответить кодом 200 ("HTTP/1.0 200 OK"). Через 30 дней, если Интернет-ресурс так и не смог принять уведомление, отсылка запросов прекращается.

Выставление счета в системе АИС "Расчет" (ЕРИП) через FTP

Формат загружаемого файла на FTP-сервер (файл *.bill):

  1. Id биллинг-аккаунта;
  2. Номер счета;
  3. Сумма;
  4. Наименование товара/услуги;
  5. Срок действия счета (dd.MM.yyyy HH:mm:ss);
  6. Пеня — необязательное поле;
  7. ФИО — необязательное;

Название файла: id биллинг-аккаунта_дата+время.bill.

Пример: 1234567_250817125700.bill

Пример загружаемого файла:

123456789;789-Test;123.56;Товар 1;01.12.2017 16:51:29;1.86;Иванов Иван

123456789;789-Test;123.56;Товар 1;01.12.2017 16:51:29;; — пример файла, когда есть незаполненные необязательные поля.

После выставления счета на электронный адрес Магазина приходит уведомление о выставлении счета:

  1. Успешное выставление счетаУведомление об успешном выставлении счета
  2. ОшибочноеУведомление об ошибочном выставлении счетаУведомление о не уникальном файле

Настройка FTP

Параметры FTP WEBPAY:

User name: merchant

Host name (Port) для тестовой среды: erip-ftp-test.webpay.by (порт 2100)

Host name (Port) для реальной среды: erip-ftp.webpay.by (порт 21)

Password (одинаковый вне зависимости от используемой среды): YJmsJs4TpveX

Пример заполнения параметров в Total Commander:

Пример настроек FTP

Оплата счетов на произвольную сумму

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

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

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

API для создания счетов в системе WEBPAY без перехода на платежную страницу

Описание механизма создания заказа

Для реализации данного механизма необходимо предварительно обратиться в техническую поддержку WEBPAY по адресу support@webpay.by для подключения данного функционала.

Сервис используется, чтобы создавать счета в системе WEBPAY через API. Запрос направляется методом POST на URL адрес для тестового создания счета — https://sand-box.webpay.by/woc/order и на URL адрес для реального — https://api.webpay.by/woc/order. Каждый запрос необходимо подписывать по алгоритму Hmac. Описание данного алгоритма представлено далее.

Описание параметров запроса и его пример

Название поляТип данныхОбязательноОписание поляКодировки и прочее
resourceIdStringДаИдентификатор Магазина в системе WEBPAY
resourceOrderNumberStringДаУникальный номер заказа, присваиваемый Магазином
validThroughDateНетДата, до которой можно оплатить заказ
shortDescriptionStringНетКраткое описание товара
creationTimeDateНетДата создания заказа Магазином
longDescriptionStringНетПодробное описание товара
languageCodeStringНетКод языка согласно ISO 639-1
itemsArrayДаМассив позиций заказамножественный
itemComplexTypeДаПозиция заказаitems/
nameStringДаНаименование товараitems/item/
quantityIntegerДаКоличество товараitems/item/
priceComplexTypeДаСтоимость одной позицииitems/item/
amountBigDecimalДаСтоимость одной позицииitems/item/price/
currencyStringДаВалюта позиции согласно ISO 4217items/item/price/
urlsMapДаМассив адресовмножественный
nameEnumДаВозможные значения:
resourceReturnUrl — URL для редиректа в случае успешной авторизации;
resourceCancelUrl — URL для редиректа в случае не успешной авторизации;
resourceNotifyUrl — URL для отправки нотификатора (paymentStatus).
urls/
urlStringДаURL, соответствующий вышеуказанному типу ('name')urls/
customerComplexTypeНетНаименование получателя товара/услуги
resourceCustomerIdStringДаИдентификатор получателя товара/услугиcustomer/
nameStringНетИмя получателя товара/услугиcustomer/
surnameStringНетФамилия получателя товара/услугиcustomer/
emailStringНетEmail получателя товара/услугиcustomer/
phoneStringНетТелефон получателя товара/услугиcustomer/
discountsArrayНетМассив позиций скидок заказамножественный
discountComplexTypeДаСкидка заказаdiscount/
nameStringДаНаименование скидкиdiscount/
promoCodeStringНетПромокодdiscount/
typeStringНетТип скидкиdiscount/
valueComplexTypeДаОписание стоимости скидкиdiscount/
amountBigDecimalДаСтоимость скидкиdiscount/value/
currencyStringДаВалюта позиции согласно ISO 4217discount/value/
shippingsArrayНетМассив позиций доставокмножественный
shippingComplexTypeДаДоставкаshipping/
nameStringДаНаименование доставкиshipping/
valueComplexTypeДаОписание стоимости доставкиshipping/
amountBigDecimalДаСтоимость доставкиshipping/value/
currencyStringДаВалюта позиции согласно ISO 4217shipping/value/

Для примера рассмотрим запрос, который формируется в формате JSON.

Пример запроса

{"resourceId":479447789,
"resourceOrderNumber":"455444556222",
"validThrough":"2017-09-25T00:01:00+03:00",
"shortDescription":"Test payment",
"creationTime":"2017-09-20T09:00:00+03:00",
"longDescription":"This is a test payment",
"languageCode":"ru",
"customer":{
"resourceCustomerId":"test33332",
"phone":"375331231231",
"email":"test@test.by",
"name":"tttttt",
"surname":"qqqqqqq"},
"items":[{
"idx":1,
"name":"Товар 1 UTF-8 1",
"quantity":"1",
"price":{
"currency":"BYN",
"amount":130.10}},
{"idx":2,
"name":"Product 2",
"quantity":1,
"price":{
"currency":"BYN",
"amount":40.10}}],
"total":{
"currency":"BYN",
"amount":170.20},
"discounts":[{
"name":"discount",
"promoCode":"promo code",
"type":"type",
"value":{
"amount":10.10,
"currency":"BYN"}}],
"shippings":[{
"name":"shipping",
"value":{
"amount":10.10,
"currency":"BYN"}}],
"urls":{
"resourceReturnUrl":"http://localhost:8080/return11111",
"resourceCancelUrl":"http://localhost:8080/cancel22222",
"resourceNotifyUrl":"http://192.168.44.11:8080/webpay/shop"}}

Описание параметров ответа

НазваниеТипОбязательныйОписание
resourceIdStringДаИдентификатор Магазина в системе WEBPAY
resourceOrderNumberStringДаНомер заказа в системе Магазина
webpayInvoiceIdIntegerНетID заказа в системе WEBPAY
webpayInvoiceNumberStringНетУникальный номер заказа в системе WEBPAY
invoiceURLStringНетURL адрес счета

Ответ системы WEBPAY при успешном создании заказа.

Пример ответа

{"resourceId":479447789,
"resourceOrderNumber":"455444556222",
"webpayInvoiceId":77714,
"webpayInvoiceNumber":"735542997",
"webpayOrderId":9736,
"webpayOrderNumber":null,
"shortOrderNumber":"455444556222",
"invoiceUrl":"https://sandbox.webpay.by/?"}

Ответ системы WEBPAY при ошибке, например:

Пример ответа

{"errorCode":"BAD_REQUEST",
"errorMessage":"resourceOrderNumber: The field must be unique"}

Механизм формирования Hmac подписи

Для выполнения запроса на создание счета необходимо добавить подпись в запрос по алгоритму Hmac. Подпись формируется следующим образом — к запросу добавляется http заголовок Authorization, который имеет следующий вид:

Authorization: HmacSHA512 <apiKey>:<nonce>:<digest>

Где:

  • HmacSHA512 — алгоритм подписи,
  • apiKey — идентификационный номер ресурса Магазина,
  • nonce — случайно сгенерированная строка,
  • digest — Hmac подпись.

В подписи используются следующие поля http запроса:

  • METHOD\n
  • RESOURCE\n
  • QUERY_STRING\n
  • CONTENT_TYPE\n
  • APIKEY\n
  • NONCE\n
  • PAYLOAD\n
Описание полей
Название поляОбязательное полеОписание поля
METHODДаМетод запроса (POST)
RESOURCEДаРесурс, на который выполняется запрос. Например, в https://sand-box.webpay.by/woc/order строка для подписи будет /woc/order
QUERYSTRINGНетПараметры запроса. Например, в https://sand-box.webpay.by/woc/order?id=11 строка для подписи будет id=11
CONTENT_TYPEДаHttp заголовок Content-type
APIKEYДаИдентификационный номер ресурса Магазина
NONCEДаСлучайно сгенерированная строка. Должна быть уникальна для каждого счета
PAYLOADДаТело запроса

Пример кода

<?php
$jsonString =
'{"resourceId":349204746,
"resourceOrderNumber":"ORDER-16",
"validThrough":"2020-06-10T20:16:35+03:00",
"creationTime":"2020-04-13T05:16:09+03:00",
"languageCode":"ru",
"customer":{
"resourceCustomerId":"1",
"phone":null,
"email":"test@test.by"
},"items":[{
"idx":0,
"name":"TEST!",
"quantity":1,
"price":{"currency":"BYN","amount":100.00}}],
"total":{"currency":"BYN","amount":105.00},
"urls":{
"resourceReturnUrl":"https:\/\/test.by",
"resourceCancelUrl":"https:\/\/test.by",
"resourceNotifyUrl":"https:\/\/test.by"},
"shippings":[{"name":"shipping","value":{"amount":5,"currency":"BYN"}}]}';

$nonce = 'Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN';
$storeid = '349204746';
$secret = '123456';

$stringToSign = "POST\n/woc/order\napplication/json;charset=utf-8\n$storeid\n$nonce\n$jsonString\n";

$digest = hash_hmac('sha512', $stringToSign, $secret, true);
$hmacString = 'HmacSHA512 '.$storeid.':'.$nonce.':'.base64_encode($digest);
//$hmacString
/*
HmacSHA512 349204746:Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN:/Ef0ipKEy2+ZW6cjtOWKr51o0stKbfWxnsRjLxGgT9s+ua6gklzj2BGLdp4/hTXxEZudpVfdcwyAB/I+eA2jfA==
*/
$headers = array(
  "Authorization: $hmacString",
  "Content-type: application/json;charset=utf-8"
);

$url = 'https://sand-box.webpay.by/woc/order';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonString);
$content = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
print "$content\n";?>

Работа без интеграции

В системе WEBPAY предусмотрена работа без осуществления интеграции с сайтом Магазина. Принимать оплату возможно, создавая счета из личного кабинета WEBPAY.

Создание счета из личного кабинета WEBPAY при работе через интернет-эквайринг и/или систему АИС "Расчет" (ЕРИП)

Формирование нового счета для оплаты

Для создания нового счета необходимо перейти в раздел меню "Счета" и нажать кнопку "Новый счет".

Также в меню "Счета" отображаются все Ваши счета и присутствует окно поиска по различным критериям: статусу, дате создания, имени счета, имени счета мерчанта, ID счета и ID аккаунта.

После нажатия на кнопку "Новый счет" перед Вами отобразится форма со специальными полями, которые необходимо заполнить. Поле "Счет для покупателя" является обязательным для заполнения. В поле "Счет для покупателя" можно создавать нового клиента, выбрав "НОВЫЙ ПОКУПАТЕЛЬ" либо выбрать ранее созданного покупателя.

Далее заполняется поле "Имя" — вводится имя клиента, для которого будет выставлен счет. Максимальная длина поля составляет 128 символов, минимальная — 1 символ. Формат ввода символов любой. Данное поле является обязательным для заполнения.

Важно!

Обращаем Ваше внимание, что поля, отмеченные *, являются обязательными для заполнения. Поля, не отмеченные *, заполнять не обязательно.

Формирование нового счета

Поле "Фамилия" также является обязательным для заполнения. Вводится фамилия клиента, для которого будет выставлен счет. Максимальная длина поля 128 символов, минимальная 1 символ. Формат ввода символов любой.

Электронный адрес, на который будет выслан новый счет для оплаты, вводится в поле "Email". Поле является обязательным для заполнения. Максимальная длина поля 128 символов, минимальная 4 символа. При вводе можно использовать: латинские буквы, цифры, символ "-" и "_" и только маленькие символы.

Поле "Имя счета" обязательно для заполнения. Является уникальный идентификатором заказа. Максимальная длина поля 32 символа, минимальная 1 символ. Формат ввода символов любой.

Важно!

Обращаем Ваше внимание, что для оплаты заказа в АИС "Расчет" (ЕРИП) будет использоваться номер, введенный в поле "Имя счета". Значение данного поля НЕ должно начинаться с "0" (нуля). Создание нескольких заказов с одним и тем же номером ЗАПРЕЩЕНО.

Поле "Валюта счета" является обязательным для заполнения. Обозначает валюту, в которой будет произведен расчет. На данный момент поддерживаются четыре валюты для оплаты:

  • белорусские рубли (BYN),
  • евро (EUR),
  • доллары США (USD),
  • российские рубли (RUB).

Далее заполняется обязательное поле "Язык". На этом этапе осуществляется выбор языка формы оплаты выставляемого счета. На данный момент поддерживаются два языка формы оплаты:

  • русский (Russian),
  • английский (English).
Создание нового счета

Дата, до которой необходимо оплатить счет, выбирается в поле "Оплатить до". Это поле является обязательным для заполнения. Для выбора даты нужно нажать на значок часов, который расположен в левой части поля. В открывшемся календаре Вы можете выбрать день, месяц и год. Дату и время оплаты также можно ввести с клавиатуры в полях "Выбрать дату" и "Выбрать время". Здесь используются форматы "гггг-мм-дд" и "чч:мм:cc" соответственно. Если в процессе заполнения формы выставляемого счета Вы передумали с датой, до которой необходимо оплатить счет, Вы можете нажать повторно на значок часов и изменить дату оплаты счета.

Далее Вам необходимо добавить в счет информацию по товарам/услугам, за которые будет производиться оплата. Наименование товара/услуги заполняется в поле "Имя продукта". Поле является обязательным для заполнения. Максимальная длина поля составляет 128 символов. Формат ввода любой.

Поле "Код продукта" заполнять не обязательно. Сюда вводится идентификатор продукта в магазине. Максимальная длина поля составляет 32 символа, минимальная — 1 символ. При вводе можно использовать латинские буквы, цифры, символы "-" и "_".

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

Далее заполняется поле "Цена". Полная цена продукта без учета стоимости доставки и скидки. Максимальная длина поля не ограничена. Поле является обязательным для заполнения.

Количество товаров/услуг прописывается в поле "Количество". Максимальная длина поля не ограничена. Поле является обязательным для заполнения.

Важно!

В поле "Количество" можно вводить только целое число.

Таким же образом Вы можете добавить в счет несколько товаров/услуг, нажав на кнопку "Добавить поле". Также Вы можете удалить товар/услугу со счета, нажав на красный значок "—" справа от позиции товара.

Далее идут поля, которые не обязательны для заполнения.

Стоимость доставки товара/услуги прописывается в поле "Стоимость доставки". Максимальная длина поля не ограничена.

Скидка на товар/услугу вводится в поле "Скидка". Максимальная длина поля не ограничена.

Важно!

Обращаем Ваше внимание, что скидка вводится без знака "-" (минус). Система автоматически вычтет скидку из цены заказа. Конечная стоимость товара/услуги с учетом скидки и доставки не должна быть больше лимита, который был установлен в договоре Интернет-эквайринга.

Если вместе с выставляемым счетом Вы желаете передать плательщику информационное сообщение, то вписать его Вы можете в поле "Примечание". Максимальная длина поля не ограничена.

Заполненный счет на оплату

После нажатия кнопки "Сохранить" отобразится только что созданный Вами счет первым в списке.

Если нажать на карточку счета, она раскроется, и Вы сможете увидеть детализацию по выставленному счету. В случае необходимости внести изменения в уже сформированный счет, Вы можете использовать кнопку "Изменить счет".

При нажатии на кнопку "Копировать URL счета" ссылка на счет будет автоматически скопирована в буфер обмена. URL адрес позволяет открыть счет в новой вкладке браузера и произвести оплату. Данную ссылку Вы можете использовать для отправки плательщику любым удобным способом (SMS, email, мессенджеры).

Кнопка "QR код" позволяет открыть код для перехода на счет. Код содержит под собой тот же URL адрес счета, который может быть распознан любым мобильным устройством с возможностью чтения QR кодов. Эта функция может, например, применяться при продаже товаров в обычных магазинах.

Сохраненный счет на оплату

Подробную информацию о клиенте, которому был выставлен счет, и товарам/услугам счета Вы можете просмотреть, нажав на кнопку "Посмотреть счет". Здесь же находится кнопка "Оплатить Счет".

Просмотр выставленного счета

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

Образец письма-уведомления по новому счету

Образец письма-уведомления для оплаты через АИС "Расчет" (ЕРИП).

Образец письма-уведомления по новому счету ЕРИП

Оплата заказа

В том случае, если клиент проследует по ссылке — он попадет на форму оплаты.

Информация о заказе

После нажатия кнопки "Оплатить счет" покупатель перейдет на страницу оплаты системы WEBPAY:

  • если у Вас подключен интернет-эквайринг;Платежная страница при интернет-эквайринге
  • если у Вас подключен прием оплаты через АИС "Расчет" (ЕРИП);Платежная страница при ЕРИП
  • если у Вас на одном биллинг-аккаунте подключена возможность оплаты банковской картой онлайн и оплаты через АИС "Расчет" (ЕРИП).Платежная страница при интернет-эквайринге и ЕРИП

Создание счета по картам рассрочки

Реализована возможность выставления счетов через личный кабинет по картам рассрочки Халва (ЗАО "МТБанк") и картам рассрочки "Приорбанк" ОАО. Если плательщик сообщил интернет-магазину, что оплата будет проходить по карте рассрочки, то рекомендуется при оплате выбрать требуемый для текущего заказа срок рассрочки. В случае, если у интернет-магазина один терминал рассрочки и при выставлении счета не выбран способ оплаты картой рассрочки, а плательщик введет карту Халва, то оплата пройдет по терминалу Халвы. В случае, если у интернет-магазина два и более терминалов рассрочки и при выставлении счета интернет-магазин не выберет нужный терминал, а плательщик введет карту рассрочки Халва, то платеж будет отклонен.

Создание счета с использованием рассрочки

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

Информация по рассрочке после оплаты

Платежи по QR-коду

При заключении договора интернет-эквайринга с ОАО "Банк БелВЭБ" предоставляется возможность приема платежей с использованием QR-кода. Такой способ не требует интеграции с сайтом и может быть использован как для платежей онлайн, так и оффлайн.

Для начала приема оплат по QR-коду следует зайти в личный кабинет WEBPAY, раздел "QR-код" (включается индивидуально для учетной записи):

Раздел QR коды

QR-код является фиксированным и индивидуальным для конкретного юридического лица или индивидуального предпринимателя и дает возможность выставить и оплатить неограниченное количество счетов.

Для удобства работы с QR-кодом можно использовать кнопки "Скачать" и "Печать". Также присутствует примечание "Чтобы скопировать QR-код в буфер обмена нажмите правой клавишей мыши на изображении → "Копировать картинку".

Сканирование QR-кода ведет на платежную форму, которая размещается на адресу https://sales.webpay.by - для реальной среды или https://salessandbox.webpay.by для тестовой.

Пример формы:

Пример формы для оплаты по QR-коду

На форме выставления счета для плательщиков отображаются:

  • Наименование компании.
  • Адрес компании, контактный телефон и email.
  • Поле "Сумма" с возможностью внести сумму оплаты.
  • Поле "Валюта" с выпадающим списком доступных для компании валют.
  • Поле "Наименование товара/услуги" с возможностью ввода информации об оплачиваемом заказе.
  • Поле "Email" для ввода адреса электронной почты для отправки карт-чека об оплате.

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

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

Отчет по оплатам, осуществленным по QR-коду

Мерчанты PCI DSS

Для осуществления интеграции с системой WEBPAY мерчантов PCI DSS, которые работают с данными карт на страницах веб-сайта или непосредственно в приложении и хотят использовать интеграцию Host2Host, следуйте, пожалуйста, инструкциям ниже. Формирование стандартного POST-запроса (раздел Формирование заказа для оплаты) + поле wsb_encrypted_data. Также обратите внимание, что при данном способе работы поле wsb_email является обязательным при отправке запроса.

Название поляОбязательное полеОписание
wsb_encrypted_dataДаДанное поле содержит зашифрованный JSON формата {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}. Шифруется по алгоритму RSA с помощью публичного ключа из личного кабинета.

Важно!

При формировании поля wsb_signature (механизм формирования подписи указан в разделе Электронная подпись заказа) поле wsb_encrypted_data также участвует, при склеивании параметров и ставится в конец перед секретным ключом из настроек биллинга. Далее происходит стандартный сценарий оплаты. Отличие заключается только в формате ответа. Ответ будет дан в формате JSON.

Поля ответа

Название поляОписание
timeВремя выполнения запроса
orderNumberНомер заказа
invoiceNumberНомер счета
transactionId транзакции
authorizationCodeАвторизационный код
RrnУникальный идентификатор банковской транзакции
trimPanНомер карты в формате 123456xxxxxx1234
payeeПолучатель платежа
amountСумма платежа
currencyВалюта платежа
acsUrlАдрес перехода для прохождения 3D-Secure
PaReqПараметр передаваемый на acs страницу
TermUrlАдрес для получения ответа от acs страницы
MDТокен для восстановления сессии после acs-страницы
tokenNameНазвание токена для восстановления платежной сессии
tokenЗначение токена для восстановления платежной сессии
availableOptionПараметр содержит возможные значения для поля paymentType. Список значений зависит от типа карты и настроек мерчанта. Возможные значения:
IpsPayment — терминал ips (дефолтный либо, при включенной маршрутизации, смаршрутизированный терминал)
halva — терминал халвы
standard — терминал халвы+ (оплата рублями)
bonus — терминал халвы+ (оплата бонусами)
paymentTypeИспользуется при необходимости выбрать вариант оплаты для карт. Приходит пустое значение, его необходимо заполнить. Возможные значения для заполнения берутся из поля availableOption.
responseCodeПри возникновении ошибки содержит код ошибки
responseTextСодержит текст ошибки

При выборе варианта оплаты для карточки Халва+

WEBPAY в ответе возвращает

Пример ответа

{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a303458
79566e334b48526e592c","tokenName":"wt","availableOption":"ipsPayment,halva","paymentType":""}

Мерчант при получении такого ответа должен запросить у клиента вариант оплаты и отправить нам POST-запрос со следующими полями:

Пример запроса

$params['wt'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5
a30345879566e334b48526e592c";
$params['payHalvaPlus'] = 1;
$params['paymentType'] = 'standard'; /* может содержать значения из доступных, полученных в параметре availableOption */

При сценарии с 3DS

WEBPAY в ответе возвращает заполненные поля acsUrl, PaReq, TermUrl, MD

Пример ответа

{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345
879566e334b48526e592c",
"tokenName": "wt",
"acsUrl": "https://aacsw.3ds.verifiedbyvisa.com",
"PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC
WR89fiTGzObs",
"TermUrl": "https://payment.webpay.by:443",
"MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"}

Мерчант отправляет POST-запрос на URL, который пришел в поле acsUrl с параметрами PaReq, MD и TermUrl.

Важно!

Поле TermUrl предварительно замените на свой URL, где будет обрабатываться ответ от acs. Когда на Ваш URL для обработки ответа от acs придёт ответ, Вам необходимо отправить POST-запрос WEBPAY с параметрами, которые пришли от acs (в ответе от acs приходит поле PaRes и MD-токен, по которому мы восстановим платежную сессию).

Пример запроса

$params['PaRes'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c
4d5a30345879566e334b48526e592c";
$params['MD'] = "d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b3555865694b5766726d62";

WEBPAY получает запрос, обрабатывает, отправляет в процессинг и возвращает мерчанту ответ

Пример ответа

{"token":"ffc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39",
"tokenName":"wt",
"time":"2019.09.13 10:18:14",
"orderNumber":"test-1568359081",
"invoiceNumber":"138143506",
"transaction":"760583316",
"authorizationCode":"269412",
"rrn":"269412973762",
"trimPan":"417753xxxxxx1234",
"amount":"6,00",
"currency":"BYN",
"payee":"Test",
"acsUrl":"",
"PaReq":"",
"TermUrl":"",
"MD":"",
"responseCode":"",
"responseText":""}

Платежные модули выплат

Данное руководство описывает процесс разработки платежных модулей выплат с помощью системы WEBPAY для Интернет-ресурсов, подключенных к интернет-эквайрингу. Функционал доступен при работе через банк-эквайер ОАО "БелВЭБ".

B2C/W2C

Общее описание

Для ввода и вывода денежных средств на Вашем сайте допускается использование плательщиком карт платежных систем MASTERCARD, VISA, БЕЛКАРТ, эмитированных любым белорусским банком. Иностранные карты недоступны для выплат согласно правилам платежных систем.

Схема работы

Первое пополнение аккаунта привязка карты (присвоение токена)

  1. Плательщик инициирует пополнение аккаунта.
  2. Интернет-ресурс формирует авторизационный POST-запрос и перенаправляет плательщика на платежную страницу WEBPAY, где плательщик вводит данные своей карточки (Формирование заказа для оплаты).
  3. После заполнения необходимых данных плательщиком, система WEBPAY направляет запрос в банк-эквайер на проведение транзакции и получает ответ о результатах прохождения.
  4. После получения ответа от банка-эквайера, система WEBPAY отправляет Интернет-ресурсу нотификатор, содержащий информацию об успешном/ошибочном проведении транзакции. В случае успешной операции в нотификаторе будет содержаться токен карты (привязка осуществляется по wsb_customer_id) и карта в формате 4***********1234.
  5. Интернет-ресурс отображает в личном кабинете плательщика карту в формате 4***********1234 (при необходимости).
  6. На своей стороне Интернет-ресурс в обязательном порядке собирает информацию о плательщике (ФИО и адрес).

Последующие пополнения аккаунтов

  1. При необходимости осуществления нового пополнения тем же плательщиком, Интернет-ресурс направляет в систему WEBPAY новый POST-запрос с указанием wsb_customer_id.
  2. Система WEBPAY восстанавливает номер карты плательщика, имя держателя карты и срок действия. Плательщику остается ввести лишь CVV/CVC код. Также при каждом пополнении плательщик проходит проверку 3D-Secure.

Вывод денежных средств с аккаунта плательщика

  1. Плательщик в личном кабинете Интернет-ресурса инициирует вывод денежных средств путем выбора из списка карт (список отображает карты плательщика в формате 4***********1234, с которых он ранее осуществлял пополнение аккаунта), на которую необходимо осуществить вывод.
  2. Плательщик указывает сумму, на которую он хочет осуществить вывод денежных средств.
  3. Интернет-ресурс отправляет запрос в систему WEBPAY, в котором указывает токен карты (любой операции, прошедшей для данного wsb_customer_id), на который необходимо осуществить вывод денежных средств, также Интернет-ресурс передает информацию о плательщике (ФИО и адрес. Описание полей представлены в таблице Описание полей для операций типа B2C) при работе с операциями типа B2C либо если осуществляется работа с операциями типа W2C, то передает информацию о получателе и отправителе (Описание полей для операций типа W2C).
  4. Система WEBPAY по полученным данным восстанавливает карту плательщика и делает запрос на вывод в банк-эквайер. Плательщик проходит проверку 3D-Secure.
  5. От банка-эквайера система WEBPAY получает результат обработки запроса.
  6. После получения результата от банка-эквайера, система WEBPAY направляет Интернет-ресурсу нотификатор, содержащий результат проведения операции вывода денежных средств.

Разработка платежного модуля

Тип операцииРаздел
Пополнение, привязка карты и последующее пополнениеФормирование заказа для оплаты ,
Упрощенный платеж
Вывод денежных средствService WSBApi (запрос TransactionB2C - для операций типа B2C либо TransactionW2C - для операций типа W2C). Перед применением необходимо сообщить IP адрес, с которого будет осуществляться запрос

Первое пополнение, привязка карты и последующее пополнение

В систему WEBPAY следует направлять авторизационный POST-запрос согласно Формированию заказа для оплаты и Упрощенному платежу. Токен карты передается в поле transaction_id.

Вывод денежных средств

Для тестирования B2C/W2C следует использовать URL https://sandbox.webpay.by/WSBApi2 и запрос TransactionB2C/TransactionW2C (Service WSBApi).

Поле addInfo для операций B2C — это json строка, состоящая из значений представленных в таблице.

Поле addInfo для операций W2C — это json строка, состоящая из двух объектов senderData и receiverData, значения которых представлены в таблицах.

Описание полей таблицы для операций типа B2C

TagTypeDescriptionValue Format
C1TFirst Nameans ...35
C2TMiddle Nameans 1
C3TLast Nameans ...35
C4TStreet Addressans ...50
C5TCityans ...25
C6TState/Province Codeans ...3
C7TCountryans 3
C8TPostal Codeans ...10

ans — alphabetic, numeric and special characters

Пример кода

<TransactionB2C xmlns= "https://billing.webpay.by/WPPAPI-V0.2/">
  <parameters>
    <store_id>182612154</store_id>
    <login>test_bveb</login>
    <password>25f9e794323b453885f5181f1b624d0b</password>
    <transaction_id>805373075</transaction_id>
    <amount>22</amount>
    <currency>BYN</currency>
    <addInfo>{"C1":"LNAMES","C2":"V","C3":"LNAMES","CC":"00", "C4":"av. POBEDITELEY101","C5":"MINSK","C7":"112","C8":"220019"}</addInfo>
  </parameters>
</TransactionB2C>

Описание полей таблицы для операций типа W2C

Описание полей таблицы senderData
TagTypeDescriptionValue Format
C1TFirst Nameans ...35
C3TLast Nameans ...35
C4TStreet Addressans ...50
C5TCityans ...25
C6TState/Province Codeans ...3
C7TCountryans 3

ans — alphabetic, numeric and special characters

Описание полей таблицы receiverData
TagTypeDescriptionValue Format
C1TFirst Nameans ...35
C3TLast Nameans ...35

ans — alphabetic, numeric and special characters

Пример кода

<TransactionW2C xmlns= "https://billing.webpay.by/WPPAPI-V0.2/">
  <parameters>
    <store_id>182612154</store_id>
    <login>test_bveb</login>
    <password>25f9e794323b453885f5181f1b624d0b</password>
    <transaction_id>805373075</transaction_id>
    <amount>22</amount>
    <currency>BYN</currency>
    <addInfo>{"senderData":{"C1":"Company Name","C3":"IVANOV","C4":"st. Shafarnyanskaya, 11, of. 54","C5":"MINSK","C6":"BY","C7":"112"},"receiverData":{"C1":"IVAN","C3":"IVANOV"}}</addInfo>
  </parameters>
</TransactionW2C>

Для тестирования следует использовать тестовую карту, данные которой можно получить обратившись в support@webpay.by

После получения ответа от системы WEBPAY, следует запросить статус через метод get_transaction (раздел Проверка платежа).

Если по одному transaction_id будет создано несколько выплат, то можно использовать запрос GetTransactionStatus (Service WSBApi).

В данном примере необходимо заменить только значения в полях: store_id, login, password, transaction_id.

Пример кода

$wsdl_url = 'https://sandbox.webpay.by/WSBApi2';
try {
  $soap_client = new SoapClient($wsdl_url, $defaultOptions);
} catch (SoapFault $e) {
  print $e->getMessage();
}
$params = array(
  'store_id'=> 'store_id',
  'login'=> 'login',
  'password'=>'password',
  'transaction_id'=> 'transaction_id',
  'order_num'=> 'order_num'
);
try {
  $r = $soap_client->GetTransactionStatus($params);
  print_r($soap_client);
  print_r($r);
} catch (SoapFault $exception) {
  print_r($soap_client);
  echo $exception;
}

P2P

Общее описание

Для вывода денежных средств на Вашем сайте допускается использование плательщиком карт платежных систем MASTERCARD, VISA, БЕЛКАРТ, эмитированных любым белорусским банком. Типы карт, на которые может осуществляться вывод денежных средств, определяется банком-эквайером. Иностранные карты недоступны для выплат согласно правилам платежных систем.

Вывод денежных средств осуществляется с корпоративной карточки Вашей организации.

Разработка платежного модуля

Для осуществления вывода денежных средств способом P2P, следуйте, пожалуйста, инструкциям ниже. Формирование стандартного POST-запроса (раздел Формирование заказа для оплаты) + поле wsb_encrypted_data + поле wsb_output_via_corpocard. Также обратите внимание, что при данном способе работы поле wsb_email является обязательным при отправке запроса.

Название поляОбязательное полеОписание
wsb_encrypted_dataДаДанное поле содержит зашифрованный JSON формата {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}. Шифруется по алгоритму RSA с помощью публичного ключа из личного кабинета.
wsb_output_via_corpocardНет

Возможные значения: true, false

По умолчанию установлено значение false

true – используется для ввода денежных средств, false – используется для вывода денежных средств

Важно!

При формировании поля wsb_signature (механизм формирования подписи указан в разделе Электронная подпись заказа) поле wsb_encrypted_data также участвует, при склеивании параметров и ставится в конец перед секретным ключом из настроек биллинга. Далее происходит стандартный сценарий оплаты. Отличие заключается только в формате ответа. Ответ будет дан в формате JSON.

Пример запроса

{
  "wsb_output_via_corpocard" : true,
  "wsb_encrypted_data": "bhch48Wu4Esi3Y7jVq/d+0A3VqdzBsRvobhDxLrWsQyl6+ogVSIxMxM8S/4EVyGeNXO6VR/FA1UnvzLvehhDWMeEZFv04SAktt5BTABXcjgWm7ZJ3tiXEv1c1UuMDCk88xhDDyfSaPaCJMxnQhA3Wo9qfXhFebDwtIUljP7MCs41woxAQx8v9f8fm3FHS2+RnrN+HRAhgM34hR3OwYx/1llgu0L78++Ovrf6ZjQqYArv8YoV8E9y5cWrGYdUp2ogmfOkvGX/wI+wZ0FoAIuwAWiUknca7zClbwfgshw4wV4p0w==",
  "wsb_storeid": "240869199",
  "wsb_order_num": "ORDER-1234567822223",
  "wsb_currency_id": "BYN",
  "wsb_version": 2,
  "wsb_seed": "dfdasf3i232m13ijdsmcvm",
  "wsb_test": 0,
  "wsb_invoice_item_name": ["Товар 1"],
  "wsb_invoice_item_quantity": [1],
  "wsb_invoice_item_price": [1],
  "wsb_total": 1,
  "wsb_signature": "b54331d410a45e731e24544701a1f692ac9983b8"
}

Поля ответа
Название поляОписание
wtТокен платежной сессии
redirectUrlURL адрес для перенаправления плательщика для ввода номера карты, на которую будет осуществлен вывод денежных средств

Пример ответа

{
  "data": {
    "wt": "93ad3cf9e599a8ecaf6bd8202dbaa5cd=6432397a5132524556574d7a6558647a5a6a51304b324a3053326b794f444a70616c5244636b30305a4656535a6a4a466357644f54546870616b5243c497a526d6c484d6d7435636b687657555a5457512c2c",
    "redirectUrl": "https://securesandbox.webpay.by?wt=93ad3cf9e599a8ecaf6bd8202dbaa5cd=643239756574d7a6558647a5a6a51304b324a3053326b794f444a70616c5244636b30305a4656535a6a4a466357644f54546870616b524352325673616c497a526d6c484d6d7435636b687657555a5457512c2c"
  }
}

После получения ответа от системы WEBPAY Вам следует перенаправить плательщика по адресу redirectUrl. Плательщик попадает на платежную страницу WEBPAY для ввода номера карты, на которую будет осуществлен вывод денежных средств с Вашей корпоративной карты.

API

Управление операциями

SDK и описание API для управления карточными операциями доступно по ссылке https://github.com/WebpayDev/wsb-api-sdk

Для самостоятельной настройки управлением операциями можно воспользоваться документацией Service WSBApi либо ознакомиться со схемами wsdl https://sandbox.webpay.by/WSBApi2.

Важно!

Предварительно необходимо направить запрос в службу поддержки компании WEBPAY на support@webpay.by, указав IP адрес, с которого будут производиться запросы.

Важно!

В случае если по каким-либо причинам не был получен ответ от системы WEBPAY рекомендуем повторять отправку запроса с увеличивающейся периодичностью до 1 часа. Если система WEBPAY так и не отдала ответ, то отмечать такие операции и направлять их на support@webpay.by.

Серверное SDK

Серверное SDK — библиотека на языке PHP для запросов на платежную страницу WEBPAY, с помощью которой нет необходимости формировать самостоятельно HTML форму. Серверное SDK размещено по адресу https://github.com/WebpayDev/payment-json-sdk.

Пример запроса размещен здесь: https://github.com/WebpayDev/payment-json-sdk/blob/master/examples/simple_request.php.

Запросы для получения отчетности

В системе WEBPAY предусмотрено получение отчетов по API из личного кабинета реальной среды https://merchant.webpay.by двумя способами:

  1. GET-методом
  2. POST-методом.
При GET-методе URL адрес формируется по следующей схеме:

url_платежного_модуля/reports/merchants/{reportType}?email=значение_параметра_email&reportFormat=значение_параметра_reportFormat&startDate=значение_параметра_startDate&endDate=значение_параметра_endDate

Заголовок Authorization: login:password

При POST-методе запрос осуществляется на следующий URL адрес:

url_платежного_модуля/reports/get

Важно!

ОГРАНИЧЕНИЕ: диапазон дат не более 3 месяцев либо файл объемом не более 100000 записей.

Пример кода

private String email;
private Integer login;
private String password (md5);
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date startDate;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date endDate;


// Запрос, отправляемый POST-методом
{
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "JSON"
}

Описание полей запроса

  • url_платежного_модуля — адрес для получения отчета. Возможные значения:
  • reportType — тип получаемого отчета. Возможные значения:
    • RECONCILIATION_REPORT — Отчет сверки,
    • RECEIPT_OF_FUNDS — Поступление средств,
    • ERIP_PAYMENT_RESULTS — ЕРИП Результаты платежей,
    • ERIP_TRANSACTION_LOG — ЕРИП Журнал транзакций.
  • email — email, на который может быть отправлен отчет. Отчет приходит на указанный email с задержкой (до 10 мин), после выгрузки требуемой информации из базы данных.
  • reportFormat — формат отправляемого отчета. Возможные значения:
    • JSON — отчет будет отправлен в формате JSON,
    • EXCEL — отчет будет отправлен файлом .xlsx.
  • startDate, endDate — диапазон дат.
  • login — логин от личного кабинета.
  • password — пароль от личного кабинета, зашифрованный в MD5.

Система удаленной идентификации IDCHECK

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

Все запросы к API отправляются по HTTPS POST протоколу с заголовком Content-Type: application/x-www-form-urlencoded. Ответ возвращается в json формате. Аутентификация осуществляется посредством подписи запроса на основе персонифицированного api ключа (api_key), подробнее о механизме подписи указано в соответствующем параметре запроса.

Пример Workflow процесса:

IDCheck workflow

Методы API

  • WEBcheck — проведение проверки в web приложении;
  • mobileCheck — проведение проверки в мобильном приложении;
  • fileCheck — проведение проверки, посредством загрузки документов через API;
  • getStatus — получение статуса проверки;
  • getResult — получение результатов проверки;
  • getDoc — получение проверенного документа;
  • unarchiveDocs — запрос возврата документов перенесённых в архив;
  • testCompleted — завершить тестирование;
  • apiStatus — статус работы сервиса.

WEBcheck

Прохождение проверки посредством web формы.

Выполняется заявителем, которого нужно переадресовать на url: <>/request_id. Где request_id и соответствующая форма генерируется после выполнения данного запроса.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: WEBcheck
3check_idдаstringуникальный идентификатор проверки, определяется клиентом. Должен соответствовать шаблону: [0-9a-zA-Z\-\ _]{1,100}
4flow_nameдаstringназвание схемы идентификации. Должно соответствовать шаблону: [0-9a-zA-Z\-\ _\+]{1,100}
5langнетstringязык формы в формате ISO 639-1. Доступный список языков: ru, en, et, pt, hu, zh, zh-tw, th, id, es, tr, vi, ar, hi, ms, ur, bn, fa, fl, fr, ja, ko, uk, ro. По умолчанию: ru
6signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+check_id
Ответ:
#ПараметрОбязательныйТипОписание
1request_idдаstringидентификатор запроса

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=WEBcheck&check_id=30&sign=75c8a65f407f7180f6a2a3952a7924d4963cd702d5d80bbe564c"

Пример ответа

{
  "request_id": "b19a6c370693218ef0a4b06308fc0a5de32e86e"
}

mobileCheck

Прохождение проверки в мобильном приложении.

Метод создаёт проверку (заявителя) и первичный токен доступа, который требуется для инициализации SDK. Время действия токена 1 час. Обновление токена присутствует в SDK. Документация и доступ к SDK (Android & iOS) выдаётся по согласованию.

Предполагаемая схема работы мобильного приложения:

mobile check method
  1. Инициализация мобильного SDK и запрос данных (токена и если необходимо flow проверки)
  2. Запрос токена по указанному клиентом идентификатору (request_id) заявителя
  3. Получение данных (токена) бэкендом клиента
  4. Получение мобильным приложением инициализационных данных
  5. Прохождение проверки заявителем
Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: mobileCheck
3check_idдаstringуникальный идентификатор проверки, определяется клиентом. Должен соответствовать шаблону: [0-9a-zA-Z\-\ _]{1,100}
4flow_nameдаstringназвание схемы идентификации. Должно соответствовать шаблону: [0-9a-zA-Z\-\ _\+]{1,100}
5signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+check_id
Ответ:
#ПараметрОбязательныйТипОписание
1request_idдаstringидентификатор запроса
2tokenдаstringтокен запроса (передаётся в SDK)

Пример запроса

curl -X POST \ \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=mobileCheck&check_id=31&sign=9e50358233f8af3ae7b005f8d9db8009ea339145bd8309324afd20079b"

Пример ответа

{
  "request_id": "1b0e72851da3f5653edbdada200fa7f1759a",
  "token": "_act-10bd541d-499c-98f3-aa10b64998b50"
}

fileCheck

Отправка документов без участия заявителя. Запрос к API отправляется по HTTPS POST протоколу с заголовком Content-Type: multipart/form-data.

Данный метод можно комбинировать со всеми методами создания запроса или прохождения проверки. Например, загрузить документ без участия заявителя, которому в дальнейшем предложить пройти только проверку живости (включающую проверку на совпадение с документом) в web или mobile sdk.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: fileCheck
3check_idдаstringуникальный идентификатор проверки, определяется клиентом. Должен соответствовать шаблону: [0-9a-zA-Z\-\ _]{1,100}
4flow_nameдаstringназвание схемы идентификации. Должно соответствовать шаблону: [0-9a-zA-Z\-\ _\+]{1,100}
5doc_fileдаbinaryфайл документа
6doc_typeдаstring тип документа
7signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+check_id
Возможные типы документов:
Тип документаОписание
PROFILE_IMAGEфотография заявителя (обычно используется в сверке живости)
PASSPORTпаспорт
Ответ:
#ПараметрОбязательныйТипОписание
1request_idдаstringидентификатор запроса
2upload_statusдаstringстатус состояния загрузки файла
Возможные статусы:
СтатусОписание
okуспешная загрузка
warningфайл документа принят, но предварительная проверка выявила проблемы с документом
errorфайл не принят

getStatus

Получение статуса проверки.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: getStatus
3request_idдаstringидентификатор запроса
4signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+request_id
Ответ:
#ПараметрОбязательныйТипОписание
1statusдаstringстатус
Описание возможных статусов ответа:
НазваниеОписание
newновый запрос верификации
in_progressидёт проверка документов
completedпроверка завершена
canceledпроверка отменена (не были загружены все документы или истекло время ожидания)

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getStatus&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=g546cbc1268d886edcc300fb05e1550d91b2a06a7c494c4a85899b830b"

Пример ответа

{
  "status": "in_progress"
}

getResult

Получение результатов проверки.

Так же результаты приходят в postback запросе, который дополнительно содержит параметр sign. Формат запроса formdata (по-умолчанию) или json на выбор клиента.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: getResult
3request_idдаstringидентификатор запроса
4signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+request_id
Ответ:
#ПараметрОбязательныйТипОписание
1check_idдаstringидентификатор проверки
2resultдаstringрезультат проверки: GREEN | RED
3reject_labelsнетarray одна или несколько причин отказа в верификации (таблица reject_labels)
4reject_finalнетintвозможность повторной отправки документов для проверки; 1 — означает финальный отказ. Значения: 0 | 1
5review_dateдаstringдата и время прохождения проверки (ISO 8601 формат: YYYY-MM-DDThh:mm:ss±hh:mm)
6applicant_summary_infoнетarrayобщие данные заявителя, собранные из возможных источников, могут быть установлены, переопределены клиентом или заявителем
applicant_summary_info[].firstNameнетstringимя
applicant_summary_info[].firstNameEnнетstringимя латиницей
applicant_summary_info[].lastNameнетstringфамилия
applicant_summary_info[].lastNameEnнетstringфамилия латиницей
applicant_summary_info[].middleNameнетstringотчество
applicant_summary_info[].middleNameEnнетstringотчество латиницей
applicant_summary_info[].legalNameнетstringюридическое имя физического лица
applicant_summary_info[].genderнетstringпол: M | F
applicant_summary_info[].dobнетstringдата рождения (формат: YYYY-mm-dd)
applicant_summary_info[].placeOfBirthнетstringместо рождения
applicant_summary_info[].countryOfBirthнетstringстрана рождения
applicant_summary_info[].stateOfBirthнетstringрегион рождения
applicant_summary_info[].countryнетstringAlpha-3 код страны (Wikipedia)
applicant_summary_info[].nationalityнетstringAlpha-3 код страны национальности
applicant_summary_info[].phoneнетstringтелефон
applicant_summary_info[].mobilePhoneнетstringмобильный телефон
applicant_summary_info[].applicant_platformнетstringустройство заявителя
applicant_summary_info[].addressesнетarrayадрес
applicant_summary_info[].addresses[].countryнетstringAlpha-3 код страны
applicant_summary_info[].addresses[].postCodeнетstringпочтовый индекс
applicant_summary_info[].addresses[].townнетstringгород
applicant_summary_info[].addresses[].streetнетstringулица
applicant_summary_info[].addresses[].subStreetнетstringдополнительная информация
applicant_summary_info[].addresses[].stateнетstringрегион
applicant_summary_info[].addresses[].buildingNameнетstringназвание здания
applicant_summary_info[].addresses[].flatNumberнетstringномер квартиры
applicant_summary_info[].addresses[].buildingNumberнетstringномер здания
applicant_summary_info[].addresses[].startDateнетstringдата начала проживания (формат: YYYY-mm-dd)
applicant_summary_info[].addresses[].endDateнетstringдата окончания проживания (формат: YYYY-mm-dd)
7docs_dataнетarrayизвлечённые данные документов
docs_data[].idDocTypeдаstringтип документа (PASSPORT, ID_CARD, DRIVERS, SELFIE, VIDEO_SELFIE)
docs_data[].idDocSubTypeнетstringсторона документа (FRONT_SIDE, BACK_SIDE или null)
docs_data[].idsDocдаarrayмассив имён файлов документа (элемент массива — параметр doc_id метода getDoc)
docs_data[].countryнетstringтрёх символьный код страны выдавшей документ
docs_data[].firstNameнетstringимя
docs_data[].firstNameEnнетstringимя латиницей
docs_data[].lastNameнетstringфамилия
docs_data[].lastNameEnнетstringфамилия латиницей
docs_data[].middleNameнетstringотчество
docs_data[].middleNameEnнетstringотчество латиницей
docs_data[].issueAuthorityнетstringорган выдачи документа
docs_data[].issuedDateнетstringдата выдачи
docs_data[].validUntilнетstringдействителен до
docs_data[].numberнетstringномер
docs_data[].dobнетstringдата рождения
docs_data[].placeOfBirthнетstringместо рождения
docs_data[].mrzLine1нетstringданные из документа, не относящиеся к ключевой группе, которые удалось распознать
8is_archivedдаintпараметр описывает состояние переноса документов в архив. Значения: 0 | 1
9data_deletedдаintсостояние удаления персональных данных. Если персональные данные заявителя были удалены, то результат не будет содержать параметры docs_data и applicant_summary_info. Значения: 0 | 1
Описание возможных статусов reject_labels:
НазваниеОписание
FORGERYБыла обнаружена попытка подделки
DOCUMENT_TEMPLATEПредоставленные документы являются шаблонами, загруженными из Интернета
NOT_DOCUMENT Предоставленные документы не имеют отношения к процедуре проверки*
SELFIE_MISMATCHФотография заявителя (изображение профиля) не соответствует фотографии на предоставленных документах
ID_INVALID Документ, удостоверяющий личность (например, паспорт или удостоверение личности) недействителен*
FOREIGNERОтсутствует вид на жительство или указан запрет на приём заявителей из другой страны
DUPLICATEУстановлен запрет на дубликаты и данный заявитель уже проверялся
WRONG_USER_REGIONКогда заявители из определенных регионов/стран не могут быть зарегистрированы
INCOMPLETE_DOCUMENTВ документе отсутствует какая-либо информация или она частично видна
BLACKLISTЗаявитель занесён в чёрный список
UNSATISFACTORY_PHOTOS Сокрыта часть информации или низкое качество фотографии*
DOCUMENT_PAGE_MISSING Некоторые страницы документа отсутствуют*
DOCUMENT_DAMAGED Документ повреждён*
REGULATIONS_VIOLATIONS Нарушение правил*
INCONSISTENT_PROFILEНе соответствие пола (например, женское имя с мужскими документами)
PROBLEMATIC_APPLICANT_DATA Данные заявителя не совпадают с данными в документах*
ADDITIONAL_DOCUMENT_REQUIRED Требуются дополнительные документы*
AGE_REQUIREMENT_MISMATCHВозрастное требование не выполнено (например, нельзя арендовать автомобиль человеку младше 25 лет)
EXPERIENCE_REQUIREMENT_MISMATCHНе хватает опыта (например, недостаточно опыта вождения)
CRIMINALЗаявитель участвует в незаконных действиях
WRONG_ADDRESS Адрес из документов не совпадает с адресом, который ввел пользователь*
GRAPHIC_EDITOR Документ был отредактирован графическим редактором*
DOCUMENT_DEPRIVEDПользователь был лишен документа
COMPROMISED_PERSONSЗаявитель был скомпрометирован
FRAUDULENT_PATTERNSПользователь был найден в криминальных сводках
SANCTIONSЗаявитель находится в санкционных списках
FRONT_SIDE_MISSING Отсутствует лицевая сторона документа*
BACK_SIDE_MISSING Отсутствует обратная сторона документа*
SCREENSHOTS Загружены скриншоты*
BLACK_AND_WHITE Загружены черно-белые фотографии документов*
INCOMPATIBLE_LANGUAGE Заявитель должен загрузить перевод своего документа*
EXPIRATION_DATE Просроченный документ*
UNFILLED_ID Документ без подписей и штампов*
BAD_SELFIE Некорректное селфи*
BAD_VIDEO_SELFIE Некорректное видео-селфи*
BAD_FACE_MATCHING Проверка лица между документом и селфи не удалась*
BAD_PROOF_OF_IDENTITY Неверный документ, удостоверяющий личность*
BAD_PROOF_OF_ADDRESS Неверное подтверждение адреса*
BAD_PROOF_OF_PAYMENT Неверное подтверждение оплаты*
SELFIE_WITH_PAPER Заявитель должен загрузить специальную селфи (например, селфи с бумагой и датой на ней)*
OTHERДругие причины

* — reject_final=0 можно использовать тот же request_id для повторной загрузки документов заявителем.

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getResult&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=456h9f69491724f43fddedfc00750d0efbd540d4ec0538ceaa27d3316bd52"

Пример ответа

{
  "check_id": 30,
  "result": "GREEN",
  "review_date": "2020-01-23T17:36:26+03:00",
  "is_archived": 0,
  "applicant_summary_info": {
    "firstName": "ВЛАДИМИР",
    "firstNameEn": "VLADIMIR",
    "middleName": "АЛЕКСЕЕВИЧ",
    "middleNameEn": "ALEXEYEVICH",
    "lastName": "ПЕТРОВ",
    "lastNameEn": "PETROV",
    "dob": "1986-03-18",
    "gender": "M",
    "placeOfBirth": "REPUBLIC OF BELARUS",
    "country": "BLR",
    "applicant_platform": "Android"
  },
  "docs_data": [
    {
      "idDocType": "PASSPORT",
      "country": "BLR",
      "firstName": "ВЛАДИМИР",
      "firstNameEn": "VLADIMIR",
      "middleName": "АЛЕКСЕЕВИЧ",
      "middleNameEn": "ALEXEYEVICH",
      "lastName": "ПЕТРОВ",
      "lastNameEn": "PETROV",
      "issuedDate": "2018-11-24",
      "validUntil": "2028-11-24",
      "number": "KB00001",
      "additionalNumber": "000001PB2",
      "dob": "1986-03-18",
      "placeOfBirth": "REPUBLIC OF BELARUS",
      "idsDoc": [
        45001,
        27686705
      ]
    },
    {
      "idDocType": "SELFIE",
      "idsDoc": [
        435890
      ]
    }
  ]
}

getDoc

Получение документа прошедшего проверку.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: getDoc
3request_idдаstringидентификатор запроса
4doc_idдаstringидентификатор документа
5signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+doc_id
Ответ:

Файл документа, заголовок Content-Type ответа опишет mime-тип.

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getDoc&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&doc_id=45001&sign=fg546cbc12685486edcc305e1550d91b2a06a7c494c4219b830b"

unarchiveDocs

Возврат документов из архива.

После выполнения будет возможность снова забрать документы методом getDoc.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: unarhiveDoc
3request_idдаstringидентификатор запроса
4signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+request_id
Ответ:
#ПараметрОбязательныйТипОписание
1statusдаstringстатус
Описание возможных статусов ответа:
НазваниеОписание
in_progressдокументы в процессе переноса
completedперенос завершён

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=unarchiveDocs&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=fe1080d9642cd761fb6b4506b38e8f2755e0df1da6504a59e55d3aea94"

Пример ответа

{
  "status": "in_progress"
}

testCompleted

Завершает идентификацию с предустановленным результатом. Доступно только в тестовой среде.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: testCompleted
3request_idдаstringидентификатор запроса
4test_resultдаstringс каким результатом завершить проверку: GREEN | RED
5reject_labelнетstring причина отказа (RED статус) верификации (таблица reject_labels)
6reject_finalнетIntсостояние финального отказа значения: 0 | 1. По умолчанию: 1 (финальный)
7signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method+request_id
Ответ:
#ПараметрОбязательныйТипОписание
1statusдаstringстатус (done)

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=testCompleted&request_id=a19a6c370693218ef0a4b06308fc0a5de32e86e&test_result=GREEN&sign=fe1080d9642cd761fb6b4506b38e8f2755e0df1da6504a59e55d3aea94"

Пример ответа

{
  "status": "done"
}

apiStatus

Статус работы сервиса.

Запрос:
#ПараметрОбязательныйТипОписание
1client_idдаstringидентификатор клиента
2methodдаstringметод API: apiStatus
3signдаhashподпись запроса представляет из себя sha256 хеш строки, состоящей из конкатенации значений следующих параметров: api_key+method
Ответ:
#ПараметрОбязательныйТипОписание
1statusдаintстатус сервиса, статический ответ (200)

Пример запроса

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=apiStatus&sign=33cbc277c9cfe9a91ead1145c1c6670ba4bcddbc0294d13b76f1b69eca1fc5b7"

Пример ответа

{
  "status": "200"
}

Ошибки

При возникновении ошибки ответ содержит параметр error с кодом ошибок.

Описание ошибок:
ОшибкаОписание
400Некорректный запрос
401Ошибка аутентификации
404Запрошенная сущность не найдена
405Неправильный метод запроса
406Невозможно выполнить запрос с текущими условиями
409Переданы некорректные данные для проверки
429Слишком много запросов
503Сервис временно недоступен

Тестовая среда

Тестовая среда имеет тот же функционал, что и продакшен, за исключением того, что проверка документов не производится. Дополнительно представлен метод testCompleted для формирования нужного ответа.