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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Раздел Ошибки

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

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

Таблица ошибок

Для каждого процессинга представлена таблица с ошибками, которая состоит из следующих столбцов:

  • Код ошибки — код ошибки, который нам предоставил банк.
  • Текст ошибки — текстовое сообщение ошибки, которое отражается в чеке у плательщика при неуспешной оплате.
  • Расшифровка/Причины возникновения — причины возникновения ошибки и ее расшифровка, чтобы Вам было понятно, почему произошла данная ошибка.
  • Рекомендации — описание того, что можно сделать чтобы ошибка не повторялась.

Как использовать раздел Ошибки

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

  1. Перейдите в раздел Ошибки из меню личного кабинета.
  2. Выберите подраздел, соответствующий процессингу банка, через который была произведена попытка оплаты.
  3. Просмотрите таблицу ошибок, чтобы найти ошибку, которая Вас интересует.
  4. Ознакомьтесь с расшифровкой ошибки, чтобы понять ее причину.
  5. Следуйте рекомендациям, чтобы устранить ошибку.

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

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

Для получения отчетов по платежам, совершенным через АИС "Расчет" (ЕРИП) и/или интернет-эквайринг, и результатов сверки поступления средств Вам необходимо зайти в систему отчетности по адресу 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.
Дата учета платежа в банке Дата отражения денежных средств в банке-эквайере.
Сумма возмещения платежа Сумма платежа в системе WEBPAY.
Сумма комиссии Комиссионное вознаграждение банку.
Валюта учета платежа в банке Валюта, в которой отражаются денежные средства в банке.
Дата и время отмены/возврата Дата и время отмены/возврата платежа в системе WEBPAY.
Сумма отмены/возврата Сумма отмены/возврата платежа в системе WEBPAY.
Дата учета возврата в банке Дата отражения возврата денежных средств в банке-эквайере.
Сумма возврата в банке Сумма отражения возврата денежных средств в банке-эквайере.
Сумма возврата комиссии Комиссионное вознаграждение банку за осуществление возврата.
Сумма торговца Сумма списания с банковской платежной карты плательщика, если валюта транзакции в Магазине отличается от валюты на банковской платежной карте плательщика.
Валюта торговца Валюта списания с банковской платежной карты плательщика, если валюта транзакции в Магазине отличается от валюты на банковской платежной карте плательщика.
Курс валюты торговца Курс конвертации, установленный платёжной системой/банком-эквайером, при списании денежных средств с банковской платежной карты плательщика, если валюта транзакции в Магазине отличается от валюты на банковской платежной карте плательщика.
Адрес плательщика Адрес плательщика, переданный Магазином в систему WEBPAY.
Отправитель денежных средств Информация о плательщике, переданная Магазином в систему WEBPAY.
Номер договора с заказчиком услуги/плательщиком Номер договора с заказчиком услуги/плательщиком, переданный Магазином в систему WEBPAY.
Назначение платежа Назначение платежа, переданное Магазином в систему WEBPAY.
Email плательщика Email, указанный плательщиком при оплате.
Рекуррентный платеж

Тип рекуррентного платежа. Возможные значения:

Инициирующий — была осуществлена привязка банковской платежной карты плательщика.

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

Банк-эмитент Банк, выпустивший банковскую платежную карту, плательщика.
Страна банка-эмитента Страна банка, выпустившего банковскую платежную карту, плательщика.
Выплата

Операция вывода денежных средств. Возможные значения:

Да — осуществлена операция вывода денежных средств.

Нет — осуществлена оплата плательщиком за услуги/товары Магазина.

Номер карты 6х4 Маскированный номер банковской платежной карты плательщика.
Id авторизации Уникальный идентификатор операции авторизации в системе WEBPAY.
Id фин. завершения Уникальный идентификатор операции финансового завершения в системе WEBPAY.
Id возврата Уникальный идентификатор операции возврата в системе WEBPAY.
Id сброса Уникальный идентификатор операции сброса в системе WEBPAY.

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

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

Указывает на принадлежность банковской платежной карты плательщика Банкам РБ. Возможные значения:

Us — принадлежит Банку РБ.

Not Us — принадлежит иностранному Банку.

