Page History

...

...

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

...

...

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.

...

...

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.

For cards of international payment systems VISA and Mastercard in most cases version 2 of the 3D-Secure protocol is used by additional authentication of the customer, the same version of the protocol is also used for UPI cards. For cards of the BELKART payment system, authentication is carried out according to version 1 of the protocol.

To start the order payment, the 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.0 protocol.

3D-Secure authorization using the protocol version 1

...

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

...

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

...

Code Block
language xml
<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.

...

Code Block
language xml
<?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

...

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

...

1. 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.
2. For version 2.0, 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 ws3dsecver2 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. IPS Assist will receive the result of the verification to the server on its side. In case of successful verification, a payment transaction will be processed. If the verification fails, the operation will fail.
6. 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 .0 is displayed as a diagram. The description below contains links to numbered units of the diagram.

Image RemovedImage 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 .0 the IPS Assist will return the AS110 return code (unit 2) and an additional threedsdata parameter block in the response.  The The full list of parameters that may be contained in the threedsdata block is presented in the table below:

Name	Accepted values	Description	In the response of the service1
version	11(1.0.0, 1.0.2) 21 (2.0, 2.1.0, 2.2.0)	3-D Secure Protocol version	1,2
threeDSServerTransID	String	3DS Server transaction ID	1,2
threeDSMethodURL	String (255 chars)	The ACS URL that will be used by the 3DS Method	1
threeDSMethodData	String (255 chars)	Request body (Base64 encoded)	1
alphaauthresult	Y - success, N - faifail, A - Attempt, U – - unable to authenticate, R - rejected, E - error, I - Informational Only	Authentication result will be received in case of Frictionless Flow authentication.	1,2
challenge	F - Frictionless Flow C –  - Challenge Flow D - Decoupled Authentication	Interaction with the customer (C – - required, F – - not needed, D - decoupled authentication)	1,2
challengeurl2	Full URL like https://acs.... 2048 symbols maximum	The ACS URL for payer verification	1,2
challengerequest2	String	Request body (Base64 encoded) for challengeurl request	1,2

...

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

Anchor
2t 2t

² 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, 47, 58), the authentication proceeds differently.

Main work scenarios:

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 For version 3D-Secure 2.0 (unit 3), if there is the issuing bank URL threeDSMethodURL (unit 57), the enterprise merchant generates hidden HTML iFrame on the payment page (unit 89) and sends a POST request with one parameter threeDSMethodData to the received address threeDSMethodURL, and then calls the get3dsecver2 service (unit 910).
• For version 3D-Secure 2.0 (unit 3), if If there is the issuing bank URL threeDSMethodURL (units 5 7, 89, 910), without the additional interaction with the card holder (unit 48) , - Frictionless Flow (F), IPS Assist immediately executes a transaction in processing or completes the operation with an error (unit 12).. In response to a call to the get3dsecver2 service, the merchant will receive the payment status (unit 6).
• If For version 3D-Secure 2.0 (unit 3), if there is the issuing bank URL threeDSMethodURL (units 5 7, 89, 910), and the additional interaction with the card holder is necessary (unit 108), the enterprise merchant generates hidden HTML iFrame on the payment page (unit 8) 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 For version 3D-Secure 2.0 (unit 3) with no issuing bank URL threeDSMethodURL and without  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 Frictionless Flow (F), the transaction will be processed immediately and the payment process will be completed (unit 12).For version 3D-Secure 2.0 (unit 3), if the additional interaction with the card holder is necessary (unit 4), but with no 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:

Name	Accepted values	Description
merchant_id	Number	Merchant identification number in IPS Assist
login	String	Service Login
password	String	Password
billnumber	15 or 16 digits, extended payment number	Unique number of payment in IPS Assist
threeDSServerTransID	String	3DS Server transaction ID

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 10), IPS Assist executes a transaction in processing or completes the operation with an error (depending on processing and enterprise settings, and authentication result) (unit 12).

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.

Warning

The process of receiving the result of an additional verification on the server of the IPS Assist is asynchronous. Only after receiving this result a payment transaction will be processed (or not conducted) in processing, which will lead to blocking of funds on the customer’s card. The merchant should receive the result of the payment transaction from IPS Assist in one of the standard ways. The enterprise can send a request to the receiving of the payment result by order number web service  or configure on its side to receive notifications sent by Assist to enterprise server.

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

Code Block
language xml
<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):

Code Block
language xml
<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.belassist.by/swagger/

An example JSON response for an operation without additional authentication:

Code Block
language xml
{ "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": "BYN", "recommendation": "", "processingname": "Fake", "meannumber": "220000****0001", "orderstate": "Approved", "rate": "1", "amount": "15.00", "responsecode": "AS000", "meantypename": "VISA", "protocoltypename": "NET", "bankcountry": "UNKNOWN", "customer": { "lastname": "Testov", "firstname": "Тест", "middlename": "Testovich", "ipaddress": "10.10.10.10", "email": "null@assist.by" }, "cardholder": "TEST", "approvalcode": "X38988", "billnumber": "5161957242913232.1", "issuebank": "UNKNOWN", "currency": "RUB", "ordernumber": "231020191345849_user2", "meansubtype": "" } }

A response example for an operation with additional authentication:

Code Block
language xml
{ "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": "BYN", "recommendation": "", "processingname": "Fake", "meannumber": "220000****0003", "orderstate": "In Process", "rate": "1", "amount": "15.00", "responsecode": "AS110", "meantypename": "MasterCard", "protocoltypename": "NET", "bankcountry": "UNKNOWN", "customer": { "lastname": "Testov", "firstname": "Тест", "middlename": "Testovich", "ipaddress": "10.10.10.10", "email": "null@assist.by" }, "cardholder": "TEST", "approvalcode": "", "billnumber": "5161957242913224.1", "issuebank": "UNKNOWN", "currency": "BYN", "ordernumber": "231020191345849_user1", "meansubtype": "" } }

Back on top