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

В случае успешной оплаты, при возврате на страницу Интернет-ресурса (используется значение, указанное в поле 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).

Инфо

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

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

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

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

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

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

Стандартный POST-запрос на `wsb_notify_url`

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

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

Название	Описание
`batch_timestamp`	Время совершения транзакции
`currency_id`	Валюта транзакции
`amount`	Сумма транзакции
`payment_method`	Метод совершения транзакции. Возможные значения: cc — банковская карточка erip — ЕРИП apple — оплата Apple Pay mastercard-scof-token — токенизация карты через Secure Card on File Mastercard Checkout Solutions vts-token — токенизация карты через Secure Card on File Visa Token Service p2p — оплата p2p samsung — оплата Samsung 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
`issuer_promo_product`	Возможные значения от `1` до `65535`. Идентификатор для определения с какой карты или группы карт осуществлялась оплата плательщиком. Подходит для проведения акций при оплате определенными картами, например, выпущенными каким-то определенным банком-эмитентом. В случае необходимости подключения данного функционала необходимо обратиться в техническую поддержку по адресу 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

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

Пример нотификатора

{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 схеме.

XSD схема
<?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>

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

batch_timestamp
currency_id
amount
payment_method
order_id
site_order_id
transaction_id
payment_type
rrn
card
SecretKey

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

Пример нотификатора
<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.

xsd схема
<?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>

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

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

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

Стандартный POST-запрос на wsb_notify_url

Механизм SOAP

Стандартный POST-запрос на `wsb_notify_url`