Данное руководство описывает процесс разработки платежного модуля для приема платежей в сети Интернет 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 (уникальный номер транзакции, присваиваемый процессинговым центром) платежа;
  • указать E-mail, привязанный к транзакции;
  • указать 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-приложения.

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

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

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

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

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

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

Название поля Обязательное поле Описание поля Примечание
*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)

Перейти к разделу: Извещение об оплате.
wsb_test да

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

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

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

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

Example form

              
<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="Минск пр. Независимости д.1 кв.2">
  <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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <input type="hidden" name="wsb_tax" value="1050">
  <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>
              
            

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

Название поля Обязательное поле Описание поля Примечание
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 нет Поле содержит значение промокода скидки для заказа. Максимальная длина поля 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. При отсутствии поля - порядок вкладок стандартный — оплата картой, потом ЕРИП

ВАЖНО! Все текстовые поля должны быть в кодировке UTF-8 или windows-125.

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

Электронная подпись формируется для предотвращения изменений в форме платежа и должна присутствовать в каждой форме заказа. Все заказы без электронной подписи не будут рассматриваться системой 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) объединенной строки.

Example form

            
            
$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 для уведомлений",значение которого можно установить в настройках биллинг-аккаунта в разделе меню "Настройки" → "Компания".

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

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

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

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

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

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

  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 - ЕРИП

order_id Номер заказа в системе WEBPAY
site_order_id Номер (имя) заказа, присвоенное магазином
transaction_id Номер транзакции
payment_type

Тип транзакции. Успешной оплате соответствуют значения: 1 и 4

rrn Номер транзакции в системе VISA/MASTERCARD/БЕЛКАРТ
wsb_signature Электронная подпись (вычисляется в случае, если в настройках биллинг-аккаунта указан "Секретный ключ")
action Код платежа процессинга
rc Внутренний код WEBPAY результата операции
approval Код операции процессинга

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

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

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

Example form

              
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}
              
            

Механизм 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 учитывается при формировании подписи только в реальной среде.

Example form

              
<?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:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
              
            

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

Example form

              
<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:OrderTag>onlinePayment</ns2:OrderTag>
      </ns2:NotifierRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
              
            

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

Example form

              
<?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 может быть произвольным.

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

Example form

              
<?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.

transaction_id Номер транзакции
batch_timestamp Время совершения транзакции
currency_id Валюта транзакции
amount Сумма транзакции
payment_method

Метод совершения транзакции. Возможные значения:

test - совершена без реального процессинга карточки

cc - банковская карточка

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

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

Example form

              
// API Request
$postdata = '*API=&API_XML_REQUEST=''.urlencode('
  <?xml version="1.0" encoding="ISO-8859-1" ?>
    <wsb_api_request>
      <command>get_transaction</command>
      <authorization>
        <username>your_username</username>
        <password>your_md5_password</password>
      </authorization>
      <fields>
        <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;
              
            

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Совершение платежей

ВАЖНО! Для подключения данной услуги, необходимо обратиться к менеджеру компании WEBPAY по адресу managers@webpay.by

Для внедрения услуги "Упрощенный платеж" Поставщику услуг достаточно внести минимальные изменения в POST-запрос из раздела Разработка платежного модуля для перехода к выполнению оплаты. Стоит обратить внимание, что оплата в тестовой среде по умолчанию производится всегда по одной карте, которая подставляется автоматически. Для того, чтобы была возможность ввести разные карты и произвести их привязку, параметру 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) объединенной строки.

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

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="86832487d9996b0f863bcd655023a281ac88727d">
  <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>
              
            

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

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

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

До проведения рекуррентных (CoF) платежей необходимо осуществить инициирующий платеж, служащий контрактом, с участием Держателя карты и с вводом всех данных карты по стандартному сценарию. Дальнейшее осуществление рекуррентных (CoF) платежей происходит без участия Держателя карты и без передачи CVV. Инициирующий платёж поддерживает 3-D 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) будет осуществлена привязка карты.

Запросы

Дополнительные поля формы оплаты

С описанием основных полей для осуществления 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.

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

Для осуществления инициирующего платежа необходимо сформировать форму со специальными полями, значения и описания которых представлены в разделе Поля формы оплаты и Дополнительные поля формы оплаты. Затем 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) объединенной строки.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="9418af1d506f8f8da1dc577278a1f0d89eecc66d">
  <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 (например, 2016-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 строки.

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

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

Параметр 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) платежа. Если срок подписки истек, платеж совершен не будет. При валидном сроке подписки карты для данного пользователя происходит оплата услуги без отображения платежной страницы.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="d0a6ec427fc2e0b5c90729606ee819e2684b9824">
  <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 и соответственно данное поле не участвует в расчете подписи.

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

