Page History

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.

...

Silentpay service parameters:

* Parameters required when merchant uses the fiscalization service through the IPS Assist.

** Parameters required by the transfer of cheque items, the detailed description is here.

* sending of customer data is optional, but if the email field is missing, then the payment notification and a fiscal cheque will not be sent to customer even if the merchant has the appropriate settings. In the absence of these parameters, the operation of the SOFI system and the transmission of additional authentication parameters via 3-D Secure protocol version 2 will also be limited.

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="hidden" NAME="GenerateReceipt" VALUE="1">
<INPUT TYPE="hidden" NAME="Tax" VALUE="Tax rate identifier">
<INPUT TYPE="hidden" NAME="ReceiptLine" VALUE="Cheque item name">
<INPUT TYPE="hidden" NAME="FPMode" VALUE="Payment method">
<INPUT TYPE="Submit"></FORM>

The service description for SOAP format can be found on page:

...

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 WDDX format:

* Parameters are not sent if the request contains the fastpaypayment value for the payment type (payment via FPS).

** Parameters are sent only if the request contains the fastpaypayment value for the payment type (payment via FPS).

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 WDDX format:

field value field value field value field value field value field value ..

field value field value field value field value field value 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</response_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>

...

<?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</response_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

Recurring payments

The service is intended for initiation payments for continued services by subscription. This possibility is allowed for payments conducted through the UCS processing.

The parameter RecurringIndicator = 1 should be set in initial authorization request (see paragraph 2) in order to initiate the recurrent payment. Also the parameters of the range of amounts in subsequent recurring payments, payment frequency (in days) and the end date of subscription should be provided.

Then periodically the company will initiate the payment, setting the payment amount only and the rest required payment information (credit card data) is taken from the original payment.

To make the subsequent recurring payment, send a request to IPS Assist server by HTTP POST or SOAP method (in UTF-8 coding).

The request URL for the recurring payment:

https://<SERVER-NAME>/recurrent/rp.cfm.

List of request parameters

...

Parameter

...

Mandatory field

...

Adopted values

...

Default values

...

Description

...

BillNumber

...

Yes

...

15 or 16 characters

...

BillNumber of initial order

...

OrderNumber

...

Yes

...

128  characters

...

New order number for this recurrent payment

...

Merchant_ID

...

Yes

...

Number

...

The enterprise identifier in IPS Assist system

...

Login

...

Yes

...

8-20  characters

...

Login (Latin letters, digits and symbol _)

...

Password

...

Yes

...

8-20  characters

...

Password (Latin letters and digits)

...

Amount

...

Yes

...

Number, 15 digits

(delimiters: ',' or '.')

...

Amount of recurrent payment, in original currency (e.g., 10.34)

...

Currency

...

Yes

...

3 characters

...

Code of currency of the indicated amount of order 

...

TestMode

...

No

...

0 - operation mode,
1 – test mode

...

0

...

Must be the same as in the initial order request

...

OrderComment

...

No

...

255 characters

...

Comment

...

Language

...

No

...

RU

EN

...

EN

...

Language of the results output

...

Format

...

No

...

1 – CSV
2 – WDDX
3 – XML
4 - SOAP

...

1 for POST request and 4 for SOAP

...

Format of the results output

Request example for HTTP POST format:

<FORM ACTION="https://test.paysecure.ru/recurrent/rp.cfm" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="BillNumber" VALUE="511111100000001.1">
<INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A1_R1">
<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="20">
<INPUT TYPE="HIDDEN" NAME="Currency" VALUE="RUB">
<INPUT TYPE="HIDDEN" NAME="Format" VALUE="3">
<INPUT TYPE="HIDDEN" NAME="Language" VALUE="EN">
<INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Buy">
</FORM>

The list of response parameters:

...

Parameter

...

Value

...

billnumber

...

Unique order number in IPS Assist system (extended format)

...

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

...

Email

...

Payer's e-mail

...

orderdate

...

Date of order (in GMT)

...

orderstate

...

Order status

...

packetdate

...

Request issue date (in GMT)

...

signature

...

Signature

...

operationtype

...

Order type

...

operationstate

...

Operation status

...

amount

...

Operation amount

...

currency

...

Operation currency 

...

ipadress

...

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

...

rate

...

Currency rate

...

message

...

Operation result message

...

customermessage

...

Result message for a customer

...

recommendation

...

Recommendation

...

approvalcode

...

Authorization code

