Page History

Versions Compared

Old Version 1

changes.mady.by.user Oksana Chizhikova

Saved on Dec 07, 2022

compared with

New Version Current

changes.mady.by.user Oksana Chizhikova

Saved on May 29, 2024

Key

This line was added.
This line was removed.
Formatting was changed.

Web Service Description

URL for SOAP: https://<SERVER-NAME>/cancel/wscancel.cfm, when sending parameters in JSON format, see swagger description: https://docs.belassist.by/swagger/.

List of request parameters:

Parameter	Mandatory field	Adopted values	Default value	Description
Billnumber	Yes	15 or 16 digits; extended format		Unique number of payment corresponding to the order number in IPS Assist; extended payment number can be passed only if the cheque is not transferred in the order.
Merchant_ID	Yes	Number		The enterprise identifier in IPS Assist
Login	Yes	8-20 character string		Login (Latin letters, digits and symbol _)
Password	Yes	8-20 character string		Password (Latin letters and digits)
Amount	No¹	Number, 15 digits, two digits after the delimiter (delimiter '.')	Authorization amount	Refund amount
Currency	No¹	3 characters	Authorization currency code	Cancellation and refund currency code. Only the authorization currency code can be used
CancelReason	No	1 – Declined by shop 2 – Declined by customer 3 – Fraud operation	2	Reason of cancellation or refund
Language	No	RU – Russian EN – English	RU	Language of the results output
ClientIP	No			IP-address of the operator performing the cancellation/refund
Format	No	1 – CSV 3 – XML 4 – SOAP 5 - JSON	4	Format of the results output. If the request is sent in SOAP or in JSON format, then the response will also be in SOAP or in JSON respectively, in other cases, in accordance with the passed format value.
Externalrefundid	No²	10 to 100 characters (allowed characters are [A-Za-z0-9\-_]		External refund ID (unique value within one order).
Customer	No³	Data structure		Customer options

Anchor

	1
	1

¹The parameters Amount and Currency can be available or missing in the request only simultaneously. If the above parameters are missing, the full amount cancelation operation will be performed.

Anchor

	2
	2

²The parameter is used only for JSON and SOAP formats.

Anchor

	3
	3

³The parameter is required only for canceling payments by ERIP.

The following customer (recipient) parameters are passed in the structure:

Parameter	Mandatory field	Adopted values	Description
bankcode	Yes	int	Suppositive number of the settlement participant assigned to the banks of the national payment system of the Republic of Belarus (beneficiary's bank).
accountnumber	Yes	string(50)	The number of the personal account of the ERIP system customer.
firstname	No	string(29)	The name of the ERIP system customer.
lastname	No	string(29)	The surname of the ERIP system customer.
secondname	No	string(29)	The second name of the ERIP system customer.

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

The parameter billnumber can be passed either in ordinary format (when there was only one successful payment on this order) or in extended format in the confirmation. While using the extended format it is required to provide the exact number of the successful authorization operation (in some cases it can be not a first operation in the order, 5111111000965142.2 for example).

Warning
Attention! Extended payment number can be passed only if the cheque is not transferred in the order.

Cancel or refund is successful when the returned response code of cancel operation is AS000 (operation completed successfully), both codes firstcode and secondcode are equal to 0, status of the order is Canceled or PartialCanceled.

Unsuccessful cancel operation has the returned response code set to values AS100-AS998. If a request for a refund or cancel can not be processed then the query will return non-zero values in firstcode and secondcode.

Type of transaction (on-line cancellation, refund, financial transaction cancellation, partial cancellation) will be determined by IPS Assist automatically depending on the amount (full or partial cancellation), processing, type of card, availability of a financial transaction for parental authorization, and refund reason.

Interface for HTTP POST - format

An example of HTTP POST request for the payment cancellation by bankcard:

Code Block

language	xml

<FORM ACTION="https://<SERVER-NAME>/cancel/wscancel.cfm" method="POST">
<INPUT TYPE="hidden" NAME="BillNumber" VALUE="511111100000001">
<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="Amount" VALUE="amount">
<INPUT TYPE="hidden" NAME="Currency" VALUE="Currency">
<INPUT TYPE="hidden" NAME="ClientIP" VALUE="IP-address">
<INPUT TYPE="hidden" NAME="Language" VALUE="Language of result output">
<INPUT TYPE="hidden" NAME="Format" VALUE="Result output format">
<INPUT TYPE="Submit"></FORM>

List of response parameters:

Parameter	Value
ordernumber	Order number
responsecode	Response code
recommendation	Recommendations
message	Message
ordercomment	Comment
orderdate	Date of order
amount	Operation amount
currency	Currency of operation
meantypename	Type of payment means
meannumber	Number of payment means
lastname	Payer's last name
firstname	Payer's first name
middlename	Payer's middle name
issuebank	Name of issue bank
Email	Payer's e-mail
bankcountry	Country of issue bank
rate	Currency rate
approvalcode	Authorization code
meansubtype	Payment means subtype
cardholder	Payment means holder
cardexpirationdate	Card expired date
ipaddress	Payer's IP-address
protocolname	Protocol
testmode	Test mode
customermessage	Result message for a customer
orderstate	Order status
processingname	Processing
operationtype	Operation type
billnumber	Extended format of Billnumber
orderamount	Original amount of operation
ordercurrency	Original currency of operation
slipno	Financial transaction identifier
packetdate	Request issue date
signature	Signature. Signature. It is generated according to the following algorithm: 1) A combined string is created from the parameters (in their string representation, in the format as they are passed in the response): billnumber, ordernumber, responsecode, orderamount, ordercurrency, meannumber, approvalcode, orderstate, packetdate (without delimiters). 2) The received string is signed with IPS Assist private key. 3) The resulting byte sequence is encoded in BASE64.