Example form

              
//Ответ об успешном рекуррентном платеже
Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586712564¤cy_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¤cy_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) платежей должна состоять из следующего набора полей:

  • 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) объединенной строки.

Example form

              
<!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 отправляет ответ об успешной либо ошибочной отвязке.

Example form

              
//пример ответа об успешной отвязке
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 File Completed
ЗАО "МТБанк"
ОАО "Белагропромбанк"
ОАО "БПС-Сбербанк"
Инициирующий Authorized → Completed
Рекуррентный Authorized → Completed

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

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

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

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

Товары, оплачиваемые по картам рассрочки "Приорбанк" ОАО или ЗАО "МТБанк" (Халва), подпадают под определенный тип рассрочки. У поставщика услуг может быть несколько типов рассрочки (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 определит вводимую плательщиком карту и на ее основании оплата будет произведена по соответствующему терминалу.

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

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

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

Selecting the payment method for the X-card

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="2e45588afe41be5372af7a250628dd03846d8e30">
  <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 с карты Халва Плюс.

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

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

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

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

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

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

Тип карты Значение промокода
VISA/MASTERCARD Gold gold
VISA/MASTERCARD Platinum platinum
VISA/MASTERCARD Infinite infinite
VISA visa
MASTERCARD (не входят карты MAESTRO и БЕЛКАРТ-MAESTRO) mastercard

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

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

Example form

              
<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="Минск пр. Независимости д.1 кв.2">
  <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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <input type="hidden" name="wsb_tax" value="1050">
  <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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <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:

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

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

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

Также в меню "Счета" отображаются все ваши счета и присутствует окно поиска по различным критериям: статусу, дате создания, имени счета, имени счета мерчанта, 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, e-mail, мессенджеры).

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

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

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

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

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

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

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

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

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

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

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

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

  • если у Вас подключен интернет-эквайринг;

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

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

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

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

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

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

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

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

Merchant PCI DSS

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

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

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

Поля ответа

Название поля Описание
time Время выполнения запроса
orderNumber Номер заказа
invoiceNumber Номер счета
transaction Id транзакции
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 в ответе возвращает

Example form

              
{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=7344
4a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e334b48526
e592c",
"tokenName":"wt",
"availableOption":"ipsPayment,halva",
"paymentType":""}
              
            

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

Example form

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

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

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