...

protocolname

...

Protocol

...

processingname

...

Processing

The request result when paying via FPS in 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>silent-test-101468</ordernumber>
<billnumber>599093519074915.1</billnumber>
<testmode>0</testmode >
<ordercomment></ordercomment>
<orderamount>31.79</orderamount>
<ordercurrency>RUB</ordercurrency>
<firstname>Auto</firstname>
<lastname>Test</lastname>
<middlename></middlename>
<email>null@assist.ru</email>
<orderdate>14.06.2022 11:39:19</orderdate>
<orderstate>In Process</orderstate>
<operationtype>100</operationtype>
<amount>31.79</amount>
<currency>RUB</currency >
<rate>1</rate>
<ipaddress>127.0.0.1</ipaddress>
<meantypename>QR code</meantype>
<responsecode>AS300</responsecode>
<message>preprocessing</message>
<customermassage>preprocessing</customermassage>
<recommendation></recommendation>
<protocoltypename>NET</protocoltypename>
<processingname>SbpRuSt</processingname>
<fastpayurl>https://qr.nspk.ru/AD100006N581D0KV8HUOT2B84344SM83?type=02&bank=100000000014&sum=3179&cur=RUB&crc=CCFD</fastpayurl>
<fastpaytimeout>14.06.2022 13:16:23</fastpaytimeout>
<fastpaytype>qrdynamic</fastpaytype>
<paketdate>14.06.2022 11:39:23</paketdate>
<signature> </signature>
</return>
</ws:SilentPayResponse>
</soapenv:Body>
</soapenv:Envelope>

The request result when paying via FPS in JSON format:

{"silentpay":
   {"meantypename":"QR code",
     "customermessage":"preprocessing",
     "message":"preprocessing",
     "testmode":0,
     "protocoltypename":"NET",
     "operationtype":100,
     "customer":
      {"lastname":"test",
       "firstname":"test",
       "middlename":"",
       "ipaddress":"127.0.0.1",
       "email":"null@assist.ru"},
     "orderdate":"14.06.2022 11:40:43",
     "packetdate":"14.06.2022 11:40:46",
     "orderamount":1.99,
     "ordercomment":"",
     "ordercurrency":"RUB",
     "recommendation":"",
     "processingname":"SbpRuSt",
     "orderstate":"In Process",
     "fastpay":
       {"url":"https://qr.nspk.ru/AD100025MS3FMK9K95LACS1LCQDKB18F?type=02&bank=100000000014&sum=199&cur=RUB&crc=A77C",
        "type":"qrdynamic",
        "timeout":"14.06.2022 13:17:46"},
      "rate":1,
      "billnumber":"599093519074916.1",
      "currency":"RUB",
      "amount":1.99,
      "ordernumber":"silent-test-198954",
      "responsecode":"AS300"}}

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:

Six first and four last numbers of the card number are returned as the field <meannumber> value here and after in all Web services; the remaining figures being hidden under * symbol.

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:

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 response_code responsecode replay field. Also, fields pareq and acsurl are not empty in this case.

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

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), Mastercard SecureCode and MirAccept (Mir catds).

For additional authentication of the customer, it is possible to use version 1 or version 2 of the 3-D Secure protocol. Protocol version 1 technology is used for VISA and Mastercard cards issued in the Russian Federation. Protocol version 2 technology is used for MIR and UPI cards.

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 protocol version 2.

3D-Secure authorization using the protocol version 1

When a payment by a card requiring authorization using the protocol version 1 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:

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:

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

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

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

