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 or SOAP method (in UTF-8 coding).
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 | Format of the results output. It is not mandatory in case of SOAP request format and mandatory for POST |
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 |
Payer's e-mail | |
orderdate | Date of order |
orderstate | Order status |
errorcode4 | Error code |
packetdate | Request issue date |
signature | Signature |
checkvalue | uppercase(md5(uppercase(md5(SALT) + md5(Х)))), where SALT – secret word; Х – is string generated according to determined rules. |
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 |
errorcode4 | Error code |
chequeItems1 | The string with the cheque items in the JSON format according to the section "Payment with cheque". |
extrrn2 | Unique payment number in processing |
externalrefundid3 | 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, ) |
challenge | Interaction with the cardholder (C – yes, F – no) |
eci | Electronic Commerce Indicator (5 – full authentication, 6 – authentication attempt, 7 – without authentication) |
1Order items are sent only if the "Send order positions" option is enabled in the Personal Account of IPS Assist.
2To transfer this parameter, please, contact the support service (support@assist.ru).
3The 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.
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. |
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>test payment</ordercomment> <orderamount>100.00</orderamount> <ordercurrency>RUB</ordercurrency> <firstname>Test</firstname> <lastname>Testov</lastname> <middlename>Testovich</middlename> <email>test@testpost.ru</email> <orderdate>01.01.2011 11:23:13</orderdate> <orderstate>Approved</orderstate> <packetdate>01.01.2011 12:05</packetdate> <signature></signature> <checkvalue> </checkvalue> <operation> <billnumber>511111100000001.1</billnumber> <operationtype>100</operationtype> <operationstate>Success</operationstate> <amount>100.00</amount> <currency>RUB</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>01.01.2011 11:24:13</ operationdate> <authresult>Y</authresult> <authrequired>1</authrequired> <slipno>111111</slipno></operation> <threedsdata> <version>1.0.0</version> <alphaauthresult>Y</alphaauthresult> <challenge>C</challenge> <eci>5</eci> </threedsdata> </operation> <operation> <billnumber>511111100000001.2</billnumber> <operationtype>200</operationtype> <operationstate>Success</operationstate> <amount>100.00</amount> <currency>RUB</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>01.02.2011 19:24:13</operationdate> <authresult></authresult> <authrequired></authrequired> <slipno>111111</slipno></operation> </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>331.39</orderamount>
<ordercurrency>RUB</ordercurrency>
<firstname>Test</firstname>
<lastname>Testov</lastname>
<middlename>T.</middlename>
<email>test@test.ru</email>
<orderdate>13.03.2014 13:38:24</orderdate>
<orderstate>Timeout</orderstate>
<packetdate>13.03.2014 14:55</packetdate>
<signature></signature>
<checkvalue>863F176DC699131758B2230EA93BC911</checkvalue>
</order>
<order>
<ordernumber>13032014_122</ordernumber>
<billnumber>5500069208498070</billnumber>
<testmode>1</testmode>
<ordercomment>тестовый платеж</ordercomment>
<orderamount>331.39</orderamount>
<ordercurrency>RUB</ordercurrency>
<firstname>Test</firstname>
<lastname>Testov</lastname>
<middlename>T.</middlename>
<email>test@test.ru</email>
<orderdate>13.03.2014 14:52:09</orderdate>
<orderstate>Approved</orderstate>
<packetdate>13.03.2014 14:55</packetdate>
<signature></signature>
<checkvalue>E458CD73F1AA3F994F4D97C40613FD0A</checkvalue>
<operation>
<billnumber>5500069208498070.1</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>331.39</amount>
<currency>RUB</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>13.03.2014 14:52:10</operationdate>
<authresult></authresult>
<authrequired>0</authrequired>
<slipno>111111</slipno>
<chequeitems>
{"items":[{"id":1,"price":"20.00","quantity":"3","amount":"60.00","tax":"vat10",
"product":"Sugar","name":"Sugar","fpmode":"1"},{"id":2,"price":"20.11","quantity":
"3.55","amount":"71.39","tax":"vat20","product":"Milk","name":"Milk",
"fpmode":"1"},{"id":3,"price":"200.00","quantity":"1","amount":"200.00",
"tax":"novat","product":"Butter","name":"Butter","fpmode":"3}]}
</chequeitems>
<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>331.39</amount>
<currency>RUB</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>13.03.2014 14:53:37</operationdate>
<authresult></authresult>
<authrequired>0</authrequired>
<slipno>111111</slipno>
<chequeitems>
{"items":[{"id":1,"price":"20.00","quantity":"3","amount":"60.00","tax":"vat10",
"product":"Sugar","name":"Sugar","fpmode":"1"},{"id":2,"price":"20.11","quantity":
"3.55","amount":"71.39","tax":"vat20","product":"Milk","name":"Milk",
"fpmode":"1"},{"id":3,"price":"200.00","quantity":"1","amount":"200.00",
"tax":"novat","product":"Butter","name":"Butter","fpmode":"3}]}
</chequeitems>
<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> |