A hidden payment mode, when all data about the order, about the customer, about the payment method and payment means are transmitted directly by the merchant, can be performed using a card or a token.
Transfer of payment parameters
To use this mode, the silentpay web service is provided.
URL for payment via silentpay :
https://<SERVER-NAME>/pay/silentpay.cfm
Silentpay service parameters:
Name | Manda- | Accepted values | Default value | Description |
Merchant_ID | Yes | Number | Merchant identification number in IPS Assist | |
Login | Yes | String | Service Login | |
Password | Yes | String | Password | |
OrderNumber | Yes/No | 128 symbols | Order number (order identification on the merchant side) | |
OrderAmount | Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Payment amount (ex.: 10.34) | |
OrderCurrency | No | 3 symbols | Default currency of enterprise or merchant | Order currency code (for OrderAmount value) Ex.: RUB, USD, EUR and so on. |
OrderComment | No | 4000 symbols | Order comment | |
Delay | No | 0 – one stage payment, | 0 | Flag for selection of one or two payment stages |
Language | No | RU – Russian | Enterprise or merchant language | Language of payment pages |
ClientIP | No | IP-address of customer | ||
Cardtype | No | 1 – VISA | Card type | |
Cardnumber | Yes | Card number | ||
Cardholder | No* | 70 letters (no digits). Space as delimiter | Card-holder | |
Expiremonth | Yes | 1-12 | Card expiration month | |
Expireyear | Yes | Year in YYYY format | Card expiration year | |
Cvc2 | Yes | CVC2 code | ||
Lastname | No* | 70 letters (no digits) | Customer second name | |
Firstname | No* | 70 letters (no digits) | Customer first name | |
Middlename | No | 70 letters (no digits) | Customer middle name | |
No* | 128 symbols | E-mail of customer | ||
Address | No | 256 symbols | Customer address | |
HomePhone | No | 64 symbols | Customer home phone | |
WorkPhone | No | 20 symbols | Customer work phone | |
MobilePhone | No | 20 symbols | Customer mobile phone | |
Fax | No | 20 symbols | Customer fax number | |
Country | No | 3 symbols | Customer's country code | |
State | No | 3 symbols | Customer's region code | |
City | No | 70 symbols | Customer's city | |
Zip | No | 25 symbols | Customer's postal index | |
isConvert | No | 0 – don't convert to the base currency 1 - don't convert to the base currency if possible 2 – always convert to the base currency | 1 | Currency conversion indicator |
Format | No | 1 – CSV | 1 | Results format. |
Signature | No | String | The string is joined according to determined rules. Then the MD5 hash prepared from this string. Hash is signed by private RSA key of the merchant. Key length - 1024. Received bit sequence is a signature. Signature is transferred BASE64 coded string. Attention! The parameter is necessary in order to protect the transmitted data from the possibility of their substitution by intruders. You should also enable the setting for check value or signature in the Personal account. | |
RecurringIndicator | No | 1 –recurring payment 0 – standard payment | 0 | Recurring payment indicator |
RecurringMinAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Minimum payment amount for recurring payments Mandatory when RecurringIndicator = 1 | |
RecurringMaxAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Maximum payment amount for recurring payments Mandatory when RecurringIndicator = 1 | |
RecurringPeriod | No/Yes | 3 digits number | Recurring interval in days Mandatory when RecurringIndicator = 1 | |
RecurringMaxDate | No/Yes | Date in string representation DD.MM.YYYY | Finish date of recurring payments Mandatory when RecurringIndicator = 1 | |
CustomerNumber | No | 32 symbols | Merchant's internal customer identification | |
SaveCard | No | 1 - the card is stored to this customer number; 0 - the card is not stored. | 0 | This parameter permits to store the card to this client number for subsequent payments, if the current payment is successful. If this card for this client number already has been saved before, the parameter is ignored. |
| Disable3DS | No | 0 - perform 3D-Secure authorization according to the merchant settings; 1 - fulfill payment without 3-D Secure. | 0 | Flag of disabling 3-D Secure. The use of this operating mode is possible in agreement with Assist. To configure it, you need to contact the support service (support@belassist.by). When using this parameter, it must also be added to the order signature, which is built according to determined rules . |
HTTP POST request example:
<FORM ACTION="https://SERVER-NAME/pay/silentpay.cfm " method="POST"> <INPUT TYPE="hidden" NAME="Merchant_ID" VALUE="Your_merchant_ID"> <INPUT TYPE="hidden" NAME="Login" VALUE="Service login"> <INPUT TYPE="hidden" NAME="Password" VALUE="Password"> <INPUT TYPE="hidden" NAME="OrderNumber" VALUE="011001-10"> <INPUT TYPE="hidden" NAME="OrderAmount" VALUE="22"> <INPUT TYPE="hidden" NAME="OrderCurrency" VALUE="RUB"> <INPUT TYPE="hidden" NAME="OrderComment" VALUE="Order 011001-10"> <INPUT TYPE="hidden" NAME="Delay" VALUE="0"> <INPUT TYPE="hidden" NAME="isConvert" VALUE="1"> <INPUT TYPE="hidden" NAME="Language" VALUE="RU"> <INPUT TYPE="hidden" NAME="ClientIP" VALUE="Customer IP address"> <INPUT TYPE="hidden" NAME="Cardtype" VALUE="Card type"> <INPUT TYPE="hidden" NAME="Cardnumber" VALUE="Card number"> <INPUT TYPE="hidden" NAME="Cardholder" VALUE="Card-holder"> <INPUT TYPE="hidden" NAME="Expiremonth" VALUE="Card expiration- month"> <INPUT TYPE="hidden" NAME="Expireyear" VALUE="Card expiration - year"> <INPUT TYPE="hidden" NAME="Cvc2" VALUE="CVC2 or CVV code"> <INPUT TYPE="hidden" NAME="Lastname" VALUE="Second name"> <INPUT TYPE="hidden" NAME="Firstname" VALUE="First name"> <INPUT TYPE="hidden" NAME="Middlename" VALUE="Middle name"> <INPUT TYPE="hidden" NAME="Email" VALUE="Email"> <INPUT TYPE="hidden" NAME="Address" VALUE="Customer address"> <INPUT TYPE="hidden" NAME="Homephone" VALUE="Customer home phone"> <INPUT TYPE="hidden" NAME="Workphone" VALUE="Customer work phone"> <INPUT TYPE="hidden" NAME="Mobilephone" VALUE="Customer mobile phone"> <INPUT TYPE="hidden" NAME="Fax" VALUE="Customer fax number"> <INPUT TYPE="hidden" NAME="Country" VALUE="Customer's country"> <INPUT TYPE="hidden" NAME="State" VALUE="Customer's region"> <INPUT TYPE="hidden" NAME="City" VALUE="Customer's city"> <INPUT TYPE="hidden" NAME="Zip" VALUE="Customer postal index"> <INPUT TYPE="hidden" NAME="TestMode" VALUE="Test mode"> <INPUT TYPE="hidden" NAME="Format" VALUE="Result format"> <INPUT TYPE="Submit"></FORM>
The service description for SOAP format can be found on page:
https://<SERVER-NAME>/pay/silentpay.wsdl
Returned values:
Name | Description |
ordernumber | Order number |
billnumber | IPS Assist bill number |
testmode | Test mode |
ordercomment | Comment |
orderamount | Original order amount |
ordercurrency | Original order currency |
amount | Payment amount |
currency | Payment currency |
rate | Currency rate |
firstname | Customer first name |
lastname | Customer second name |
middlename | Customer middle name |
ipaddress | IP-address of customer |
meantypename | Payment mean type |
meansubtype | Payment mean sub-type |
meannumber | Payment mean number |
cardholder | Payment mean holder |
cardexpirationdate | Card expired date |
issuebank | Issuer-Bank name |
bankcountry | Issuer-Bank country |
orderdate | Order date (GMT) |
orderstate | Order status |
responsecode | Return code |
message | Message |
customermessage | Message for customer |
recommendation | Recomendations |
approvalcode | Authorization code |
protocoltypename | Protocol |
processingname | Processing |
operationtype | Operation type |
packetdate | Request date (GMT) |
signature | 1) For signature type 'MD5' - empty 2) For signature type 'PGP' – value X signed by secured key of IPS Assist, BASE64 encoded |
pareq | 3D-Secure authorization request packet |
ascurl | URL for 3D-Secure authorization redirect |
There are performance limitations when using the service.
Request result will be provided according the requested format.
For CSV format:
Field name:field value Field name:field value....Field name:field value
For XML format:
<?xml version='1.0' encoding='UTF-8' standalone='yes'?> <!DOCTYPE result [ <result firstcode='first code' secondcode='second code' count='objects count'> <orders><order> <ordernumber>Order number</ordernumber> <responsecode>Return code</responsecode> <recommendation>Recommendations</recommendation> <message>Message</message> <ordercomment>Comment</ordercomment> <orderdate>Payment date/time</orderdate> <amount>Payment amount</amount> <currency>Currency code</currency> <meantypename>Card type</meantype> <meannumber>Card Number</meannumber> <lastname>Second name</lastname> <firstname>First name</firstname> <middlename>Middle name</middlename> <issuebank>Issuer-Bank name</ issuebank > <email>E-mail</email> <bankcountry>Issuer-Bank country code</bankcountry> <rate>Currency rate</rate> <approvalcode>Authorization code</approvalcode> <meansubtype>Card sub-type</meansubtype> <cardholder>Card-holder</cardholder> <cardexpirationdate>Card expired date</cardexpirationdate> <ipaddress>IP-address</ipaddress> <protocoltypename>Protocol type</protocoltypename> <testmode>Test mode payment indicator</ testmode > <customermassage>Message for customer</customermassage > <orderstate>Order status</orderstate> <processingname>Processing name</ processingname> <operationtype>Operation type</operationtype> <billnumber>Bill number</billnumber> <orderamount>Original payment amount</orderamount> <ordercurrency>Original currency </ordercurrency> <paketdate> Packet data</paketdate> <signature> </signature> <pareq>pareq value</pareq> <ascurl>URL of Issuer-Bank </ascurl> </order></orders></result>
For SOAP format:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/"> <soapenv:Header/> <soapenv:Body> <ws:SilentPayResponse> <return> <ordernumber xsi:type="xsd:string">Order number</ordernumber> <responsecode xsi:type="xsd:string">Return code</responsecode> <recommendation xsi:type="xsd:string">Recommendations</recommendation> <message xsi:type="xsd:string">Message</message> <ordercomment xsi:type="xsd:string">Comment</ordercomment> <orderdate xsi:type="xsd:string">Payment date/time</orderdate> <amount xsi:type="xsd:string">Payment amount</amount> <currency xsi:type="xsd:string">Currency code</currency> <meantypename xsi:type="xsd:string">Card type</meantype> <meannumber xsi:type="xsd:string">Card number</meannumber> <lastname xsi:type="xsd:string">Second name</lastname> <firstname xsi:type="xsd:string">First name</firstname> <middlename xsi:type="xsd:string">Middle name</middlename> <issuebank xsi:type="xsd:string">Issuer-Bank name</ issuebank > <email xsi:type="xsd:string">E-mail</email> <bankcountry xsi:type="xsd:string">Issuer-Bank country code</bankcountry> <rate xsi:type="xsd:string">Currency rate</rate> <approvalcode xsi:type="xsd:string">Authorization code</approvalcode> <meansubtype xsi:type="xsd:string">Card sub-type</meansubtype> <cardholder xsi:type="xsd:string">Card-holder name</cardholder> <cardexpirationdate xsi:type='xsd:string'>Card expired date</cardexpirationdate> <ipaddress xsi:type="xsd:string">customer IP-address</ipaddress> <protocoltypename xsi:type="xsd:string">Protocol type</protocoltypename> <testmode xsi:type="xsd:string">Test mode payment flag</ testmode > <customermassage xsi:type="xsd:string">Message fro customer</customermassage > <orderstate xsi:type="xsd:string">Order status</orderstate> <processingname xsi:type="xsd:string">Processing name</processingname> <operationtype xsi:type="xsd:string">Operation type</operationtype> <billnumber xsi:type="xsd:string">Bill number</billnumber> <orderamount xsi:type="xsd:string">Original payment amount</orderamount> <ordercurrency xsi:type="xsd:string">Original payment currency</ordercurrency> <paketdate xsi:type="xsd:string">packet date</paketdate> <signature xsi:type="xsd:string"> </signature> <pareq xsi:type="xsd:string">pareq value </pareq> <ascurl xsi:type="xsd:string">Issuer-Bank URL </ascurl> </return> </ws:SilentPayResponse> </soapenv:Body> </soapenv:Envelope>
In case of successful payment the return code responsecode is equal to AS000 value.
In case of unsuccessful payment the responsecode is one of AS100-AS998 values (except AS110 code that is returned when 3-D Secure authorization required – see here, for details).
If the request can't be processed the firstcode and secondcode parameters have non-zero values.
If responsecode AS300 is received, and order status (orderstate) and operation status (operationstate) are 'In Process', the current status of the payment can be obtained later via the request to the web-service orderresult.
If the payment result is not received (for example, due to network problems), then you can get it later via the request to the web-service orderresult.
Result example in XML format for error return (not correct password):
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <!DOCTYPE result [...]> <result firstcode="7" secondcode="102" count="0"></result>
For the decryption of firstcode and secondcode values, please, refer here.
An enterprise can also initiate the provision of subscription services for payments passing through UCS processing.
Additional parameters for System of Fraud Intelligence (SOFI)
Merchants, which use silentpay service can provide additional parameters about the customer for analyses within the anti-fraud system.
In additional to the main list of the silentpay parameters the following optional parameters for SOFI can be provided in the request:
Name | Accepted values | Description |
HEADER_HTTP_USER_AGENT | String (255 chars) | Header User Agent http from http request |
HEADER_HTTP_ACCEPT | String (255 chars) | Header Accept http from http request |
HEADER_HTTP_ACCEPT_LANGUAGE | String (128 chars) | Header Accept Language http from http request |
HEADER_HTTP_REFERER | String (255 chars) | Header Referer http from http request |
HEADER_REMOTE_HOST | String (16 chars) | Customer IP-address |
HEADER_HTTP_FORWARDED | String (16 chars) | Header Forwarded http from http request |
HEADER_HTTP_X_FORWARDED_FOR | String (16 chars) | Header Xforwarded-For http from http request |
HEADER_HTTP_VIA | String (128 chars) | Header Via http from http request |
CLIENT_JS_VER | String (16 chars) | Java script interpreter version |
CLIENT_LOCAL_TIME | String (128 chars) | Customer local time |
CLIENT_SCREEN_RES | String (16 chars) | Customer screen resolution (<width>x< high>) |
CLIENT_SCREEN_COLORS | Decimal (numbers from 1 to 24) | Color depth of customer screen |
CLIENT_JS_BROWSER_NAME | String (255 chars) | Customer browser name |
CLIENT_TIME_ZONE | Decimal (5) | Customer time zone GMT offset in hours. Conversion formula is (- GMT_H). For example, offset GMT+2 is equal to – 2. |
CLIENT_COOKIES | String (16 chars) | Unique browser identity from external system |
CLIENT_JAVA | Logical (true, false) | Java script support enabled indicator |
CLIENT_STYLESHEETS | Logical (true, false) | css styles support |
CLIENT_BROWSER_PLATFORM | String (64 chars) | Browser platform name |
CLIENT_SYSTEM_LANGUAGE | String (5 chars) | Language code of customer operational system |
CLIENT_BROWSER_LANGUAGE | String (5 chars) | Language code of the browser |
CLIENT_USER_LANGUAGE | String (5 chars) | Customer language code |
CLIENT_PROCESSOR | String (16 chars) | Processor name of customer computer |
CLIENT_CONNECTION | String (16 chars) | HTTP connection type |
CLIENT_HOSTADDRESS | String (16 chars) | DNS lookup based on HOST_ADDRESS |
CLIENT_HOSTNAME | String (70 chars) | Customer host name |
3D-Secure authorization
It is possible to use the card, which requires 3D-Secure authorization for payment via silentpay service (when the shop and processing have configured settings for it).
When a payment by a card (which required 3D-Secure authorization) is processed the IPS Assist returns AS110 value in the responsecode replay field.
The additional fields are also added in the silentpay response packet. These fields allow the merchant to provide additional payer authentication using 3-D Secure technologies (VISA cards) and Mastercard SecureCode (Mastercard catds).
Currently, for additional authentication of the customer, the most issuing banks operate according to the 3-D Secure 1.0 protocol version for all types of cards.
For a more secure authentication process, issuing banks and payment systems are switching to a new version of protocol 2.0 for all types of cards (VISA, Mastercard). To support a new generation protocol, a merchant has to make changes to the customer authentication process.
To start the order payment, the merchant sends an authorization request to the IPS Assist server. The following data about the customer device and browser must be added to the usual request parameters, if this has not been done before for operating with the SOFI. This data is required in the new 3-D Secure 2.0 protocol.
Name | Accepted values | Description |
HEADER_HTTP_ACCEPT | String (255 chars) | Header Accept http from http request |
HEADER_HTTP_USER_AGENT | String (255 chars) | Header User Agent http from http request |
CLIENT_JAVA | Logical (true, false) | Java script support enabled indicator navigator.javaEnabled() |
CLIENT_BROWSER_LANGUAGE | String (5 chars) | Language code of the browser navigator. language |
CLIENT_SCREEN_COLORS | Decimal (15) | Color depth of customer screen Screen.pixelDepth |
CLIENT_SCREEN_RES | String (16 chars) | Customer screen resolution Screen.width + 'x' + screen.height |
ChallengeWindowSize | 2 chars (01 – 250x400, 02 – 390x400, 03 – 500x600, 04 – 600x400, 05 – Full screen) | IFrame size for cardholder verification |
3D-Secure authorization using the protocol 1.0
When a payment by a card requiring authorization using the 1.0 protocol is processed, the IPS Assist returns the response code AS110 and additional fields pareq and acsurl in response to the authorization request.
The customer has to be forwarded to the issuer-bank site by URL from acsurl field.
The following values should be provided in the request form:
AcsUrl | Url of Issuer-Bank: value which is received from IPS Assist in the acsurl field |
PaReq | The value which is received from IPS Assist in the pareq field |
TermUrl | Url of the shop for results from issuer-bank receiving |
MD | Identification that is used for further reference between order and 3D-Secure authorization |
Form example for Issuer-Bank request:
<FORM ACTION="acsurl value that is received from IPS Assist" method="POST"> <INPUT TYPE="hidden" NAME="PaReq" VALUE="pareq value that is received from IPS Assist"> <INPUT TYPE="hidden" NAME="TermUrl" VALUE="url of the shop"> <INPUT TYPE="hidden" NAME="MD" VALUE="Any identity (provided by shop)"> <INPUT TYPE="submit" NAME="Submit_3DS" CLASS="button" VALUE="Continue"> </FORM>
The issuer-bank returns (by URL which is provided in TermUrl parameter of the request) the following values:
PaRes | Result packet |
MD | Identity which was provided in the request |
After the receiving of the reply from Issuer-Bank the shop has to transfer the 3D-Secure authorization result (pares value) to the IPS Assist. Web-service get3DSec can be used for it.
Get3DSec – transfer of the 3D-Secure authorization result
Service request URL:
https://<SERVER-NAME>/get3dsec/ws3dsec.cfm.
Request and replay format: SOAP, a wsdl-description is available by the following URL:
https://payments.paysecure.ru/get3dsec/get3dsec.wsdl.
The merchant has to transfer the pares value to IPS Assist. The following request in SOAP format should be sent to the IPS Assist:
Input parameters:
Method: send3dsparams
Parameter | Mandatory | Description |
merchant_id | Yes | Merchant identification number in IPS Assist |
login | Yes | Service login |
password | Yes | Password |
ordernumber | Yes | Order number |
pares | Yes | 3DS result packet |
language | No | Language |
Example of the request:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <send3dsparams xmlns="urn:assist-processor"> <merchant_id>Merchant ID</merchant_id> <login>Login</login> <password>Password</password> <ordernumber>Order number</ordernumber> <language>Language</language> <pares>value pares which is received from issuer-bank</pares> </send3dsparams> <s:Body> <s:Envelope>
Return values – the same as in the silentpay request result.
In case of request failure:
<?xml version="1.0" encoding="windows-1251" 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/"> <SOAP-ENV:Fault> <faultcode>First code</faultcode> <faultstring>Second code</faultstring> <detail /> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
3D-Secure authorization using the protocol 2.0
he customer can be authenticated without entering an additional password (based on advanced data) - this is an important feature of the new version of the protocol. The authentication process, in which there is no additional interaction with the cardholder, is called Frictionless Flow. The authentication process, in which the cardholder is required to enter an additional verification code, is called the Challenge Flow process.
Also, before authentication using the new protocol, the client’s browser must send an additional request to the ACS of the issuing bank (further we will call it 3DSMethod).
To work with the new protocol, the following changes must be made on the enterprise's side:
Check the version of the 3D-Secure protocol in response to an authorization request to the Assist service. For version 1.0, support the workflow described above.
