www.belassist.by

If the merchant requires not only the information about the order status (approved, cancelled, payment confirmation in process), but also a detailed information about the operations (payment, payment approval, return or cancellation) executed with regards to this order, the merchant can use Web service to receive the results of the operations under a given order number.

To receive the payment result by order number, send a request to IPS Assist server via HTTP POST, SOAP method (in UTF-8 coding) or in JSON format (swagger description: https://docs.belassist.by/swagger/).

The request URL for receiving the payment result with a list of operations within the order:

https://<SERVER-NAME>/orderresult/orderresult.cfm.

The order search using Web service can be performed only for the specified time period. The default sampling end date is taken to be the current date, while the default sampling start date is the current date, minus three days.

List of request parameters

Parameter

Mandatory field

Adopted values

Default value

Description

Ordernumber

Yes

String, 128  characters


Order number

Merchant_ID

Yes

Number


The enterprise identifier in IPS Assist

Login

Yes

8 - 20 characters


Login (Latin letters, digits and symbol _)

Password

Yes

8 - 20 characters


Password (Latin letters and digits)

StartYear

No

Year in "2011" format

Minus three days from the current date

Sampling start date (GMT)

StartMonth

No

1 - 12

Minus three days from the current date

StartDay

No

1 - 31

Minus three days from the current date

StartHour

No

0 - 23

Minus three days from the current date

StartMin

No

0 - 59

Minus three days from the current date

EndYear

No

Year in "2011" format

Current year

Sampling end date (GMT)

EndMonth

No

1 - 12

Current month

EndDay

No

1 - 31

Current day

EndHour

No

0 - 23

Current hour

EndMin

No

0 - 59

Current minute

Language

No

RU

EN

EN

Language of the results output

Format

Yes/No

3 - XML
4 - SOAP
5 - JSON

3

Format of the results output. Passed only for a request in POST format (by default, the response will be returned in XML format). For other formats, the response is returned in the same format in which the request was made.

All request parameters are automatically validated. The validation rules are given in the table "The validation rules for input parameters".

Request example for HTTP POST format:

<FORM ACTION="https://<SERVER-NAME>/orderresult/orderresult.cfm" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="Ordernumber" VALUE="1001-01">
<INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Your Merchant_ID">
<INPUT TYPE="HIDDEN" NAME="Login" VALUE="Your login">
<INPUT TYPE="HIDDEN" NAME="Password" VALUE="Your password">
<INPUT TYPE="HIDDEN" NAME="Startyear" VALUE="2011">
<INPUT TYPE="HIDDEN" NAME="Startmonth" VALUE="04">
<INPUT TYPE="HIDDEN" NAME="Startday" VALUE="01">
<INPUT TYPE="HIDDEN" NAME="Starthour" VALUE="00">
<INPUT TYPE="HIDDEN" NAME="Startmin" VALUE="00">
<INPUT TYPE="HIDDEN" NAME="Endyear" VALUE="2011">
<INPUT TYPE="HIDDEN" NAME="Endmonth" VALUE="04">
<INPUT TYPE="HIDDEN" NAME="Endday" VALUE="02">
<INPUT TYPE="HIDDEN" NAME="Endhour" VALUE="00">
<INPUT TYPE="HIDDEN" NAME="Endmin" VALUE="00">
<INPUT TYPE="HIDDEN" NAME="Format" VALUE="3">
<INPUT TYPE="HIDDEN" NAME="Language" VALUE="EN">
<INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Execute">
</FORM>

List of response parameters:

Parameter

Value

Order parameters

billnumber

Unique order number in IPS Assist

ordernumber

Order number

testmode

Test mode

ordercomment

Comment

orderamount

Original amount of order

ordercurrency

Original currency of order

firstname

Payer's first name

lastname

Payer's last name

middlename

Payer's middle name

Email

Payer's e-mail

orderdate

Date of order

orderstate

Order status

errorcode2

Error code

packetdate

Request issue date

signature

1) For signature type MD5 - empty;

2) For PGP type - an X value, signed by IPS Assist secret key and converted into BASE64 string. 

checkvalue

1) For PGP type - empty;

2) For MD5 type - uppercase(md5(uppercase(md5(SALT) + md5(Х)))), where SALT - - secret word; Х - result of the following parameters string concatenation: merchant_id, ordernumber, orderamount, ordercurrency, orderstate (without delimiters), + means string concatenation.