Сумма сделки Сумма заказа в Магазине без учета суммы скидки и суммы доставки.
Сумма скидки Сумма скидки, установленная Магазином.
Наименование скидки Описание скидки, указанное Магазином.
Сумма доставки Стоимость доставки, установленная Магазином.
Наименование доставки Описание доставки, указанное Магазином.
Отправитель денежных средств Информация о плательщике, переданная Магазином в систему WEBPAY.
Номер договора с заказчиком услуги/плательщиком Номер договора с заказчиком услуги/плательщиком, переданный Магазином в систему WEBPAY.
Назначение платежа Назначение платежа, переданное Магазином в систему WEBPAY.
Тип карты Тип банковской платежной карты плательщика (DEBIT, CREDIT, CHARGE CARD).
Email плательщика Email, указанный плательщиком при оплате.
Рекуррентный платеж

Тип рекуррентного платежа. Возможные значения:

Инициирующий — была осуществлена привязка банковской платежной карты плательщика.

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

Банк-эмитент Банк, выпустивший банковскую платежную карту, плательщика.
Страна банка-эмитента Страна банка, выпустившего банковскую платежную карту, плательщика.
Выплата

Операция вывода денежных средств. Возможные значения:

Да — осуществлена операция вывода денежных средств.

Нет — осуществлена оплата плательщиком за услуги/товары Магазина.

Id авторизации Уникальный идентификатор операции авторизации в системе WEBPAY.
Id фин. завершения Уникальный идентификатор операции финансового завершения в системе WEBPAY.
Id возврата Уникальный идентификатор операции возврата в системе WEBPAY.
Id сброса Уникальный идентификатор операции сброса в системе 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).

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

Лимиты по операциям для виртуальных платежных терминалов

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

После подключения интернет-эквайринга банк-эквайер передает в WEBPAY необходимые лимиты. WEBPAY при создании и настройке личного кабинета для мерчанта устанавливает их в системе.

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

После изменения лимитов на email, указанный в Профиле компании, отправляется уведомление с указанием:

  • Наименования изменившегося лимита и его значением
  • Наименования организации
  • Биллинг ID
  • URL-адрес сайта

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

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

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

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

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

тип: VISA

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

  1. JSON API.
  2. Создание HTML-страницы с обыкновенной HTML-формой.

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

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

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

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

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

Важно!

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

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

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

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

В случае, если Вам необходимо установить автоматический редирект на URL адрес, то Вы можете обратиться в службу поддержки WEBPAY по адресу support@webpay.by.

К данному URL добавляются значения Идентификатора заказа (wsb_order_num) и номера транзакции (wsb_tid) в системе WEBPAY.
wsb_cancel_return_url нет URL адрес, на который возвращается покупатель в случае не успешной оплаты. К данному URL добавляются значение Идентификатора заказа (wsb_order_num).
wsb_notify_url нет

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

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

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

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

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

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

В тестовой среде Sandbox значение данного поля должно быть равным 1.
wsb_3ds_payment_option нет

Поле, позволяющее принудительно изменять необходимость прохождения 3D-Secure плательщиком. Управление 3D-Secure недоступно для магазинов, которые работают через банк-эквайер "Приорбанк" ОАО.

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

Допустимые значения:

auto — процесс 3D-Secure осуществляется по умолчанию;

force_3ds — принудительное проведение платежа с использованием 3D-Secure. Если карта не поддерживает 3D-Secure, транзакция не пройдёт;

force_3ds_only_auth_yes — после проведения аутентификации с помощью 3D-Secure статус должен быть только Y, что гарантирует успешную аутентификацию пользователя, иначе транзакция не пройдёт;

without_3ds — принудительное отключение 3D-Secure.

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

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

1 — включить передачу токена платежной сессии;

0 — отключить передачу токена платежной сессии.

Правило формирования ссылки, по которой следует направить плательщика: https://URL_адрес_платежной_страницы/{wsb_show_wt}

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

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

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

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

...

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

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

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

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

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

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

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

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

Определение принадлежности карты плательщика к карте рассрочки "Халва" ЗАО "МТБанк" и возможность осуществления оплаты данной картой.

Данное поле не влияет на прохождение оплаты картами, отличными от карт рассрочки "Халва" ЗАО "МТБанк".

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

1 — разрешено проведение оплаты картой рассрочки "Халва" ЗАО "МТБанк";

0 — отказ в проведении оплаты картой рассрочки "Халва" ЗАО "МТБанк".

