www.assist.ru

Versions Compared

Old Version 34

changes.mady.by.user Oksana Chizhikova

Saved on

compared with

New Version Current

changes.mady.by.user Oksana Chizhikova

Saved on

Key

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

Web Service Description

URL for HTTP POSTSOAP: https://<SERVER-NAME>/cancel/cancel.cfm.URL for SOAPwscancel.cfm, when sending parameters in JSON format, see swagger description: https://<SERVER-NAME>/cancel/wscancel.cfm

Expand
titleIf the merchant makes use of the "THANK YOU" Sberbank Bonus Program

If the merchant makes use of the THANK YOU from Sberbank Bonus Program and there can be two successful payment operations (by card and by points) in the order, as well as a point accrual operation, we recommend to use the web service https://<SERVER-NAME>/cancel/wscancel.cfm for cancellations.

List of request parameters:

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

No1

Number, 15 digits, two digits after the delimiter (delimiter '.'

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

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

 (with '.' delimiter)

Authorization amount

Refund amount

Currency

No*1

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 operation1

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
2 – WDDX
3 – XML
4 – SOAP
5 - JSON

4Format of input data

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

No2

10 to 100 characters (allowed characters are [A-Za-z0-9\-_]


External refund ID (unique value within one order)

Anchor
1
1


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


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

Multiexcerpt include
MultiExcerptNameval
PageWithExcerptDoc blocks

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.

Expand
titleCancellation of orders paid with bonus points

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:

Code Block
languagexml
<FORM ACTION="https://<SERVER-NAME>/cancel/wscancel.cfm" method="POST

Multiexcerpt include
MultiExcerptNameval
PageWithExcerptDoc blocks

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

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.

Expand
titleCancellation of orders paid with bonus points

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 (cancel)

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

Code Block
languagexml
<FORM ACTION="https://<SERVER-NAME>/cancel/cancel.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="AmountBillNumber" VALUE="amount511111100000001">
<INPUT TYPE="hidden" NAME="CurrencyMerchant_ID" VALUE="CurrencyYour Merchant_ID">
<INPUT TYPE="hidden" NAME="ClientIPLogin" VALUE="IP-addressYour login ">
<INPUT TYPE="hidden" NAME="LanguagePassword" VALUE="Language of result outputYour password">
<INPUT TYPE="hidden" NAME="FormatAmount" VALUE="Result output formatamount">
<INPUT TYPE="Submit"></FORM>

List of response parameters:

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

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

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

. 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
languagexml
<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<!DOCTYPE result
Code Block
languagexml
<?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>

...

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:

...

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 is calculated by following algorithm:

1. The following order parameters (in their string representations as they are provided in the replay): billnumber, ordernumber, responsecode, amount, currency, meannumber, approvalcode, orderstate, packetdate are joined in one string without any delimiter.

2. Resulting string is signed by the private RSA key of IPS Assist.

3. Resulting bit sequence is transferred as BASE64 coded string in signature field.

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.

Multiexcerpt include
MultiExcerptNameslipno
PageWithExcerptDoc blocks

An example of request result of payment cancellation or refund:

Code Block
languagexml
<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>
Expand
titleAn example of request result of payment cancellation or refund with bonus points:
Code Block
languagexml
<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):

Code Block
languagexml
<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