Operation parameters

billnumber

Extended format of billnumber

operationtype

Operation type

operationstate

Operation status

amount

Operation amount

currency

Currency of operation

ipaddress

Payer's IP-address

clientip

Transactor's IP-address

meantype_id

Type of payment means

meansubtype

Payment means subtype

meannumber

Number of payment means

cardholder

Payment means holder

cardexpirationdate

Card expired date

issuebank

Name of issue bank

bankcountry

Country of issue bank

responsecode

Response code

message

Operation result message

customermessage

Result message for a customer

recommendation

Recommendation

approvalcode

Authorization code

protocolname

Protocol

processingname

Processing

operationdate

Operation date and time (GMT)

authresult

3Ds authorization result (Y - success, N - fail, A - Attempt, U - unknown, R - rejection, C -not completed for any reason, E - error)

authrequired

The card involvement in 3Ds check result (1 - involved, 0 - not involved, -1 - unknown, null - error appear during involvement check)

slipno

Financial transaction identifier

errorcode2

Error code

externalrefundid1

External refund ID

3DSecure parameters

version

3DSecure protocol version

alphaauthresult

3Ds authorization result (Y - success, N - fail, A - Attempt, U - unable to authenticate, R - rejection, C -not completed for any reason, E - error, I - Informational Only)

challenge

Interaction with the cardholder (C - yes, F - no, D - Decoupled Authentication)

eci

Electronic Commerce Indicator (5 - full authentication, 6 - authentication attempt, 7 - without authentication)


1The parameter is sent only if it was sent in the cancellation request using the wscancel service and the results output format is JSON or XML.


2To transfer this parameter, please, contact the support service (support@belassist.by).

The parameter is useful for orders in Declined and Timeout statuses, it helps to identify a payment error (for example, to build a report on various errors), but it does not determine the payment status. The parameter will be present in both the operation data block and the order data block. In most cases, the errorcode parameter will be 0 for an order. This does not mean that the order has been successfully paid. This means that there is no error code at the order level. The payment status is determined by the orderstate and the responsecode. In addition, an order that does not contain an operation can be created (and subsequently closed with an error).

An example of a request result for an order without an operation:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/"><soapenv:Body>
<ws:orderresultResponse><orderresult>
   <order>
      <ordernumber>2022_07_12_00_order2</ordernumber>
      <billnumber>516009019085079</billnumber>
      <testmode>0</testmode>
      <ordercomment>test payment</ordercomment>
      <orderamount>67.35</orderamount>
      <ordercurrency>BYN</ordercurrency>
      <firstname/>
      <lastname/>
      <middlename/>
      <email>test@test.by</email>
      <orderdate>31.08.2022 15:53:38</orderdate>
      <orderstate>Declined</orderstate>
      <errorcode>14</errorcode>
      <packetdate>31.08.2022 15:54</packetdate>
      <signature/>
      <checkvalue>BD01127113BB4E085C2FDCC98175466A</checkvalue>
      </order></orderresult>
</ws:orderresultResponse></soapenv:Body></soapenv:Envelope>

