Home

Overview

Quick start

This guide shows the process of a frictionless authentication, using the Software Express 3DS Server REST interface.

What you'll need#

  • Active account on 3DS Server's homologation environment (obtained with our support team)
  • A tool capable of performing HTTP calls, such as Postman, REST Client or cURL

Creating the transaction#

Click here to see the full Open-API ("Swagger") file for 3DS

HTTP method: POST

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

Headers:

  • Content-Type: application/json
  • merchant_id: {your merchant id}
  • merchant_key: {your merchant key}

Request:

{
"cardholder":{
"acct":{
"number":"1234123412341234"
}
},
"brand_id":"2"
}
curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"cardholder":{
"acct":{
"number":"1234123412341234"
}
},
"brand_id":"2"
}
--verbose

Response:

{
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}

Learn more about this service.

Performing the authentication#

Click here to see the full Open-API ("Swagger") file for 3DS

HTTP Method: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/**{3DS Server transaction ID}**

Headers:

  • Content-Type: application/json
  • merchant_id: {your merchant id}
  • merchant_key: {your merchant key}

Request:

{
"three_ds_comp_ind":"Y",
"pay_token_ind":"false",
"notification_url":"https://www.requestor.com/notification",
"decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
"trans_type":"01",
"three_ds_requestor":{
"authentication_ind":"01",
"decoupled_max_time":"10",
"id":"id",
"name":"Loja de Testes",
"url":"https://www.requestor.com"
},
"acquirer":{
"bin":"2",
"merchant_id":"00000000"
},
"browser":{
"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip":"10.20.30.40",
"javascript_enabled":"true",
"java_enabled":"false",
"language":"pt-BR",
"color_depth":"24",
"screen_height":"864",
"screen_width":"1536",
"tz":"180",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder":{
"card_expiry_date":"2212",
"name":"Joaquim",
"acct":{
"type":"02",
"number":"1234123412341234"
}
},
"merchant":{
"mcc":"1234",
"country_code":"BRA",
"name":"Loja de Teste",
},
"message":{
"category":"01"
},
"purchase":{
"amount":"10000",
"currency":"986",
"exponent":"2",
"date":"date"
}
}
curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind":"Y",
"pay_token_ind":"false",
"notification_url":"https://www.requestor.com/notification",
"decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
"trans_type":"01",
"three_ds_requestor":{
"authentication_ind":"01",
"decoupled_max_time":"10",
"id":"id",
"name":"Loja de Testes",
"url":"https://www.requestor.com"
},
"acquirer":{
"bin":"2",
"merchant_id":"00000000"
},
"browser":{
"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip":"10.20.30.40",
"javascript_enabled":"true",
"java_enabled":"false",
"language":"pt-BR",
"color_depth":"24",
"screen_height":"864",
"screen_width":"1536",
"tz":"180",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder":{
"card_expiry_date":"2212",
"name":"Joaquim",
"acct":{
"type":"02",
"number":"1234123412341234"
}
},
"merchant":{
"mcc":"1234",
"country_code":"BRA",
"name":"Loja de Teste",
},
"message":{
"category":"01"
},
"purchase":{
"amount":"10000",
"currency":"986",
"exponent":"2",
"date":"date"
}
}
--verbose

Response:

{
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "Y"
},
"message_version": "2.2.0"
}

Learn more about this service.

Attention - About the new version "/3ds-server/v3" (in development):

Soon, Fiserv will launch a new version of the APIs (/3ds-server/v3) for 3DS usage, incorporating the HMAC (Hash-based Message Authentication Code) model for authentication, authorization, and integrity assurance of requests. The HMAC signature (generated hash) must be sent via the HTTP header "Authorization" and the HTTP header "Auth-Token-Type" should be added with HMAC as its value. The technical specification on how to generate the HMAC signature is available at the link: HMAC Generation.

Additionally, in this new version of the APIs (/3ds-server/v3), it will be necessary to include the HTTP header "Client-Request-Id", containing a UUID v4 (Universally Unique Identifier version 4), randomly generated according to RFC 4122 specifications, for unique identification of the request. To learn more about UUID v4, see: https://www.rfc-editor.org/rfc/rfc4122.

Comparison between versions:

Para /3ds-server/v2

Content-Type: application/json

merchant_id: {your merchant id}

merchant_key: {your merchant key}

Para /3ds-server/v3

Content-Type: application/json

Client-Request-Id: {UUID version 4}

Authorization: {HMAC signature}

Auth-Token-Type: HMAC

merchant_id: {your merchant id}

merchant_key: {your merchant key}