The processes of bankcard authorization (payment operation) and financial transaction (financial confirmation) in the double-stage operation mode are split.
Bankcard payment operation
At the first stage, the bankcard is authorized, its credit status is verified and the funds at the client's account are blocked. If the enterprise uses the double-stage operation mode, then, besides the mandatory and additional payment parameters (as described in section "Payment request"), there is a need to send the parameter Delay=1 in the authorization request.
<FORM ACTION=" https://<SERVER-NAME>/pay/order.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Your Merchant_ID"> <INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A20042011_28"> <INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="237.40"> <INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="USD"> <INPUT TYPE="HIDDEN" NAME="Delay" VALUE="1"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="RU"> <INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@test.by"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Order payment 28-A"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_OK" VALUE="http://www.URL.by/yes"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_NO" VALUE="http://www.URL.by/no"> <INPUT TYPE="HIDDEN" NAME="CardPayment" VALUE="1"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Buy"> </FORM>
After pressing this button, a customer is automatically redirected to IPS Assist payment pages, where he/she enters his/her personal data and the card information for the payment operation to be completed. The payment operation can be both successfully completed and failed. After successfully completing the payment operation in the enterprise's double-stage operation mode, the order adopts the status Delayed in IPS Assist (Payment confirmation in process); order statuses are listed in table "OrderState field values".
At the second stage, after successfully completed payment operation, the enterprise performs the payment confirmation operation. A financial transaction is sent for processing only after the payment has been confirmed.
Attention! When the double-stage operation mode is used the customer's account is withdrawn only after the payment has been confirmed by Internet-shop.
Payment confirmation
Internet-shop can issue a financial confirmation within 2 days in Personal account, or using Web service.
To confirm the payment, send a request to IPS Assist server via HTTP POST or SOAP method (in UTF-8 coding).
The request URL for the financial confirmation transmission:
https://<SERVER-NAME>/charge/charge.cfm.
List of payment confirmation parameters for the enterprise's double-stage operation mode is given in table below:
Parameter | Mandatory field | Adopted values | Default values | Description |
Billnumber | Yes | 15 or 16 digits, extended payment number | 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 | 20 characters | Login (Latin letters, digits and symbol _) | |
Password | Yes | 30 characters | Password (Latin letters and digits) | |
Amount | No* | 15 digits, two digits after the delimiter (delimiter '.') | The amount of financial confirmation | |
Currency | No* | 3 characters | Confirmation currency code. Only the currency code of the payment operation can be used. | |
ClientIP | No | IP-address of the operator's computer that confirms the payment | ||
Language | No | RU – Russian | RU | Language of the results output |
Format | No | 1 – CSV (delimited fields) | 1 | Format of the results output. If the request is sent in JSON format, then the response will also be in JSON, in other cases, in accordance with the passed format value. |
| AutoDeposit | No | 1 – flag on 0 – flag off | Online deposit flag. It is used in cases when it is necessary to immediately unblock the unconfirmed part of the order amount. |
* The parameters Amount and Currency can be passed or missed in the request only simultaneously. If the above parameters are missing, the full amount confirmation operation will be performed.
All request parameters are automatically validated. The validation rules are given in table "The validation rules for input parameters".
The confirmation can be performed to both the complete amount and a part of the amount. It is allowed to issue a partial confirmation of amount not exceeding the amount of payment, if the payment operation by bankcard was completed through processing with correspondent settings.
Please, note that confirmation amount should be provided (using both Personal account and Web service) in the same currency which was used in the payment operation (normally, in Roubles).
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, 500000000000001.2 for example).
The payment confirmation operation is always successful, unless declined due to technical failure. In case of a technical failure, the payment should be confirmed again. The repeated payment confirmation does not result in a repeated cash withdrawal.
If the payment has been successfully confirmed, the order in IPS Assist adopts the status Approved or PartialDelayed, the Response_code is AS000.
The service description for SOAP format can be found on page:
https://<SERVER-NAME>/charge/charge.wsdl
The 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 |
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 state |
processingname | Processing |
operationtype | Operation type |
billnumber | Billnumber extended format |
orderamount | Original amount of operation |
ordercurrency | Original currency of operation |
slipno | Financial transaction identifier |
packetdate | Request issue date |
signature | The X value without delimiters, signed with IPS Assist private key, encoded in BASE64, where X - billnumber,ordernumber,responsecode,orderamount,ordercurrency,meannumber,approvalcode,orderstate,packetdate |
Examples
Request example for HTTP POST format:
<FORM ACTION="https://<SERVER-NAME>/charge/charge.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="BillNumber" VALUE="545000000000001"> <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="100"> <INPUT TYPE="HIDDEN" NAME="Currency" VALUE="BYN"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="0"> <INPUT TYPE="HIDDEN" NAME="Format" VALUE="3"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Execute"> </FORM>
The result of payment financial confirmation request in CSV format:
ordernumber: 0001-01 responsecode: AS000 recommendation: message: Completed. ordercomment: test payment orderdate: 01.01.2011 09:00:05 amount: 100.00 currency: BYN meantypename: VISA meannumber: 411111****1111 lastname: Testov firstname: Test middlename: Testovich issuebank: BANK email: test@testpost.by bankcountry: Russia rate: 1 approvalcode: meansubtype: Corporate Purchasing Card cardholder: TEST cardexpirationdate:12/20 ipaddress: 111.23.11.23 protocoltypename: testmode: 1 customermessage: Completed. orderstate: Approved processingname: Name operationtype: 200 billnumber: 511111100000001.2 orderamount: 100.00 ordercurrency: RUB slipno: 111111 packetdate: 01.01.2011 09:01:47 signature:
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> 06.07.2016 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> </approvalcode>
<meansubtype> Corporate Purchasing Card </meansubtype>
<cardholder> TEST </cardholder>
<cardexpirationdate> 12/20 </cardexpirationdate>
<ipaddress> 10.23.10.23 </ipaddress>
<protocoltypename> </protocoltypename>
<testmode> 1 </testmode>
<customermessage> Completed. </customermessage>
<orderstate> Approved </orderstate>
<processingname> Name </processingname>
<operationtype> 200 </operationtype>
<billnumber> 511111100000001.2 </billnumber>
<orderamount> 100.00 </orderamount>
<ordercurrency> BYN </ordercurrency>
<slipno>111111</slipno>
<packetdate> 06.07.2016 10:53:45 </packetdate>
<signature> </signature>
</order> </orders>
</result>
Six first and last four digits of the card number are returned as the field <cardnumber> value here and after in all Web services; the remaining figures being hidden under * symbol.
If the payment is successfully confirmed, the field "orderstate" will contain the value Approved or PartialDelayed, the confirmation operation response_code is AS000. If the payment confirmation is not confirmed, the response_code will adopt the values AS100- AS998.
If the payment confirmation request cannot be processed, the request will return non-zero values of the firstcode, secondcode parameters.
An example of a result request in XML format which returned an error (wrong password):
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <!DOCTYPE result (View Source for full doctype...)> <result firstcode="7" secondcode="102" count="0"></result>
For description of the first and second codes of the automated interfaces refer to table "Error codes".
In SOAP format:
<?xml version='1.0' encoding='utf-8' standalone='no'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema'> <SOAP-ENV:Body SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <ASS-NS:MakeChargeResponse xmlns:ASS-NS='http://www.paysecure.ru/message/'> <return xmlns:si='http://www.paysecure.ru/type/' xsi:type='si:SOAPStruct'> <ordernumber xsi:type='xsd:string'>0001-01</ordernumber> <responsecode xsi:type='xsd:string'>AS000</responsecode> <recommendation xsi:type='xsd:string'></recommendation> <message xsi:type='xsd:string'>Completed.</message> <ordercomment xsi:type='xsd:string'>test payment</ordercomment> <orderdate xsi:type='xsd:string'>06.07.2016 11:23:13</orderdate> <amount xsi:type='xsd:string'>100.00</amount> <currency xsi:type='xsd:string'>BYN</currency> <meantypename xsi:type='xsd:string'>VISA</meantypename> <meannumber xsi:type='xsd:string'>411111****1111</meannumber> <lastname xsi:type='xsd:string'>Testov</lastname> <firstname xsi:type='xsd:string'>Test</firstname> <middlename xsi:type='xsd:string'>Testovich</middlename> <issuebank xsi:type='xsd:string'>New Bank</issuebank> <email xsi:type='xsd:string'>test@testpost.by</email> <bankcountry xsi:type='xsd:string'>Russia</bankcountry> <rate xsi:type='xsd:string'>1</rate> <approvalcode xsi:type='xsd:string'></approvalcode> <meansubtype xsi:type='xsd:string'>Classic</meansubtype> <cardholder xsi:type='xsd:string'>TEST</cardholder> <cardexpirationdate xsi:type='xsd:string'>12/20</cardexpirationdate> <ipaddress xsi:type='xsd:string'>11.23.11.23</ipaddress> <protocoltypename xsi:type='xsd:string'></protocoltypename> <testmode xsi:type='xsd:string'>1</testmode> <customermessage xsi:type='xsd:string'>Completed.</customermessage> <orderstate xsi:type='xsd:string'>Approved</orderstate> <processingname xsi:type='xsd:string'>Name</processingname> <operationtype xsi:type='xsd:string'>200</operationtype> <billnumber xsi:type='xsd:string'>511111100000001.2</billnumber> <orderamount xsi:type='xsd:string'>100.00</orderamount> <ordercurrency xsi:type='xsd:string'>BYN</ordercurrency> <slipno xsi:type='xsd:string'>111111</slipno> <packetdate xsi:type='xsd:string'>06.07.2016 11:28:26</packetdate> <signature xsi:type='xsd:string'></signature> </return> </ASS-NS:MakeChargeResponse></SOAP-ENV:Body> </SOAP-ENV:Envelope>
The following root certificate has to be installed on the requester side in the Trusted Root Certification Authorities Store for correct work with WEB-services via secure communication over TLS:
- root certificate Thawte: Comodo: COMODO RSA Certification Authority (https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/969/108/root-comodo-rsa-certification-authority-sha-2);
- root certificate GlobalSign: GlobalSign Root CA R1 (https://www.globalsign.com/repository/ca-certificates/).
Before to start, check the presence of this certificate in the trust store and add tit if necessary.