An example of a request result for an order with an operation:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/"><soapenv:Body>
<ws:orderresultResponse><orderresult>
   <order>
      <ordernumber>FS1662389086973_40</ordernumber>
      <billnumber>5747838257354506</billnumber>
      <testmode>0</testmode>
      <ordercomment>test payment</ordercomment>
      <orderamount>67.35</orderamount>
      <ordercurrency>BYN</ordercurrency>
      <firstname/>
      <lastname/>
      <middlename/>
      <email>test@test.by</email>
      <orderdate>31.08.2022 15:53:38</orderdate>
      <orderstate>Declined</orderstate>
      <errorcode>0</errorcode>
      <packetdate>31.08.2022 15:54</packetdate>
      <signature/>
      <checkvalue>BD01127113BB4E085C2FDCC98175466A</checkvalue>
      <operation>
         <billnumber>5747838257354506.1</billnumber>
         <operationtype>100</operationtype>
         <operationstate>Failure</operationstate>
         <orderamount>67.35</orderamount>
         <ordercurrency>BYN</ordercurrency>
         <clientip>81.211.118.98</clientip>
         <ipaddress>0.0.0.0</ipaddress>
         <meantype_id>1</meantype_id>
         <meantypename>VISA</meantypename>
         <meansubtype>Visa Platinum Business / Visa Business Enhanced (U.S.)</meansubtype>
         <meannumber>428564****0018</meannumber>
         <cardholder>N/A</cardholder>
         <cardexpirationdate>12/25</cardexpirationdate>
         <issuebank>BANK</issuebank>
         <bankcountry>Россия</bankcountry>
         <responsecode>AS100</responsecode>
         <message>Отсутствует связь с компонентом аутентификации по 3-D Secure.</message>
         <customermessage>Ошибка аутентификации по 3-D Secure.</customermessage>
         <recommendation>Попытайтесь повторить операцию через некоторое время.</recommendation>
         <approvalcode></approvalcode>
         <protocoltypename>NET</protocoltypename>
         <processingname>XXX</processingname>
         <operationdate>31.08.2022 15:53:38</operationdate>
         <authresult></authresult>
         <authrequired>0</authrequired>
         <slipno></slipno>
         <threedsdata>
            <version>2.2.0</version>
            <alphaauthresult></alphaauthresult>
            <challenge>F</challenge>
            <eci></eci>
         </threedsdata>
         <errorcode>3DS72</errorcode>
      </operation>
   </order></orderresult>
</ws:orderresultResponse></soapenv:Body></soapenv:Envelope>

Attention! Please, note that several operations can be created within one order (payment, payment confirmation, cancellation). Furthermore, there can be several payment operations within one order, if some of them were unsuccessful. The order can have the only one successful payment operation. Thus there can be several enclosed operations within one order number in the response to a request for the operations results.

Attention! The testmode value of response has to be checked. If the payment was made in test mode (testmode = 1), then the shipment of goods or providing of services for the current request is not required.

There are performance limitations when using the service.