Пример кода

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

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

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

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

Пример кода

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

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

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

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

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

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

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

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

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

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

Пример кода

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

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

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

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

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

Важно!

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

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

Отображение результата оплаты на стороне Интернет-ресурса

Данный функционал позволяет Интернет-ресурсу отображать результат прохождения оплаты на своей стороне. Сразу после выполнения платежа, плательщик будет перенеправлен на указанный Интернет-ресурсом URL-адрес без отображения на платежной странице WEBPAY результата оплаты.

Важно!

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

Для того, чтобы система WEBPAY осуществила редирект плательщика на страницу Интернет-ресурса, следует добавить в запрос на формирование заказа для оплаты (HTML-форму или JSON API) следующие поля:

  1. wsb_redirect — принимает значение 1.
  2. wsb_return_format — принимает значение json.

После того как плательщик осуществил оплату заказа, система WEBPAY перенаправит его на URL-адрес, указанный Интернет-ресурсом в поле wsb_return_url — в случае успешной оплаты или wsb_cancel_return_url — в случае неуспешной оплаты. Также система WEBPAY направит Интернет-ресурсу в формате JSON следующие параметры с результатом совершения оплаты:

Название Описание
orderNumber Уникальный идентификатор заказа, присвоенный магазином
invoiceNumber Уникальный идентификатор заказа, присвоенный системой WEBPAY
rrn Номер транзакции в системе VISA/MASTERCARD/БЕЛКАРТ
trimPan Номер банковской платежной карты плательщика в формате 123456xxxxxx7890, с которой осуществлялась оплата
responseCode Внутренний код WEBPAY результата операции
responseText Текстовое сообщение о результате операции

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

{
  "orderNumber":"ORDER-12345678",
  "invoiceNumber":"123456789",
  "rrn":"123456789123",
  "trimPan":"123456xxxxxx1234",
  "responseCode":"W0545",
  "responseText":"Недостаточно средств"
}

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

Номер банковской платежной карты плательщика в формате 123456xxxxxx7890, с которой осуществлялась оплата.

Поле включено в нотификатор при использовании сценариев, когда необходима карта в ответе, например, при работе с рекуррентными платежами, мерчантами PCI DSS и т.д.

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

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

  • batch_timestamp
  • currency_id
  • amount
  • payment_method
  • order_id
  • site_order_id
  • transaction_id
  • payment_type
  • rrn
  • card — добавляется в подпись, в зависимости от выбранного сценария работы
  • SecretKey

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

Пример кода

application/x-www-form-urlencoded

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

Механизм SOAP

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

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

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

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

Важно!

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

Пример кода

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

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

Пример кода

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

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

Пример кода

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

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

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

Пример кода

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

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

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

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

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

Тип Значение Описание
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 support@webpay.by и внести небольшие изменения в сценарий взаимодействия приложения Поставщика услуг с программным комплексом WEBPAY. Эта опция сделает оплату товаров для Покупателя более удобной, что, в свою очередь, повысит привлекательность ресурса.

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

Пример кода

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. JSON API.
  2. Создание HTML-страницы с обыкновенной HTML-формой.

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

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

Важно!

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

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

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

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

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

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

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

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

Важно!

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

Важно!

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

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

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

Пример кода

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

Пример кода

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример кода

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример кода

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

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

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

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

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

Платежи Apple Pay

Описание

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

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

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

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

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

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

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

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

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

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

Подключение

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

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

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

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

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

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

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

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

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

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

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

Тип карты Значение промокода
VISA Gold gold
VISA Platinum platinum
VISA Infinite infinite

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

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

Пример кода

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

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

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

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

Visa Offers Platform

Для подключения возможности работы с системой Visa Offers Platform (VOP) необходимо обратиться в техническую поддержку WEBPAY support@webpay.by.

С технической документацией по интеграции с системой VOP можно ознакомиться здесь.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример кода

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

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

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

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

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

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

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

Пример: 1234567_250817125700.bill

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

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

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

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

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

Настройка FTP

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

User name: merchant

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Название поля Тип данных Обязательно Описание поля Кодировки и прочее
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/
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.

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

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

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

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

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

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

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

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

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

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

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

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

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

Где:

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

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

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

Пример кода

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Редактирование счета для оплаты

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

