Home

Overview

3DS Server

Overview#

To make 3DS 2.0 authentication transactions, it's necessary to integrate with a 3DS Server application, as the one provided by FIRSEV. This application communicates with the brand and the issuer to authenticate the cardholder, reducing fraud occurrences and allowing payments with debit cards. It is independent of the payment application, and the integrator will have to perform and manage the orchestration in their application.

This model requires a greater integration effort (API integration is necessary), but it allows for greater flexibility in the payment flow (managed by the merchant), and the payment checkout is from the merchant itself.

The 3DS 2.0 protocol differs from it's 1.0 version in the possibility of having a frictionless authentication, which is a process that doesn't require additional interactions from the customer.

This documentation is focused on the interactions with the 3DS Server. For further information about the other components of the flow, refer to the EMVCo official documents.

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more

Communication#

To make a Web Service transaction, the whole communication must be done via HTTPS/TLS. It's important that the merchant's server supports encryption of a minimum of 128 bits. The merchant's server must make calls on specific addresses to do REST transactions.

Each service must be called using the base URL concatenated with the desired resource (see the chapter related to the service to be consumed). The HTTP method (GET, POST or PUT) indicates the expected action on the selected resource. Listed below are the 3DS Server base URLs:

Production base URL:

https://3ds.softwareexpress.com.br/

Homologation base URL:

https://mpi-homolog.softwareexpress.com.br/3ds-server/

Every call received by the services will be responded synchronously.

Attention:

Never use the IP instead of the 3ds.softwareexpress.com.br domain. The IP can change at any time without previous warning, so it's important to use the domain when accessing 3DS Server.

During card validation, it is possible to receive error code 305, indicating that the card is not within the range of supported cards for 3DS 2.0 authentication by the issuer, thus preventing the authentication process from taking place. The decision to cancel the transaction or proceed with the payment without using 3DS lies with the 3DS Requestor.

Important:

Besides the response parameters of the services described in this specification, 3DS Server can return other parameters without previous warning.

It's important that the application is prepared to receive the unknown parameters besides the fields already specified and simply ignore them.

Flows#

The 3DS 2.0 protocol has 2 main flows:

  • Frictionless: the whole authentication is performed without requiring additional interactions from the customer.
  • Challenge: the information collected by the issuer are not enough to authenticate the cardholder. Thus, the customer must provide more data, directly on the issuer's site.

Glossary:

  • 3DS Requestor: merchant or gateway (like Carat Portal)
  • DS: Directory Server; represents the brand
  • ACS: Access Control Server; represents the issuer
  • AReq: Authentication Request, as described on the 3DS 2.0 protocol
  • ARes: Authentication Response, as described on the 3DS 2.0 protocol
  • CReq: Challenge Request, as described on the 3DS 2.0 protocol
  • CRes: Challenge Response, as described on the 3DS 2.0 protocol
  • RReq: Results Request, as described on the 3DS 2.0 protocol
  • RRes: Results Response, as described on the 3DS 2.0 protocol

Frictionless Flow#

  1. 3DS Requestor creates the authentication transaction on 3DS Server, passing the customer's card number and its brand ID.
  2. 3DS Server validates whether the received card can be authenticated by the indicated brand. If positive, returns the 3DS Server transaction ID (three_ds_server.trans_id) and the 3DS Method URL (three_ds_method_url) corresponding to the card.
  3. The 3DS Method URL must be displayed on the customer's browser in an "invisible" 1 pixel frame.
  4. This will allow ACS to gather cardholder's device information directly.
  5. 3DS Requestor sends information for performing the authentication.
  6. 3DS Server generates an AReq and sends it to DS, which will then propagate it to ACS. The authentication result is returned to 3DS Server as content from ARes.
  7. If authentication is successful, the status (field three_ds_server.status) will be returned with a value of Y. The following fields should be sent to the acquirer: ECI (field eci), CAVV (field authentication.value), and reference_id (field ds.transId).

Recommended:

To improve performance and enable background data collection, we recommend performing steps 1 and 4 immediately after card filling, instead of waiting to execute everything all at once.

Frictionless payment authorization flow.#

Attention::

In the Frictionless flow, during step 1 of authentication in the transaction creation service on the 3DS Server, the reference_id (transaction ID three_ds_server.trans_id) is returned. In the authentication service return on the 3DS Server, the eci (Electronic Commerce Indicator) field and the authentication.value field (CAVV) are returned. It is the responsibility of the merchant's application to merchant this information and pass it on to the payment fulfillment service in the second step as shown above.

  • In step 2 of the authorization, the merchant's application creates the transaction in Carat, passing information such as store code, installment number, and order code, and obtains a response with a NIT (Transaction Identifier Number). Learn more.
  • With the information obtained from the transaction creation service in Carat, the merchant's application then proceeds to consume the payment fulfillment service, providing the NIT, buyer's card details, ECI (eci field), CAVV (authentication.value field), and the reference_id (3DS Server transaction ID ds.trans_id). In case of success, the payment transaction status will change to CONF (confirmed). Learn more.

Challenge Flow#

The steps 1 through 6 are the same as in the frictionless flow.

  1. The following information will be returned: status (three_ds_server.status field) with value C and the challenge URL (acs.url field) and the reference_id (field ds.transId), which is the last field that should be sent to the acquirer.
  2. 3DS Requestor prepares the CReq to be submitted from the customer's browser to the challenge URL.
  3. ACS displays its challenge screen so that the cardholder provides more information. Note that multiple interactions may be necessary to conclude this process.
  4. ACS sends RReq to DS, which will then propagate it to 3DS Server. This call is a notification informing the authentication result.
  5. ACS sends CRes to 3DS Requestor in its URL informed in step 5 (notification_url field). This object contains the 3DS Server transaction ID.
  6. 3DS Requestor queries the 3DS Server transaction to obtain the authentication result.
  7. 3DS Server returns the transaction information.

Challenge flow with payment authorization.#

Attention:

In the Challenge flow, during step 1 of authentication in the transaction creation service on the 3DS Server, the reference_id (transaction ID ds.trans_id) is returned. After the challenge, it is necessary to query the 3DS Server's inquiry service to obtain authentication information, returning the ECI (Electronic Commerce Indicator) field and the authentication.value field (CAVV). It is the responsibility of the merchant's application to merchant this information and pass it on to the service responsible for payment fulfillment.

  • In step 2 of the authentication, the merchant's application creates the transaction, providing information such as merchant code, installment number, and order code, and receives a response with a NIT (Transaction Identifier Number). Learn more.
  • With the information obtained from the transaction creation service in Carat, the merchant's application then proceeds to consume the payment fulfillment service, providing the NIT, buyer's card details, ECI (eci field), CAVV (authentication.value field), and the reference_id (3DS Server transaction ID ds.trans_id). In case of success, the payment transaction status will change to CONF (confirmed). Learn more.