An example of request result of payment cancellation or refund in XML format

Code Block

language	xml

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<!DOCTYPE result [
<!ATTLIST result
          firstcode CDATA #REQUIRED
          secondcode CDATA #REQUIRED
          count CDATA #REQUIRED>
<!ELEMENT result (orders?)>
<!ELEMENT orders (order)>
<!ELEMENT order (ordernumber?, responsecode?, recommendation?, message?, ordercomment?, orderdate?, amount?, currency?, meantypename?, meannumber?, lastname?, firstname?, middlename?, issuebank?, email?, bankcountry?, rate?, approvalcode?, meansubtype?, cardholder?, cardexpirationdate?, ipaddress?, protocoltypename?, testmode?, customermessage?,  orderstate?, processingname?, operationtype?, billnumber?, orderamount?, ordercurrency?, slipno?, packetdate?, signature?, pareq?, acsurl?)>
<!ELEMENT ordernumber (#PCDATA)>
<!ELEMENT responsecode (#PCDATA)>
<!ELEMENT recommendation (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ELEMENT ordercomment (#PCDATA)>
<!ELEMENT orderdate (#PCDATA)>
<!ELEMENT amount (#PCDATA)>
<!ELEMENT currency (#PCDATA)>
<!ELEMENT meantypename (#PCDATA)>
<!ELEMENT meannumber (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!ELEMENT issuebank (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT bankcountry (#PCDATA)>
<!ELEMENT rate (#PCDATA)>
<!ELEMENT approvalcode (#PCDATA)>
<!ELEMENT meansubtype (#PCDATA)>
<!ELEMENT cardholder (#PCDATA)>
<!ELEMENT cardexpirationdate (#PCDATA)>
<!ELEMENT ipaddress (#PCDATA)>
<!ELEMENT protocoltypename (#PCDATA)>
<!ELEMENT testmode (#PCDATA)>
<!ELEMENT customermessage (#PCDATA)>
<!ELEMENT orderstate (#PCDATA)>
<!ELEMENT processingname (#PCDATA)>
<!ELEMENT operationtype (#PCDATA)>
<!ELEMENT billnumber (#PCDATA)>
<!ELEMENT orderamount (#PCDATA)>
<!ELEMENT ordercurrency (#PCDATA)>
<!ELEMENT slipno (#PCDATA)>
<!ELEMENT packetdate (#PCDATA)>
<!ELEMENT signature (#PCDATA)>
<!ELEMENT pareq (#PCDATA)>
<!ELEMENT acsurl (#PCDATA)>]>
 <result firstcode="0" secondcode="0" count="1">
<orders> <order>
<ordernumber> 0001-01 </ordernumber>
<responsecode> AS000 </responsecode>
<recommendation></recommendation>
<message> Completed. </message>
<ordercomment>test payment</ordercomment>
<orderdate> 01.01.2011 10:51:53 </orderdate>
<amount> 100.00 </amount>
<currency> BYN </currency>
<meantypename>VISA</meantypename>
<meannumber>411111****1111</meannumber>
<lastname> Testov </lastname>
<firstname> Test </firstname>
<middlename> Testovich </middlename>
<issuebank> BANK </issuebank>
<email> test@testpost.by </email>
<bankcountry> Russia </bankcountry>
<rate>1</rate>
<approvalcode> F39530 </approvalcode>
<meansubtype> Corporate Purchasing Card </meansubtype>
<cardholder> TEST </cardholder>
<cardexpirationdate>12/20</cardexpirationdate>
<ipaddress> 10.23.23.23 </ipaddress>
<protocoltypename></protocoltypename>
<testmode> 1 </testmode>
<customermessage> Completed. </customermessage>
<orderstate> Canceled </orderstate>
<processingname> Name </processingname>
<operationtype> 300 </operationtype>
<billnumber>511111100000001.2</billnumber>
<orderamount> 100.00 </orderamount>
<ordercurrency> BYN </ordercurrency>
<slipno>111111</slipno>
<packetdate> 01.01.2011 12:36:31 </packetdate>
<signature></signature>
</order> </orders> </result>

Warning
The field <slipno> is used only for processing Multicard. The values of this parameter in result requests are described in the References.

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

Code Block

language	xml

<?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 Table Codes of automated interfaces. Tables Order State, Operation Type, Response Code and 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 *.

Web-service for SOAP-format (wscancel)

Web-service description for SOAP format can be found on page:

https://<SERVER-NAME>/cancel/wscancel.wsdl

An example of request for the payment cancellation by bankcard:

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Header/>
    <Body>
        <WSCancelRequestParams>
            <merchant_id xmlns="">423422</merchant_id>
            <billnumber xsi:type="xsd:string" xmlns="">500000210031071.1</billnumber>
            <login xsi:type="xsd:string" xmlns="">login</login>
            <password xsi:type="xsd:string" xmlns="">password</password>
            <amount xsi:type="xsd:string" xmlns="">23.23</amount>
   <currency xsi:type="xsd:string" xmlns="">BYN</currency>
        </WSCancelRequestParams>
    </Body>
</Envelope>

List of response parameters:

Parameter	Value
*Order parameters (section <order>)*
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
rate	Currency rate
orderdate	Date of order (GMT)
orderstate	Order status
*Payer data* (*section* <*customer*>)
firstname	Payer's first name
lastname	Payer's last name
middlename	Payer's middle name
email	Payer's e-mail
*Operation parameters (repeated section <operation>)*
billnumber	Extended format of Billnumber: billnumber.<operation number>
operationtype	Operation type
operationstate	Operation status
amount	Operation amount
currency	Currency of operation
ipaddress	Payer's IP-address
meantype_id	Payment means ID
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	Recommendations
approvalcode	Authorization code
protocoltypename	Protocol
processingname	Processing
operationdate	Operation date and time (GMT)
slipno	Financial transaction identifier
Data packet properties (in section <result>)
packetdate	Request issue date (GMT)
signature	Signature. Signature. It is generated according to the following algorithm: 1) A combined string is created from the parameters (in their string representation, in the format as they are passed in the response): billnumber, ordernumber, responsecode, orderamount, ordercurrency, meannumber, approvalcode, orderstate, packetdate (without delimiters). 2) The received string is signed with IPS Assist private key. 3) The resulting byte sequence is encoded in BASE64.

Warning
The field <slipno> is used only for processing Multicard. The values of this parameter in result requests are described in the References.

An example of request result of payment cancellation or refund:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
    <soapenv:Body><ws:WSCancelResponseParams>
        <order>
            <billnumber>500000210031071</billnumber>
            <ordernumber>14092012-002</ordernumber>
            <testmode>0</testmode>
            <ordercomment>test payment</ordercomment>
            <orderamount>4010.00</orderamount>
            <ordercurrency>BYN</ordercurrency>
            <rate>1</rate>
            <orderdate>06.07.2016 09:29:38</orderdate>
            <orderstate>Canceled</orderstate>
            <customer>
                <firstname>Testov</firstname>
                <lastname>Test</lastname>
                <middlename>T</middlename>
                <email>test@test.by</email>
            </customer>
            <operation>
                <billnumber>500000210031071.3</billnumber>
                <operationtype>300</operationtype>
                <operationstate>Success</operationstate>
                <amount>4010.00</amount>
                <currency>BYN</currency>
                <ipaddress>10.10.10.10</ipaddress>
                <meantype_id>1</meantype_id>
                <meansubtype></meansubtype>
                <meannumber>411111****1111</meannumber>
                <cardholder>TEST</cardholder>
                <cardexpirationdate>12/20</cardexpirationdate>
                <issuebank>Bank T</issuebank>
                <bankcountry>Россия</bankcountry>
                <responsecode>AS000</responsecode>
                <message></message>
                <customermessage>Success</customermessage>
                <recommendation></recommendation>
                <approvalcode>X34209</approvalcode>
                <protocoltypename></protocoltypename>
                <processingname>Fake</processingname>
                <operationdate>06.07.2016 09:33:51</operationdate>
                 <slipno></slipno>
            </operation>
        </order>
        <packetdate>06.07.2016 09:33:57</packetdate>
        <signature>kA0DAAIRzfHw5YyCW...bQnThrGPVGBK6gh9bxUl1w==</signature>
    </ws:WSCancelResponseParams></soapenv:Body>
</soapenv:Envelope>

An example of request result, returning the error (wrong amount):

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><soapenv:Fault><faultcode>soapenv:Server.generalException</faultcode><faultstring/><detail><ns:WSException xmlns:ns="http://www.paysecure.ru/ws/">
<firstcode>5</firstcode><secondcode>108</secondcode>
</ns:WSException></detail>
</soapenv:Fault></soapenv:Body></soapenv:Envelope>

An example of a request to cancel a payment using the ERIP system:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
   <soapenv:Body>
        <ws:WSCancelRequestParams>
            <billnumber>5481287255582736</billnumber>
            <merchant_id>481287</merchant_id>
            <login>login</login>
            <password>password</password>
            <amount>50</amount>
   <currency>BYN</currency>
   <bankcode>444</bankcode>
   <accountnumber>BY11AAAA1234123412341234123445</accountnumber>
   <firstname>Ivan</firstname>
   <lastname>Ivanov</lastname>
 
        </WSCancelRequestParams>
    </soapenv:Body>
</soapenv:Envelope>

Note
Cancellation is possible only after a daily reconciliation with ERIP system. Attempting to cancel before reconciliation results in "15 - Forbidden operation" and "308 - Cancellation operation" errors.

An example of the result of a request sent before reconciliation:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server.generalException</faultcode>
         <faultstring/>
         <detail>
            <ns:WSException xmlns:ns="http://www.paysecure.ru/ws/">
                <firstcode>15</firstcode>
                <secondcode>308</secondcode>
            </ns:WSException>
          </detail>
      </soapenv:Fault>
</soapenv:Envelope>

Back on top

Content

Space Tools

Versions Compared

Old Version 1

New Version Current

Key

Web Service Description