Изменение счета

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

  • При редактировании поля "Счет для покупателя" Вы можете изменить ранее выбранного покупателя на нового покупателя.
  • Если необходимо изменить срок действия счета, Вы можете изменить его в поле "Оплатить до", указав необходимую дату и время.
  • При необходимости изменения языка формы оплаты выставленного счета, нужно редактировать поле "Язык". Система поддерживает два языка формы оплаты — русский и английский.
  • При редактировании счета доступно поле "Добавить поле", нажав на него Вы можете добавить в уже созданный счет новые товары/услуги. Так же можно удалять товары из счета нажав на кнопку "—".
  • Редактировать поля "Код продукта", "Имя продукта", "Цена", "Количество", "Стоимость доставки", "Скидка", а так же вносить изменения в поле "Примечание".
Изменение данных в счете

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

История изменений счета

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

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

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

QR-код - единый поддомен

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

Раздел QR коды

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

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

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

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

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

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

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

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

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

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

QR-код - уникальный поддомен

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

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

Раздел QR коды

Основные характеристики QR-кода

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

Работа с QR-кодом

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

Сканирование QR-кода ведет на платежную форму, которая будет иметь адрес вида: https://название_магазина.w-p.by

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

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

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

На странице QR будет отображаться следующая информация:

  • Логотип компании
  • Кнопки для переключения языка, цвет которых можно настроить под цвет бренда компании
  • Реквизиты магазина, которые были переданы нам при подключении
  • Адрес и время работы магазина (цвет иконок также можно настроить под цвет бренда компании)
  • Обязательные поля для заполнения плательщиком (сумма, валюта, email, наименование товара/услуги)
  • Дополнительные поля, которые можно настроить под нужды компании (например, ФИО, № договора, Номер телефона, Адрес и т.п.)

При нажатии на кнопку "Информация об оплате" будет отображаться общая информация о том, как осуществляется оплата.

Пример информации об оплате

Оплата по QR-коду

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

Отчеты

Результаты проведения платежей и отчет можно посмотреть и/или загрузить в необходимом формате в личном кабинете WEBPAY в разделе "Отчеты → Отчет по QR счетам". В столбце Дополнительная информация будут отображаться данные, которые указал плательщик при совершении платежа.

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

Мерчанты PCI DSS

Формирование оплаты

Для осуществления интеграции с системой WEBPAY мерчантов PCI DSS, которые работают с данными карт на страницах своего веб-сайта или непосредственно в своем приложении и хотят использовать интеграцию Host2Host, следуйте, пожалуйста, инструкциям ниже:

  1. Сформируйте стандартный POST-запрос (раздел Формирование заказа для оплаты).
  2. Добавьте в запрос поле wsb_encrypted_data.
  3. Добавьте в запрос поле wsb_email. При данном способе работы это поле является обязательным при отправке запроса.
  4. Дополнительно можно добавить поле wsb_return_format для указания формата ответа от нашей системы.
Название поля Обязательное поле Описание Примечание
wsb_encrypted_data Да Содержит зашифрованный JSON формата {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}. Шифруется по алгоритму RSA с помощью публичного ключа из личного кабинета.
wsb_email Да Электронный адрес покупателя.
wsb_return_format Нет Формат вывода результата. Возможное значение: json.

Важно!

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

Поля ответа

Название поля Описание
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 в ответе возвращает

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

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

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

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

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

Сценарий проведения PCI DSS платежа по 3D-Secure 1.0

Шаг 1

Сформируйте POST-запрос как описано в разделе Формирование оплаты и отправьте его по адресу https://payment.webpay.by/api/v1/payment — для реальной среды или по адресу https://securesandbox.webpay.by/api/v1/payment — для тестовой среды.

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

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"VYs5XZYA79BORvcPW4LbBM6x4B36lBnQskF7j61UVlsH4ENPrPCs1exkJdCF6fX9nyENvrC434w3tL6HBtY7mxFXFvMBbsNoDbF4OC4lJEPVSSoBASLZH/9M1hBtavKjjDyKWXsCd5HYihp6PRTs3rMtw9+6Dao8hyfucMxyGpzDU/fW7DZdZ1GY3RIRKXJgPOP/AWv1YORy22BtyNs461CKuyXVY5AdeLO7WmV2x9kxexKNncKO4o0voy9KjW/nYj7R1YCQAZ4k1G2ZuXku90+yeo/AVBCXVTOEejwfplw9dFARes6OtQcW10kQmTdMi9200bf3sY2lQ1UZSbNMRw==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Стоимость доставки",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Скидка на товар",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":""
}

