Cancelation and Refund

Web Service Description

URL for SOAP: https://<SERVER-NAME>/cancel/wscancel.cfm, when sending parameters in JSON format, see swagger description: https://docs.assist.ru/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)

¹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.

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

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). 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.

Parameters Amount and Currency should be missed and billnumber (in short/standard format) should be passed for the full amount cancellation of order that were paid by card and by bonus points.

The service should be called individually for each payment operation (passing the extended format of billnumber) for the partial amount cancellation of order that were paid by card and by bonus points. For this, the parameter bullnumber of the wscancel call should be provided in extended mode for the corresponding card operation (5111111000965142.1 for example) in one call, and parameter Amount should be set to the necessary amount that should be refunded to the card. In another call the payment by bonus points can be partly canceled. For this, the billnumber should be provided in extended mode for the corresponding bonus points payment operation (5111111000965142.2 for example). Amount should be set to the quantity of points that shoulbe refunded on the customer bonus account.

If during the payment some bonus points accruals were done then the related quantity of bonus points canceled automatically (you don't need to the cancel accrual operation of the order). Amount of the bonus points accruals cancellation is calculated automatically for both cancel operations (card, and points refunds) individually.

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.

If enterprise uses cheque in the order payment then only cheque items cancellation is possible. The canceled cheque items should be passed in ChequeItem property. The cheque usage in the orders is described in details in the section Payment With Cheque.

Interface for HTTP POST - format

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

<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

<?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> RUB </currency> 
<meantypename>VISA</meantypename> 
<meannumber>411111****1111</meannumber> 
<lastname> Testov </lastname> 
<firstname> Test </firstname> 
<middlename> Testovich </middlename> 
<issuebank> BANK </issuebank> 
<email> test@testpost.ru </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> RUB </ordercurrency> 
<slipno>111111</slipno>
<packetdate> 01.01.2011 12:36:31 </packetdate> 
<signature></signature> 
</order> </orders> </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>

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:

<?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="">RUB</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.

An example of request result of payment cancellation or refund:

<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>RUB</ordercurrency>
            <rate>1</rate>
            <orderdate>14.09.2012 09:29:38</orderdate>
            <orderstate>Canceled</orderstate>
            <customer>
                <firstname>Testov</firstname>
                <lastname>Test</lastname>
                <middlename>T</middlename>
                <email>test@test.ru</email>
            </customer>
            <operation>
                <billnumber>500000210031071.3</billnumber>
                <operationtype>300</operationtype>
                <operationstate>Success</operationstate>
                <amount>4010.00</amount>
                <currency>RUB</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>14.09.2012 09:33:51</operationdate>
                <slipno>112211</slipno>
            </operation>
        </order>
        <packetdate>14.09.2012 09:33:57</packetdate>
        <signature>kA0DAAIRzfHw5YyCW...bQnThrGPVGBK6gh9bxUl1w==</signature>
    </ws:WSCancelResponseParams></soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
    <soapenv:Body><ws:WSCancelResponseParams>
        <order>
            <billnumber>5774168101038147</billnumber>
            <ordernumber>14092012-002</ordernumber>
            <testmode>0</testmode>
            <ordercomment>test payment</ordercomment>
            <orderamount>4010.00</orderamount>
            <ordercurrency>RUB</ordercurrency>
            <rate>1</rate>
            <orderdate>14.09.2012 09:29:38</orderdate>
            <orderstate>Canceled</orderstate>
            <customer>
                <firstname>Ivan</firstname>
                <lastname>Ivanov</lastname>
                <middlename>Ivanovich</middlename>
                <email>iivanov@mail.test</email>
            </customer>
            <operation>
                <billnumber>5774168101038147.3</billnumber>
                <operationtype>300</operationtype>
                <operationstate>Success</operationstate>
                <amount>4010.00</amount>
                <currency>RUB</currency>
                <ipaddress>10.10.10.10</ipaddress>
                <meantype_id>1</meantype_id>
                <meansubtype></meansubtype>
                <meannumber>427683****3018</meannumber>
                <cardholder>TEST</cardholder>
                <cardexpirationdate>12/20</cardexpirationdate>
                <issuebank>SBERBANK OF RUSSIA</issuebank>
                <bankcountry>Russia</bankcountry>
                <responsecode>AS000</responsecode>
                <message></message>
                <customermessage></customermessage>
                <recommendation></recommendation>
                <approvalcode>X34209</approvalcode>
                <protocoltypename></protocoltypename>
                <processingname>UCS</processingname>
                <operationdate>14.09.2012 09:33:51</operationdate>
                <slipno></slipno>
            </operation>
            <operation>
                <billnumber>5774168101038147.4</billnumber>
                <operationtype>600</operationtype>
                <operationstate>Success</operationstate>
                <amount>401.00</amount>
                <currency>RUB</currency>
                <ipaddress>10.10.10.10</ipaddress>
                <meantype_id>12</meantype_id>
                <meansubtype></meansubtype>
                <meannumber>427683****3018</meannumber>
                <cardholder>TEST</cardholder>
                <cardexpirationdate>12/20</cardexpirationdate>
                <issuebank>SBERBANK OF RUSSIA</issuebank>
                <bankcountry>Россия</bankcountry>
                <responsecode>AS000</responsecode>
                <message></message>
                <customermessage></customermessage>
                <recommendation></recommendation>
                <approvalcode></approvalcode>                    
                <protocoltypename></protocoltypename>
                <processingname>SberLo</processingname>
                <operationdate>14.09.2012 09:33:51</operationdate>
                <slipno></slipno>
            </operation>
        </order>
        <packetdate>14.09.2012 09:33:57</packetdate>
        <signature>kA0DAAIRzfHw5YyCW...bQnThrGPVGBK6gh9bxUl1w==</signature>
    </ws:WSCancelResponseParams></soapenv:Body>
</soapenv:Envelope>

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

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

Back on top

Content

Space Tools

Web Service Description