Page History
Web Service Description
URL for HTTP POST: https://<SERVER-NAME>/cancel/cancel.cfm.URL for SOAP: https://<SERVER-NAME>/cancel/wscancel.cfm, parameters are passed by SOAP request, or 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 | No1 | Number, 15 digits, two digits after the delimiter (delimiter '.') | Authorization amount | Refund amount | ||
Currency | No1 | 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 | Reason of cancellation or refund | ||
Language | No | RU – Russian | RU | Language of the results output | ||
ClientIP | No | IP-address of the operator performing the cancellation/refund | ||||
Format | No | 1 – CSV | Format of input data4 | 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. | ||
CustomerExternalrefundid | No2 | Data structure | Customer options | 10 to 100 characters (allowed characters are [A-Za-z0-9\-_] | External refund ID (unique value within one order). | |
Customer | No3 | Data structure | Customer options |
Anchor | ||||
---|---|---|---|---|
|
1The 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 | ||||
---|---|---|---|---|
|
2The parameter is used only for JSON and SOAP formats.
Anchor | ||||
---|---|---|---|---|
|
3The parameter is required only for canceling payments by ERIP.
...
Interface for HTTP POST - format (cancel)format
An example of HTTP POST request for the payment cancellation by bankcard:
Code Block | ||
---|---|---|
| ||
<FORM ACTION="https://<SERVER-NAME>/cancel/cancelwscancel.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> |
...
Code Block | ||
---|---|---|
| ||
<?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 | ||
---|---|---|
| ||
<?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 | ||
---|---|---|
| ||
<?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 |
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). |
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 | ||
---|---|---|
| ||
<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 | ||
---|---|---|
| ||
<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 | ||
---|---|---|
| ||
<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 | ||
---|---|---|
| ||
<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> |