После отправки запроса на указанный URL, WEBPAY вернет в ответ заполненные поля acsUrl, PaReq, TermUrl, MD.

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

{
  "data":{
    "token":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl":"https:\/\/ucas.npc.by:8443\/pareq\/194978586\/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d\/",
    "PaReq":"eJxVUctSwkAQvPsVFB\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\/LNf9eTAbA3EVEOkSFadcUMllh\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\/t38FyiprZE=",
    "MD":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "TermUrl":"https:\/\/payment.webpay.by\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c"
  }
}

Шаг 2

Далее для продолжения сессии необходимо отправить полученные параметры на URL адрес, который содержится в ответе в поле acsUrl. Запрос отправляется методом POST с заголовком Content-Type: multipart/form-data, содержащий в теле запроса поля PaReq, MD, TermUrl со значениями из ответа из шага 1.

Важно!

  • Из значения поля acsUrl нужно убрать все обратные слэши "\".
  • Значение поля TermUrl предварительно замените на свой URL адрес, где Вы будете обрабатывать ответ от acs.

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://ucas.npc.by:8443/pareq/194978586/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('PaReq' => 'eJxVUctSwkAQvPsVFB\\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\\/LNf9eTAbA3EVEOkSFadcUMllh\\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\\/t38FyiprZE=','TermUrl' => 'https:\\/\\/payment.webpay.by\\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c','MD' => '92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c'),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: multipart/form-data'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

После отправки запроса у Вас появится форма, куда плательщику в поле ввода необходимо ввести 3D-Secure код, полученный через СМС на номер мобильного телефона, к которому привязана его банковская карточка.

После того как плательщик ввел 3D-Secure смс-код и нажал кнопку Подтвердить, на Ваш URL адрес для обработки ответа от acs, указанный ранее в поле TermUrl, придут параметры — token, PaReq, MD — необходимые для восстановления сессии в WEBPAY.

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

{
  "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
  "PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC WR89fiTGzObs",
  "MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"
}

Шаг 3

Вам необходимо отправить POST-запрос в WEBPAY с параметрами, которые пришли от acs в шаге 2.

Для восстановления сессии в WEBPAY следует отправить POST-запрос по адресу https://payment.webpay.by/api/v1/payment?wt={token} — для реальной среды или по адресу https://securesandbox.webpay.by/api/v1/payment?wt={token} — для тестовой среды, где:

  • token — значение поля token, которое пришло в ответе от aсs в шаге 2 (также вместо этого параметра можно передавать параметр MD).

Тело запроса должно содержать параметры MD и PaReq, также полученные от acs на шаге 2.

Шаг 4

WEBPAY получает от Вас запрос из шага 3, обрабатывает, отправляет в процессинг и возвращает Вам ответ в формате JSON. Обратите внимание, что ответ приходит от сервиса WEBPAY во вложении data.

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

{
  "data":{
    "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
    "tokenName":"wt",
    "time":"2023.06.26 13:25:58",
    "orderNumber":"ORDER-de35",
    "invoiceNumber":"796529012",
    "transaction":"608120887",
    "authorizationCode":"885415",
    "rrn":"001783883631",
    "trimPan":"512722xxxxxx8665",
    "payee":"\u041e\u041e\u041e \u00ab\u0412\u0415\u0411 \u041f\u042d\u0419\u00bb",
    "amount":"0.10",
    "currency":"BYN",
    "responseCode":"",
    "responseText":"",
    "acsUrl":""
  }
}

Сценарий проведения PCI DSS платежа по 3D-Secure 2.0

Шаг 1

