Payment notification

In case of successful payment, when returning to the Internet Resource's page (using the value specified in the wsb_return_url field), the system passes the order number (value of the wsb_order_num field) and the transaction number (field wsb_tid) corresponding to the processed payment as GET request parameters.

Additionally, the system will notify the Internet Resource about the completed operation at the wsb_notify_url address (if specified in the form field) or at the "Notification URL", which can be set in the user account settings under the menu section "Settings" → "Company".

Notifications from the WEBPAY system are sent from the IP address: 178.163.225.84.

If the address for receiving notifications is specified both in the form field (wsb_notify_url) and in the user account settings, the address from the POST request specified in the wsb_notify_url field will be used.

Upon receiving a notification, the Internet Resource must respond with code 200 (HTTP/1.0 200 OK). If the Internet Resource fails to receive the notification for 30 days, the sending of requests ceases.

During development, it is necessary to account for the possibility of both receiving a payment notification (wsb_notify_url) and the customer returning to the Internet Resource's page specified in the (wsb_return_url) field.

Info

The payment session duration is 20 minutes, and the payer can attempt payment during this time. Therefore, the notification is not sent immediately after the authorization request for payment is sent to the WEBPAY system.

The notification is sent only after the WEBPAY system receives the payment result. By default, notifications are sent only for successful operations. If you require notifications for unsuccessful payments as well, we recommend contacting WEBPAY technical support.

If within 20 minutes of the Internet Resource sending the authorization request the payer has not been redirected to the wsb_return_url or wsb_cancel_return_url addresses, and/or the Internet Resource has not received a notification, it is recommended to use the GetTransactionStatus method from the API for managing card operations or contact the WEBPAY support team at support@webpay.by to clarify the operation status.

Receiving payment success notification

Two methods are available for receiving payment notifications:

Standard POST request sent from the WEBPAY system to wsb_notify_url (used by default).
Via the SOAP mechanism (can be enabled upon request).

Standard POST request to `wsb_notify_url`

After a successful payment is made, the WEBPAY system sends a specially formed POST request to the address specified in the Internet Resource's wsb_notify_url field. This request contains information about the payment. The Internet Resource must verify the received information according to the order fulfillment requirements and respond to the request with code 200 (HTTP/1.0 200 OK).

Fields contained in the request

Name	Description
`batch_timestamp`	Transaction timestamp
`currency_id`	Transaction currency
`amount`	Transaction amount
`payment_method`	Transaction method. Possible values: cc — bank card erip — ERIP apple — Apple Pay mastercard-scof-token — card tokenization via Secure Card on File Mastercard Checkout Solutions vts-token — card tokenization via Secure Card on File Visa Token Service p2p — p2p payment samsung — Samsung Pay
`order_id`	Order number in the WEBPAY system
`site_order_id`	Order number (name) assigned by the store
`transaction_id`	Transaction number
`payment_type`	Transaction type. Values `1` and `4` correspond to successful payment
`rrn`	Transaction number in the VISA/MASTERCARD/BELKART system
`wsb_signature`	Digital signature (calculated if a Secret Key is specified in the user account settings)
`action`	Processing payment code
`rc`	Internal WEBPAY operation result code
`approval`	Processing operation code
`country_alpha_three_code`	Issuing bank country code in `ISO 3166-1 alpha-3`. To include this field in the notification, contact support@webpay.by
`card`	Payer's bank payment card number in the format `123456xxxxxx7890` used for the payment. This field is included in the notification when using scenarios that require the card in the response, e.g., when working with recurring payments, PCI DSS merchants, etc. If standard integration is used but the card number is required for some reason, contact support@webpay.by to include this field in the notification
`issuer_promo_product`	Possible values from `1` to `65535`. Identifier for determining which card or card group the payer used for payment. Suitable for running promotions when paying with specific cards, e.g., those issued by a particular issuing bank. To enable this functionality, contact technical support at support@webpay.by

wsb_signature is a hex sequence and is the result of the MD5 function. The argument for the MD5 function is a text sequence obtained by simple concatenation of the following fields:

batch_timestamp
currency_id
amount
payment_method
order_id
site_order_id
transaction_id
payment_type
rrn
card — added to the signature depending on the selected workflow scenario
SecretKey

If necessary, you can manually resend the notification for an authorized transaction. To do this, find the relevant transaction in the billing account under "Payments" and click the "Send Notification" button.

Notification Example
{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 Mechanism

For the SOAP mechanism (can be enabled upon request), the WEBPAY system sends a specially formed SOAP request with the Content-Type: text/xml header to the address specified in the Internet Resource's wsb_notify_url field.

The notification structure is described in the XSD schema.

XSD Schema
<?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 is a hex sequence and is the result of the MD5 function. The argument for the MD5 function is a text sequence obtained by simple concatenation of the following fields:

batch_timestamp
currency_id
amount
payment_method
order_id
site_order_id
transaction_id
payment_type
rrn
card
SecretKey

The fields must be concatenated in the specified order.

Notification example
<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>

The Internet Resource must verify the received information according to the order fulfillment requirements and respond to the request with code 200.

XSD Schema
<?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>

The response should have the value 200 in the code field if the notification was processed successfully. If the code is not 200, the notification will be resent. The value in the codeDescription field can be arbitrary.

If necessary, you can manually resend the notification for an authorized transaction. To do this, find the relevant transaction in the user account under "Payments" and click the "Send notification" button.

Responce example
<?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>

Payment notification

Payment notification

Receiving payment success notification

Standard POST request to wsb_notify_url

SOAP Mechanism

Standard POST request to `wsb_notify_url`