1. Check the version of the 3D-Secure protocol in response to an authorization request to the Assist service. For version 1, support the workflow described above.
2. For version 2, create a hidden iFrame on the payment page (for a detailed parameters description see below) and send 3DSMethod request (if available) to the issuing bank ACS.
3. To continue authentication, call the get3dsecver2 web service with additional 3D-Secure parameters. If authentication occurs without additional interaction with the customer (Frictionless Flow), then Assist will receive its result and send the authorization transaction to the processing. The enterprise will receive in response a full payment result, which also contains the result of authorization in processing. If additional authentication of the customer is necessary, then the IPS Assist will return additional fields for verification (Challenge Flow) in response to the request.
4. If there are additional fields in the response that indicate the need for additional verification, the enterprise creates an iFrame on the payment page, which implements the display of the ACS page of the issuing bank to enter a one-time password. Customer completes authentication.
5. If the response contains additional fields indicating the possibility of Decoupled Authentication, the enterprise awaits the result of the verification check. Buyer authentication can be done through an alternative method supported by the issuing bank (for example, through a push notification on the phone and Face ID or fingerprint authentication in the issuing bank's app).
6. IPS Assist will receive the result of the verification to the server on its side (for Challenge Flow and Decoupled Authentication). In case of successful verification, a payment transaction will be processed. If the verification fails, the operation will fail.
7. To find out the final result of payment for an order, the enterprise must use one of the methods for obtaining an authorization result.

The logic of the new protocol version 2 is displayed as a diagram. The description below contains links to numbered units of the diagram.

Image Added

To start paying for the order, the enterprise sends an authorization request to the IPS Assist server  and the necessary additional parameters (unit 1).

On the payment with a card requiring authorization under the protocol version 2 the IPS Assist will return the AS110 return code (unit 2) and an additional threedsdata parameter block in the response. The full list of parameters that may be contained in the threedsdata block is presented in the table below:

¹The parameter may be contained in the response of the service: 1- silentpay; 2 - get3dserver2.

² In case of authorization without additional interaction with the customer (Frictionless Flow), the parameters challengeurl and challengerequest will not be returned.

Depending on the content of the received threedsdata block (units 3,7,8), the authentication proceeds differently.

The main operating scenarios for version 2 are determined by whether a 3DSMethod call is required (generation of a hidden iFrame in the client browser), as well as whether additional client authentication is required and under what scenario it takes place:

• If there is the issuing bank URL threeDSMethodURL (unit 7), the merchant generates hidden HTML iFrame on the payment page (unit 9) and sends a POST request with one parameter threeDSMethodData to the received address threeDSMethodURL, and then calls the get3dsecver2 service (unit 10).
• If there is the issuing bank URL threeDSMethodURL (units 7, 9, 10), without the additional interaction with the card holder (unit 8) - Frictionless Flow (F), IPS Assist immediately executes a transaction in processing or completes the operation with an error. In response to a call to the get3dsecver2 service, the merchant will receive the payment status (unit 6).
• If there is the issuing bank URL threeDSMethodURL (units 7, 9, 10), and the additional interaction with the card holder is necessary (unit 8), the merchant generates hidden HTML iFrame on the payment page and sends an HTTP POST request for the card holder verification to the specified challengeurl URL (unit 11). This iFrame displays the issuer's bank ACS page and the customer enters a one-time password received from the bank. This is the Challenge Flow (C) scenario.
• If there is the issuing bank URL threeDSMethodURL (units 7, 9, 10), the additional interaction with the card holder is necessary (unit 8) and with decoupled authentication, the merchant must keep the order in the In Process state and wait for the final payment status (within the lifetime of the order). This is the Decoupled Authentication (D) scenario.
• If there is not the issuing bank URL threeDSMethodURL and when the additional interaction with the card holder is not required - Frictionless Flow (F), the transaction will be processed immediately and the payment process will be completed (unit 6). The merchant will receive the authentication result and payment status immediately in response to the call to the silentpay service.
• If there is not the issuing bank URL threeDSMethodURL and the additional interaction with the card holder is necessary (unit 8), but with no issuing bank URL threeDSMethodURL, the enterprise should generate an HTML iFrame object on the payment page and send an HTTP POST request for the card holder verification to the specified challengeurl URL (unit 11). This iFrame displays the issuer's bank ACS page and the customer enters a one-time password received from the bank.
• If there is not the issuing bank URL threeDSMethodURL and the additional interaction with the card holder is necessary (unit 8) under the Decoupled Authentication scenario (D), the merchant must keep the order in the In Process state and wait for the final payment status (within the lifetime of the order).

In those work scenarios that require the generation of a hidden HTML iFrame, at step 7 in the threedsdata unit, the merchant will receive the necessary threeDSMethodData and threeDSMethodURL parameters for generating a POST request (unit 9). The result of sending the request can be positive (HTTP code 200), negative (any other HTTP code), or the request sending timeout value will be exceeded (set to 10 seconds). After receiving the HTTP code or the timeout has expired, a request must be sent to the get3dsecver2 service (unit 10) to continue the authentication process.

get3dserver2 - web service of the 3D-Secure authentication continuation

Service request URL:

https://<SERVER-NAME>/get3dsec/get3dsecver2.cfm

Supported formats: SOAP, JSON.

Input parameters:

IPS Assist continues the process of authentication of the customer in the payment system and the issuing bank through 3DS Server.

If additional verification of the customer is not required (Frictionless Flow) (unit 8), IPS Assist executes a transaction in processing or completes the operation with an error (depending on processing and enterprise settings, and authentication result) (unit 6).

The response to the request in this case will contain one of the final response codes (AS000 - operation completed successfully, AS100-AS109 - denial of authorization), all response fields described  above, and an additional threedsdata data block in which the challenge parameter is F, and the alphaauthresult field contains the authentication result (Y, N, U, R, I).

Receiving an AS110 response code in the response of the get3dsecver2 web service means that an additional card holder verification is required (Challenge Flow). In the threedsdata data block, the challenge parameter will be equal to C, and the challengeurl and challengerequest parameters will be filled (block 8). In this case, the enterprise should generate an HTML iFrame object on the payment page and send an HTTP POST request for the card holder verification to the specified URL (block 11) with the creq parameter, in which pass the received challengerequest value. This iFrame displays the ACS page of the issuing bank and the customer enters a one-time password received from the bank.

In a decoupled authentication scenario, the challenge parameter in the threedsdata data block will be equal to D, and the challengeurl and challengerequest parameters will be absent (block 8). The merchant must in this case keep the order in the In Process state and await the final payment status.

IPS Assist will receive the result of this verification on its server in asynchronous mode. Depending on the authentication result and the settings of the processing and of the enterprise, the IPS Assist will executes a transaction in processing or completes the operation with an error.

In order for the buyer to be able to return back to the merchant’s website after passing the additional verification, the IPS Assist support service should be informed of the URL to return the buyer and receive the result of passing the additional verification. Receiving this request will mean for a merchant, that the additional verification is completed, and the merchant can now redirect the buyer’s browser to the result page on its side and wait for the completion of the payment transaction in processing.

Receipt of the payment result after additional verification is reflected in the diagram in blocks 12, 13, 14.

An example of the threedsdata data block in which additional verification of the card holder is not required (in this case, the responsecode will be different from AS110):

<threedsdata>
<version>2.2</version>
<alphaauthresult>Y</alphaauthresult>
<challenge>F<challenge>
</threedsdata>

An example of a threedsdata data block in which additional card holder verification is required (responsecode is AS110):

<threedsdata>
<version>2.2</version>
<challenge>С<challenge>
<challengeurl>https://acs.superbank.ru/version20/creq</challengeurl>
<challengerequest>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE3ZWJlMDU3LTg2ZjgtNGFmMS05MTJkHGNlYTc5Mzc0OWUxMiIsImFjc1RyYW5zSUQiOiI5ODhmOWZmYS1kNzYyLTQ0YjktOWI0OS01ZDRkMjU5YmRkZWQiLCJkc1RyYW5zSUQiOiJkMGJmZGQzYy00YzdhLTVmNjktODAwMC0wMDAwMDAwOGM3NjMiLCJtZXNzYWdlVHlwZSI6IkNSеZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0</challengerequest>
</threedsdata>

To get a web service response in JSON format, you need to pass content-type = application/json or format = 5 in the request. Description of the parameters of all IPS Assist web services for the JSON format is contained in the swagger file at:

https://docs.assist.ru/swagger/

An example JSON response for an operation without additional authentication:

{
   "threedsdata":    {
      "version": "2.2.0",
      "alphaauthresult": "Y",
      "challenge": "F"
   },
   "MakePaymentResponse":    {
      "customermessage": "Success",
      "message": "Success",
      "token": "",
      "testmode": "0",
      "operationtype": "100",
      "orderdate": "23.10.2019 10:45:47",
      "packetdate": "23.10.2019 10:49:48",
      "orderamount": "15.00",
      "ordercomment": "",
      "cardexpirationdate": "12/20",
      "ordercurrency": "RUB",
      "recommendation": "",
      "processingname": "Fake",
      "meannumber": "220000****0001",
      "orderstate": "Approved",
      "rate": "1",
      "amount": "15.00",
      "responsecode": "AS000",
      "meantypename": "MIR",
      "protocoltypename": "NET",
      "bankcountry": "UNKNOWN",
      "customer":       {
         "lastname": "Testov",
         "firstname": "Тест",
         "middlename": "Testovich",
         "ipaddress": "10.10.10.10",
         "email": "null@assist.ru"
      },
      "cardholder": "TEST",
      "approvalcode": "X38988",
      "billnumber": "5161957242913232.1",
      "issuebank": "UNKNOWN",
      "currency": "RUB",
      "ordernumber": "231020191345849_user2",
      "meansubtype": ""
   }
}

A response example for an operation with additional authentication:

{
   "threedsdata":    {
      "version": "2.2.0",
      "challengerequest": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3MDlmM2M0LTVkNTItNDNlZS1hMTcxLTQ2NzM0MDRlMzUxMyIsImFjc1RyYW5zSUQiOiDNZWNmOTk4NC1jZGY2LTRkMWQtYTUzZS1kMzZhOTUyZTgzZDYiLCJkc1RyYW5zSUQiOiJlYWRlMmY4NC1jMDY1LTVmMGItODAwMC0wMDAwMDAwYjU3NWQiLCJtZXSKFWdlVHlwZSI6IkNSZXEEJCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0",
      "challengeurl": "https://acs.superbank.ru/acs/creq",
      "challenge": "C"
   },
   "MakePaymentResponse":    {
      "customermessage": "New Client authentication by 3DSecure technology.",
      "message": "New Client authentication by 3DSecure technology.",
      "token": "",
      "testmode": "0",
      "operationtype": "100",
      "orderdate": "23.10.2019 10:45:46",
      "packetdate": "23.10.2019 10:46:32",
      "orderamount": "15.00",
      "ordercomment": "",
      "cardexpirationdate": "12/20",
      "ordercurrency": "RUB",
      "recommendation": "",
      "processingname": "Fake",
      "meannumber": "220000****0003",
      "orderstate": "In Process",
      "rate": "1",
      "amount": "15.00",
      "responsecode": "AS110",
      "meantypename": "MIR",
      "protocoltypename": "NET",
      "bankcountry": "UNKNOWN",
      "customer":       {
         "lastname": "Testov",
         "firstname": "Тест",
         "middlename": "Testovich",
         "ipaddress": "10.10.10.10",
         "email": "null@assist.ru"
      },
      "cardholder": "TEST",
      "approvalcode": "",
      "billnumber": "5161957242913224.1",
      "issuebank": "UNKNOWN",
      "currency": "RUB",
      "ordernumber": "231020191345849_user1",
      "meansubtype": ""
   }
}

Back on top

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

Token payment

When you pay by the Google Pay token in the browser on the online store side, the following actions are performed:

Image Removed

...

When you pay by the Apple Pay token in the browser on the online store side, the following actions are performed:

Image Removed

1. The buyer selects the product or service on the online store site and presses the Apple Pay button (it is available only in Safari browser on the MacOS platform).
2. After pressing the Apple Pay button the Apple Pay API is called through the Apple Pay and the certificate with the merchant public key is transmitted. At the same time, a special dialog opens, where the buyer can select one of the cards added to the Apple Pay mobile app.
3. After selecting the card, a PUSH notification is sent to the iPhone of the buyer and the buyer is asked to apply a finger to the reader to confirm the payment.
4. Apple Pay app creates an encrypted package with a token and payment data and returns it to online store page script.
5. The encrypted packet with the token and payment data is sent to the IPS Assist TokenPay service.
6. The IPS Assist decrypts the packet with the token and payment data.
7. The IPS Assist performs payment by a token through the processing of a settlement bank.
8. The IPS Assist returns the results of payment to the online store.

To organize the receipt of payments by token in the browser on the online store side, you need to do the following preparatory steps:

• make a request to connect payment means for payments by token(Apple Pay, Google Pay)  to the IPS Assist technical support service  support@assist.ru;
• embed into the code of your page:
  • to receive an encrypted packet with a token and payment data:
    • Google Pay API for Google Pay;
    • ApplePay JS API for Apple Pay;
  • for payment - access to TokenPay service;
• obtain confirmation from the IPS Assist technical support service that all the necessary technical settings for the functioning of the TokenPay payment processing service when paying for goods and services to your merchant have been fulfilled;
• prepare for payments receiving;
• when using Apple Pay, create and sign an Apple Pay certificate to make payments using the corresponding section in the IPS Assist Personal Account;
• when using Google Pay, you should register with Google Pay API to get a MerchantID for use it as MerchantID parameter, set gateway=”assist” and specify allowedCardAuthMethods = ["CRYPTOGRAM_3DS"] to organize the scheme for encrypting a data packet with a token or allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"], if you also need to accept payments with non tokenized cards that saved in Google account.

...