Для осуществления интеграции по проведению PCI DSS платежа по 3D-Secure 2.0, слеуйте инструкциям ниже:

  1. Сформируйте POST-запрос как описано в разделе Формирование оплаты.
  2. Добавьте в запрос поле wsb_tds_notification_url, которое должно содержать значение URL адреса, на который произойдет перенаправление плательщика после прохождения 3D-Secure проверки и на который Вам вернутся параметры с результатом прохождения 3D-Secure сессии.
  3. Отправьте запрос по адресу https://payment.webpay.by/api/v1/payment — для реальной среды или по адресу https://securesandbox.webpay.by/api/v1/payment — для тестовой среды.

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

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"LxWN6haDcxu7K2prY2t4P7enfuejEsU7lbD2xvaa8lwQcLQAhchW8xvUXPZWPiYpWuMKtaC3emwALfw9wcB388Gj86Kh7pVSGyljckcFY69tSmvUrUCJYvpNIvYLcBALotXRQCZiijn+ryaXyS0Ymu8G6S6sahWH2UkIEsZJrmMdq2N5fy4sB6fFmDZCtJdCpZHgpCiK9GjX1gvwiB7pOu4vJEwxVmPdheeYsYQiruk+be9U+ENK0EqRA7rZQlrM80lOxw2j2dF2KZYeVbdo5BiYX11bcHNZcgfTbu2zGTQF6MRkV/VPjUuJ+hkMTYPl9XeUYLq8+fMk3QauP/+AXg==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Стоимость доставки",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Скидка на товар",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":"",
  "wsb_tds_notification_url":"https://companyname.com/test/"
}

После отправки запроса на указанный URL, WEBPAY вернет в ответ заполненные поля token, acsUrl, creq.

Важно!

При прохождении 3D-Secure проверки по Frictionless flow (процесс 3D-Secure аутентификации без участия держателя карты. Банк-эмитент самостоятельно собирает данные о транзакции, в том числе и об устройстве, с которого она совершается, и оценивает возможный уровень мошенничества. Если угроз не обнаруживается, подтверждение платежа проходит незаметно для плательщика), на запрос из шага 1 будет получен ответ из шага 3.

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

{
  "data":{
    "token":"17efa805408c3d0496476f7ef66d5a8f=62554e714f44564b4d30524f4f553148526a527263466c775748687861545a765758466e53476833516d6f3353457458565564595345643157585242636e6c5056573956516e4275575652564e475a4564544a7753672c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl": "https:\/\/emvacs.qiwi.com\/acs\/api\/3ds2\/creqbrw",
    "threeDSSessionData":"",
    "creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0="
  }
}

Шаг 2

Далее для продолжения сессии необходимо отправить полученные параметры на URL адрес, который содержится в ответе в поле acsUrl. Запрос отправляется методом POST с заголовком Content-Type: application/x-www-form-urlencoded, содержащий в теле запроса поле creq со значением из ответа из шага 1.

Важно!

  • Из значения поля acsUrl нужно убрать все обратные слэши "\".

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

POST /acs/api/3ds2/creqbrw HTTP/1.1
Host: emvacs.qiwi.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 327

creq=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0%3D

После отправки запроса у Вас появится форма, куда плательщику в поле ввода необходимо ввести 3D-Secure код, полученный через СМС на номер мобильного телефона, к которому привязана его банковская карточка.

После того как плательщик ввел 3D-Secure смс-код и нажал кнопку Подтвердить, произойдет перенаправление на URL адрес, который был Вами указан в шаге 1 в поле wsb_tds_notification_url, также на указанный URL будут отправлены параметры с результатом 3D-Secure сессии, необходимые для восстановления сессии в WEBPAY.

Шаг 3

Для восстановления сессии в WEBPAY следует отправить POST-запрос с заголовком Content-Type: application/x-www-form-urlencoded по адресу https://payment.webpay.by/?wt={token} — для реальной среды или по адресу https://securesandbox.webpay.by/?wt={token} — для тестовой среды, где:

  • token — значение поля token, которое пришло в ответе от aсs в шаге 2.

Тело запроса должно содержать параметры, полученные от acs на шаге 2 (может быть несколько параметров, например, CRes и threeDSSessionData).

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

POST /?wt=92a2b7aefffcf9d7291e2a068bb0346c%3D526b5a5252557073596e497264314e4c56336c6c64475253556e4e7556474e3565574572596d523156545a48616d6377544752574f486432556d7830526e686155486c495a456f774d484e506432396a5557706859772c2c HTTP/1.1
Host: payment.webpay.by
Content-Type: application/x-www-form-urlencoded
Content-Length: 324