An example of a request result in XML format:

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<!DOCTYPE result [
<!ATTLIST result
          firstcode CDATA #REQUIRED
          secondcode CDATA #REQUIRED
          count CDATA #REQUIRED>
<!ELEMENT result (order*)>
<!ELEMENT order (ordernumber?,billnumber?,testmode?,ordercomment?,orderamount?,ordercurrency?,firstname?,lastname?,middlename?,email?,orderdate?,orderstate?,packetdate?,signature?,checkvalue?,operation*)>
<!ELEMENT ordernumber (#PCDATA)>
<!ELEMENT billnumber (#PCDATA)>
<!ELEMENT testmode (#PCDATA)>
<!ELEMENT ordercomment (#PCDATA)>
<!ELEMENT orderamount (#PCDATA)>
<!ELEMENT ordercurrency (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT orderdate (#PCDATA)>
<!ELEMENT orderstate (#PCDATA)>
<!ELEMENT packetdate (#PCDATA)>
<!ELEMENT signature (#PCDATA)>
<!ELEMENT checkvalue (#PCDATA)>
<!ELEMENT operation (billnumber?,operationtype?,operationstate?,amount?,currency?,clientip?,ipaddress?,meantype_id?,meantypename?,meansubtype?,meannumber?,cardholder?,cardexpirationdate?,issuebank?,bankcountry?,responsecode?,message?,customermessage?,recommendation?,approvalcode?,protocoltypename?,processingname?,operationdate?,authresult?,authrequired?, slipno?)>
<!ELEMENT operationtype (#PCDATA)>
<!ELEMENT operationstate (#PCDATA)>
<!ELEMENT amount (#PCDATA)>
<!ELEMENT currency (#PCDATA)>
<!ELEMENT clientip (#PCDATA)>
<!ELEMENT ipaddress (#PCDATA)>
<!ELEMENT meantype_id (#PCDATA)>
<!ELEMENT meantypename (#PCDATA)>
<!ELEMENT meansubtype (#PCDATA)>
<!ELEMENT meannumber (#PCDATA)>
<!ELEMENT cardholder (#PCDATA)>
<!ELEMENT cardexpirationdate (#PCDATA)>
<!ELEMENT issuebank (#PCDATA)>
<!ELEMENT bankcountry (#PCDATA)>
<!ELEMENT responsecode (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ELEMENT customermessage (#PCDATA)>
<!ELEMENT recommendation (#PCDATA)>
<!ELEMENT approvalcode (#PCDATA)>
<!ELEMENT protocoltypename (#PCDATA)>
<!ELEMENT processingname (#PCDATA)>
<!ELEMENT operationdate (#PCDATA)>
<!ELEMENT authresult (#PCDATA)>
<!ELEMENT authrequired (#PCDATA)>
<!ELEMENT slipno (#PCDATA)>]>
<result firstcode='0' secondcode='0' count='1'>
<order>
<ordernumber>0001-01</ordernumber>
<billnumber>511111100000001</billnumber>
<testmode>1</testmode>
<ordercomment>тестовый платеж</ordercomment>
<orderamount>100.00</orderamount>
<ordercurrency>BYN</ordercurrency>
<firstname>Test</firstname>
<lastname>Testov</lastname>
<middlename>Testovich</middlename>
<email>test@testpost.by</email>
<orderdate>06.07.2016 11:23:13</orderdate>
<orderstate>Approved</orderstate>
<packetdate>06.07.2016 12:05</packetdate>
<signature></signature>
<checkvalue> </checkvalue>
<operation>
<billnumber>511111100000001.1</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>100.00</amount>
<currency>BYN</currency>
<clientip>111.23.11.23</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>1</meantype_id>
<meantypename>VISA</meantypename>
<meansubtype>Classic</meansubtype>
<meannumber>411111****1111</meannumber>
<cardholder>TEST</cardholder>
<cardexpirationdate>12/20</cardexpirationdate>
<issuebank>New Bank</issuebank>
<bankcountry>Russia</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage> </customermessage>
<recommendation></recommendation>
<approvalcode>F41412</approvalcode>
<protocoltypename>NET</protocoltypename>
<processingname>Name</processingname>
 <operationdate>06.07.2016 11:24:13</ operationdate>
<authresult>Y</authresult>
<authrequired>1</authrequired>
</slipno></operation>
<threedsdata>
  <version>1.0.0</version>
  <alphaauthresult>Y</alphaauthresult>
  <challenge>C</challenge>
  <eci>5</eci>
</threedsdata>
<operation>
<billnumber>511111100000001.2</billnumber>
<operationtype>200</operationtype>
<operationstate>Success</operationstate>
<amount>100.00</amount>
<currency>BYN</currency>
<clientip>111.23.11.23</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>1</meantype_id>
<meantypename>VISA</meantypename>
<meansubtype>Classic</meansubtype>
<meannumber>411111****1111</meannumber>
<cardholder>TEST</cardholder>
<cardexpirationdate>12/20</cardexpirationdate>
<issuebank>New Bank</issuebank>
<bankcountry>Russia</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage> </customermessage>
<recommendation></recommendation>
<approvalcode></approvalcode>
<protocoltypename></protocoltypename>
<processingname>Name</processingname>
<operationdate>06.07.2016 19:24:13</operationdate>
<authresult></authresult>
<authrequired></authrequired>
</slipno>
</operation></order></result>

An example of request result in XML format, returning the error (wrong password):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<!DOCTYPE result [...]>
<result firstcode="7" secondcode="102" count="0"></result>

For the description of the first and second codes of the automated interfaces refer to the table "Error codes". Tables "Order state", "Operation type", "Response Codes", "Currency codes" also include the descriptions of possible order statuses, types of operations, response codes and currency codes, respectively. The first 6 digits and the last 4 digits of the card number are returned as the field <meannumber> value; the other digits are hidden under symbol *.

The WEB-service description for SOAP format can be seen on page:

https://<SERVER-NAME>/orderresult/orderresult.wsdl.

If the order payment attempt was unsuccessful (card is not authorized or timeout), then the payment repeat will create a new unique number (billnumber) in the IPS Assist for the same order number of internet-shop, which will be reflected in the response to the order status request. In this case, the response to the request contains all the operations performed under this order number with all relevant unique billnumbers of IPS Assist in order of implementation of them.

An example of request result in SOAP format for the case of successful payment order at the second attempt, the first attempt was closed due to a timeout, and the second (successful) consists of two operations:

<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/"><soapenv:Body>
<ws:orderresultResponse><orderresult>
   <order>
      <ordernumber>13032014_122</ordernumber>
      <billnumber>5500069208498005</billnumber>
      <testmode>1</testmode>
      <ordercomment>тестовый платеж</ordercomment>
      <orderamount>100.00</orderamount>
      <ordercurrency>BYN</ordercurrency>
      <firstname>Test</firstname>
      <lastname>Testov</lastname>
      <middlename>T.</middlename>
      <email>test@test.by</email>
      <orderdate>06.07.2016 13:38:24</orderdate>
      <orderstate>Timeout</orderstate>
      <packetdate>06.07.2016 14:55</packetdate>
      <signature></signature>
      <checkvalue>863F176DC699131758B2230EA93BC911</checkvalue>
   </order>
   <order>
      <ordernumber>13032014_122</ordernumber>
      <billnumber>5500069208498070</billnumber>
      <testmode>1</testmode>
      <ordercomment>тестовый платеж</ordercomment>
      <orderamount>100.00</orderamount>
      <ordercurrency>BYN</ordercurrency>
      <firstname>Test</firstname>
      <lastname>Testov</lastname>
      <middlename>T.</middlename>
      <email>test@test.by</email>
      <orderdate>06.07.2016 14:52:09</orderdate>
      <orderstate>Approved</orderstate>
      <packetdate>06.07.2016 14:55</packetdate>
      <signature></signature>
      <checkvalue>E458CD73F1AA3F994F4D97C40613FD0A</checkvalue>
      <operation>
         <billnumber>5500069208498070.1</billnumber>
         <operationtype>100</operationtype>
         <operationstate>Success</operationstate>
         <amount>100.00</amount>
         <currency>BYN</currency>
         <clientip>10.10.10.10</clientip>
         <ipaddress>0.0.0.0</ipaddress>
         <meantype_id>1</meantype_id>
         <meantypename>VISA</meantypename>
         <meansubtype>Busines</meansubtype>
         <meannumber>462710****4724</meannumber>
         <cardholder>TEST</cardholder>
         <cardexpirationdate>12/20</cardexpirationdate>
         <issuebank>Bank</issuebank>
         <bankcountry>RUS</bankcountry>
         <responsecode>AS000</responsecode>
         <message> </message>
         <customermessage> </customermessage>
         <recommendation></recommendation>
         <approvalcode>X53576</approvalcode>
         <protocoltypename>NET</protocoltypename>
         <processingname>Fake</processingname>
         <operationdate>06.07.2016 14:52:10</operationdate>
         <authresult></authresult>
         <authrequired>0</authrequired>
         <slipno></slipno>
         <threedsdata>
             <version>1.0.0</version>
             <alphaauthresult>C</alphaauthresult>
             <challenge>C</challenge>
             <eci></eci>
         </threedsdata>
      </operation>
      <operation>
         <billnumber>5500069208498070.2</billnumber>
         <operationtype>200</operationtype>
         <operationstate>Success</operationstate>
         <amount>100.00</amount>
         <currency>BYN</currency>
         <clientip>10.10.10.10</clientip>
         <ipaddress>0.0.0.0</ipaddress>
         <meantype_id>1</meantype_id>
         <meantypename>VISA</meantypename>
         <meansubtype>Busines</meansubtype>
         <meannumber>462710****4724</meannumber>
         <cardholder>TEST</cardholder>
         <cardexpirationdate>12/20</cardexpirationdate>
         <issuebank>Bank</issuebank>
         <bankcountry>RUS</bankcountry>
         <responsecode>AS000</responsecode>
         <message> </message>
         <customermessage> </customermessage>
         <recommendation></recommendation>
         <approvalcode></approvalcode>
         <protocoltypename></protocoltypename>
         <processingname>Fake</processingname>
         <operationdate>06.07.2016 14:53:37</operationdate>
         <authresult></authresult>
         <authrequired>0</authrequired>
         <slipno></slipno>
         <threedsdata>
             <version>1.0.0</version>
             <alphaauthresult>Y</alphaauthresult>
             <challenge>C</challenge>
             <eci>5</eci>
         </threedsdata>
      </operation>
   </order>
</orderresult></ws:orderresultResponse></soapenv:Body></soapenv:Envelope>

Attention!

The following root certificates have to be installed on the requester side in the Trusted Root Certification Authorities Store for correct work with WEB-services via secure communication over TLS:

Before to start, check the presence of these certificates in the trust store and add tit if necessary.

Back on top