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

Разработка платежного модуля осуществляется на стороне сервера подключаемого клиента и предполагает создание либо внесение изменений в исходный код скриптов дорабатываемого 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.

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

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

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

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

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

Существует механизм регулирования времени отведенного на оплату со стороны Интернет-ресурса. Для этого в авторизационном запросе необходимо передать параметр, который будет указывать, с какого времени производить отсчет отведенного для оплаты интервала (по умолчанию 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Механизм 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

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

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

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

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

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

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

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

Для проверки платежа при возврате на страницу Интернет-ресурса, указанную в поле 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-документ, содержащий следующие поля:

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

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

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

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

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

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

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

Следует также обратить внимание на то, что для тестовой среды и для реальной, суммы максимальной и минимальной транзакции различны. Для тестовой среды минимальная сумма платежа составляет 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>

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

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

В системе 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) платежей необходимо дополнительно использовать следующие поля:

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

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

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

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

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

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

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

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-запроса. Поля содержащиеся в нотификаторе представлены ниже.

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

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

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

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

При работе с 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, в зависимости от выбранного Магазином банка-эквайера, платежи принимают следующие статусы:

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

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

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

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

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

Для указания в авторизационном запросе используемого типа рассрочки необходимо дополнительно передать параметр 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 определит вводимую плательщиком карту и на ее основании оплата будет произведена по соответствующему терминалу.

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

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

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

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

Если разрешение на оплату накопленными бонусными баллами отсутствует, то страница с выбором способа платежа показана не будет и автоматически произойдет обычная оплата в 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, которые передаются в поле wsb_discount_promo_code, указаны в таблице ниже:

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

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

Тестирование скидочной программы 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 карты):

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 активной вкладкой будет выступать "Оплата ЕРИП".

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

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

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

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

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

При оплате платежей через систему АИС "Расчет" (ЕРИП) система 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:

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

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

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

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

• для определенного/неопределенного покупателя необходимо создать счет в личном кабинете WEBPAY (Создание счета из личного кабинета WEBPAY) или по API (API для создания счетов в системе 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. Описание данного алгоритма представлено далее.

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

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

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

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

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

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

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

Где:

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

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

• METHOD\n
• RESOURCE\n
• QUERY_STRING\n
• CONTENT_TYPE\n
• APIKEY\n
• NONCE\n
• PAYLOAD\n

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