cres=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjcyMDYxNmItYjJkNy00MjE2LTljM2EtNzcyNzZjN2Q0OWM3IiwKICAibWVzc2FnZVR5cGUiIDogIkNSZXMiLAogICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICJhY3NUcmFuc0lEIiA6ICJiYTA4NjMxZi0yZjRkLTQ2MDgtODU3Yi1jMGM5ZmVjYWQ5NDEiLAogICJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIiA6ICJZIiwKICAidHJhbnNTdGF0dXMiIDogIlkiCn0

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

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

{
  "time": "2023.07.14 11:59:03",
  "orderNumber": "ORDER-d213e35",
  "orderNote": "",
  "invoiceNumber": "181060384",
  "transaction": "909062398",
  "authorizationCode": "KDNVSQ",
  "rrn": "319511005218",
  "trimPan": "220073xxxxxx8210",
  "payee": "ООО «ВЕБ ПЭЙ»",
  "customerName": "",
  "customerAddress": "",
  "serviceDate": "",
  "pdfUrl": "https://billing.webpay.by/?kjBNq4f1l1qbIoUeyp7Zpjo6yFeuB%2BPKpl6r1PEBFyzKalsJb84uIMYjM3lYKbn3s1pNEnXRZLqTRKSvomJUVHOd9lnQ3y0zleHOx4VN1ab%2FWQ%3D%3D",
  "language": "ru",
  "items": [
    {
      "name": "test",
      "quantity": 1,
      "price": "0.10",
      "totalAmount": "0.10",
      "commission": "0.00"
    }
  ],
  "amount": "0.10",
  "currency": "BYN"
}

Рекуррентный (Credential on File) платеж для мерчантов PCI DSS

Для совершения рекуррентных (CoF) платежей мерчанту PCI DSS следует ознакомиться со стандартной работой с рекуррентными платежами и внести минимальные изменения в запросы.

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

При формировании инициирующего платежа для мерчантов PCI DSS изменяется алгоритм формирования подписи заказа путем добавления поля wsb_encrypted_data (с правилом формирования данного поля можно ознакомиться здесь) перед параметром SecretKey. Электронная подпись wsb_signature должна быть сформирована согласно следующему правилу из значений следующих полей:

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

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

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

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

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

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

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

Оплата по ранее привязанным в другом PSP картам

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

  1. Сформировать запрос на проведение рекуррентного платежа
  2. В поле wsb_encrypted_data (с правилом формирования данного поля можно ознакомиться здесь) передавать данные платежной карточки Вашего плательщика, за исключением поля cc_cvv. Поля cc_pan, cc_exp, cc_name содержат данные держателя карты, а поле cc_cvv оставляется пустым.

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

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

B2C/W2C (Банк БелВЭБ)

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример кода

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

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

Описание полей таблицы senderData
Tag Type Description Value Format
C1 T First Name ans ...35
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

ans — alphabetic, numeric and special characters

Описание полей таблицы receiverData
Tag Type Description Value Format
C1 T First Name ans ...35
C3 T Last Name ans ...35

ans — alphabetic, numeric and special characters

Пример кода

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

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

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

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

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

Пример кода

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

P2P (Банк БелВЭБ)

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

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

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

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

Система WEBPAY предусматривает два способа формирования вывода денежных средств с использованием типа P2P:

  1. Вывод без использования токенизации карты:
  2. Вывод с использованием токенизации карты.

Формирование стандартного POST-запроса

Для осуществления P2P вывода денежных средств необходимо сформировать стандартный POST-запрос (раздел Формирование заказа для оплаты), в который дополнительно передаются следующие поля:

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

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

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

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

Важно!

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

Важно!

При формировании запроса P2P на выплату денежных средств (в поле wsb_output_via_corpocard передано значение true) поля wsb_invoice_item_name, wsb_invoice_item_quantity, wsb_invoice_item_price являются необязательными.

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