Example form

              
{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=7344
4a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e334b48526
e592c",
"tokenName": "wt",
"acsUrl": "https://aacsw.3ds.verifiedbyvisa.com",
"PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U
4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSCWR89fiTGzObs",
"TermUrl": "https://payment.webpay.by:443",
"MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=54715979
4b415849646e5242754b35545865694b5766726d62"}
              
            

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

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

Example form

              
$params['PaRes'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a
05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566
e334b48526e592c";
$params['MD'] = "d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae
80=547159794b415849646e5242754b3555865694b5766726d62";
              
            

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

Example form

              
{"token":"ffc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444
a4f5f39",
"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 для Интернет-ресурсов, подключенных к интернет-эквайрингу. Функционал доступен при работе через банк-эквайер ОАО "БелВЭБ".

Для ввода и вывода денежных средств на Вашем сайте допускается использование плательщиком карт платежных систем 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.

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

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

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

Тип операции Раздел
Пополнение, привязка карты и последующее пополнение POST-запрос;
Упрощенный платеж
Вывод денежных средств Web функции (запрос TransactionB2C). Перед применением необходимо сообщить IP адрес, с которого будет осуществляться запрос

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

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

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

Для тестирования B2C следует использовать URL https://sandbox.webpay.by/WSBApi2 и запрос TransactionB2C (Web функции).

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

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

Tag Type Description Value Format
C1 T First Name ans ...35
C2 T Middle Name ans 1
C3 T Last Name ans ...35
C4 T Street Address ans ...50
C5 T City ans ...25
C6 T State/Province Code ans ...3
C7 T Country ans 3
C8 T Postal Code ans ...10

ans – alphabetic, numeric and special characters

Для тестирования можно воспользоваться тестовой картой

Номер карты Срок действия CVV
5445781008964725 10/22 395

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

Example form

              
<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":"VTWO","C3":"LNAMES","CC":"00",
    "C4":"av. POBEDITELEY101","C5":"MINSK","C7":"112","C8":"220019"}</addInfo>
  </parameters>
</TransactionB2C>
              
            

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

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

Example form

              
$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;
}
              
            

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

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

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

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. Описание данного алгоритма представлено далее.

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

Название поля Тип данных Обязательно Описание поля Кодировки и прочее
resourceId String Да Идентификатор Магазина в системе WEBPAY
resourceOrderNumber String Да Уникальный номер заказа, присваиваемый Магазином
validThrough Date Нет Дата, до которой можно оплатить заказ
shortDescription String Нет Краткое описание товара
creationTime Date Нет Дата создания заказа Магазином
longDescription String Нет Подробное описание товара
languageCode String Нет Код языка согласно ISO 639-1
items Array Да Массив позиций заказа множественный
item ComplexType Да Позиция заказа items/
name String Да Наименование товара items/item/
quantity Integer Да Количество товара items/item/
price ComplexType Да Стоимость одной позиции items/item/
amount BigDecimal Да Стоимость одной позиции items/item/price/
currency String Да Валюта позиции согласно ISO 4217 items/item/price/
urls Map Да Массив адресов множественный
name Enum Да Возможные значения:
resourceReturnUrl - URL для редиректа в случае успешной авторизации;
resourceCancelUrl - URL для редиректа в случае не успешной авторизации;
resourceNotifyUrl - URL для отправки нотификатора (paymentStatus).
urls/
url String Да URL, соответствующий вышеуказанному типу ('name') urls/
customer ComplexType Нет Наименование получателя товара/услуги
resourceCustomerId String Да Идентификатор получателя товара/услуги customer/
name String Нет Имя получателя товара/услуги customer/
surname String Нет Фамилия получателя товара/услуги customer/
email String Нет Email получателя товара/услуги customer/
phone String Нет Телефон получателя товара/услуги customer/
discounts Array Нет Массив позиций скидок заказа множественный
discount ComplexType Да Скидка заказа discount/
name String Да Наименование скидки discount/
promoCode String Нет Промокод discount/
type String Нет Тип скидки discount/
value ComplexType Да Описание стоимости скидки discount/
amount BigDecimal Да Стоимость скидки discount/value/
currency String Да Валюта позиции согласно ISO 4217 discount/value/
shippings Array Нет Массив позиций доставок множественный
shipping ComplexType Да Доставка shipping/
name String Да Наименование доставки shipping/
value ComplexType Да Описание стоимости доставки shipping/
amount BigDecimal Да Стоимость доставки shipping/value/
currency String Да Валюта позиции согласно ISO 4217 shipping/value/

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

Example form

              
{"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",
"unit":"ww.",
"quantity":"1",
"price":{
"currency":"BYN",
"amount":130.10}},
{"idx":2,
"name":"Product 2",
"unit":"qt.",
"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"}}
              
            

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

Название Тип Обязательный Описание
resourceId String Да Идентификатор Магазина в системе WEBPAY
resourceOrderNumber String Да Номер заказа в системе Магазина
webpayInvoiceId Integer Нет ID заказа в системе WEBPAY
webpayInvoiceNumber String Нет Уникальный номер заказа в системе WEBPAY
invoiceURL String Нет URL адрес счета

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

Example form

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

Ответ системы WEBPAY при ошибке

Example form

              
{"errorCode":"BAD_REQUEST",
"errorMessage":"resourceId: Resource not found or disabled"}
              
            

Механизм формирования 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 Да Тело запроса

Example form

              
<?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+ZW6cj
tOWKr51o0stKbfWxnsRjLxGgT9s+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";?>
              
            

Структура запроса для получения отчетности

Запрос осуществляется на URL адрес:

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

Example form

              
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;
              
            

Форматы отчетов

Отчет от системы WEBPAY можно получить в двух форматах:

  • JSON
  • EXCEL-file

Отчет приходит на указанный email с задержкой (до 10 мин), после выгрузки требуемой информации из базы данных.

Example form

              
// JSON
{
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "JSON"
}

//EXCEL-file
{
  "email": "test@webpay.by",
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "EXCEL"
}
              
            

Типы отчетов

Система WEBPAY может высылать следующие типы запросов:

  • RECONCILIATION_REPORT - отчет сверки;
  • RECEIPT_OF_FUNDS - поступление средств;
  • ERIP_PAYMENT_RESULTS - ЕРИП Результаты платежей;
  • ERIP_TRANSACTION_LOG - ЕРИП Журнал транзакций.