<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_storeid" value="240869199">
  <input type="hidden" name="wsb_order_num" value="ORDER-1234567822223">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="dfdasf3i232m13ijdsmcvm">
  <input type="hidden" name="wsb_output_via_corpocard" value="true">
  <input type="hidden" name="wsb_encrypted_data" value="bhch48Wu4Esi3Y7jVq/d+0A3VqdzBsRvobhDxLrWsQyl6+ogVSIxMxM8S/4EVyGeNXO6VR/FA1UnvzLvehhDWMeEZFv04SAktt5BTABXcjgWm7ZJ3tiXEv1c1UuMDCk88xhDDyfSaPaCJMxnQhA3Wo9qfXhFebDwtIUljP7MCs41woxAQx8v9f8fm3FHS2+RnrN+HRAhgM34hR3OwYx/1llgu0L78++Ovrf6ZjQqYArv8YoV8E9y5cWrGYdUp2ogmfOkvGX/wI+wZ0FoAIuwAWiUknca7zClbwfgshw4wV4p0w==">
  <input type="hidden" name="wsb_return_url" value="https://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="https://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="https://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_total" value="1.00">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="04c0129511a4df53e74676f0cb18ac2a1d34a8e2">
  <input type="submit" value="Выплатить">
</form>

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

Вывод P2P на карту

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

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

P2P (МТБанк)

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

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

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

Система WEBPAY предусматривает два способа формирования вывода денежных средств с использованием типа P2P:

  1. JSON API.
  2. Формирование стандартного POST-запроса.

Формирование стандартного POST-запроса

Важно!

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

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

В ответе будет передан transaction_id для осуществления в дальнейшем по нему вывода.

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

Для осуществления P2P вывода денежных средств необходимо сформировать стандартный POST-запрос (раздел Формирование заказа для оплаты) на адрес https://securesandbox.webpay.by/output/mtb для тестовой среды или https://payment.webpay.by/output/mtb для реальной среды, в который дополнительно передаются следующие поля:

Название поля Обязательное поле Описание
wsb_token_p2p Да

Значение данного поля соответствует значению поля transaction_id, переданного в нотификаторе после осуществленной операции ввода и привязки карты.

wsb_output_via_corpocard_mtb Да

Поле всегда содержит значение true и указывает на осуществление вывода денежных средств.

wsb_customer_id Да Уникальный идентификатор пользователя в Магазине.

Важно!

При формировании запроса P2P на выплату денежных средств поля wsb_invoice_item_name, wsb_invoice_item_quantity, wsb_invoice_item_price являются необязательными.

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

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

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

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

<form action="https://securesandbox.webpay.by/output/mtb" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_storeid" value="240869199">
  <input type="hidden" name="wsb_order_num" value="ORDER-1234567822223">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="dfdasf3i232m13ijdsmcvm">
  <input type="hidden" name="wsb_token_p2p" value="164941648452655">
  <input type="hidden" name="wsb_output_via_corpocard_mtb" value="true">
  <input type="hidden" name="wsb_customer_id" value="164968">
  <input type="hidden" name="wsb_return_url" value="https://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="https://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="https://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_total" value="1.00">
  <!-- Значение SecretKey в примере равно 1 -->
  <input type="hidden" name="wsb_signature" value="c6e16f9fa0837eff0585b1046431a134839fbc14">
  <input type="submit" value="Выплатить">
</form>

API

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

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

Важно!

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

Важно!

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

Серверное SDK

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

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

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

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

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

{url_платежного_модуля}/reports/merchants/{reportType}?email={email}&reportFormat={reportFormat}&startDate={startDate}&endDate={endDate}&startFinancialCompletionDate={startFinancialCompletionDate}&endFinancialCompletionDate={endFinancialCompletionDate}&startReversalDate={startReversalDate}&endReversalDate={endReversalDate}

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

Пример:

https://sander.webpay.by/reports/merchants/RECONCILIATION_REPORT?email=test@webpay.by&reportFormat=JSON&startDate=2019-12-20&endDate=2019-12-30&startFinancialCompletionDate=2019-12-20&endFinancialCompletionDate=2019-12-30&startReversalDate=2019-10-01&endReversalDate=2019-12-30

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

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

Важно!

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

Пример кода

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


// Запрос, отправляемый POST-методом
{
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2019-12-20",
  "endDate": "2019-12-30",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "JSON",
  "startFinancialCompletionDate" : "2019-12-20",
  "endFinancialCompletionDate" : "2019-12-30",
  "startReversalDate" : "2019-12-20",
  "endReversalDate" : "2019-12-30"
}

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

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

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

IDCheck — система управления средствами удаленной идентификации и верификации пользователей, единовременной фото- и видео-фиксации, обработки и проверки цифровой подлинности документов и изображений, которая позволяет:

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

Ознакомиться с технической документацией и способами интеграции можно здесь.