Home

Visão Geral

Quick start

Este guia mostra o processo de uma autenticação frictionless, utilizando a interface web service REST do 3DS Server da Software Express.

O que você precisará#

  • Cadastro ativo no ambiente de homologação do 3DS Server (obtido com nossa equipe de suporte)
  • Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a transação#

Clique aqui para ver o arquivo completo Open-API ("Swagger") para o 3DS

Tipo de requisição: POST

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

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja}
  • merchant_key: {chave da sua loja}

Requisição:

{
"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

Resposta:

{
"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"
}

Saiba mais sobre esse serviço.

Fazendo a autenticação#

Clique aqui para ver o arquivo completo Open-API ("Swagger") para o 3DS

Tipo de requisição: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/**{ID da transação 3DS Server}**

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja}
  • merchant_key: {chave da sua loja}

Requisição:

{
"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

Resposta:

{
"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"
}

Saiba mais sobre esse serviço.

Atenção - Sobre a nova versão "/3ds-server/v3" (em desenvolvimento):

Em breve, a Fiserv lançará uma nova versão das APIs (/3ds-server/v3) para utilização do 3DS, incorporando o modelo HMAC (Hash-based Message Authentication Code) para autenticação, autorização e garantia de integridade das requisições. A assinatura HMAC (hash gerado) deverá ser enviada por meio do header HTTP "Authorization" e a inclusão do header HTTP "Auth-Token-Type", com o valor HMAC. A especificação técnica de como gerar a assinatura HMAC está disponível pelo link: Geracao de HMAC.

Além disso, nessa nova versão das APIs (/3ds-server/v3), será necessário incluir o header HTTP "Client-Request-Id", contendo um UUID v4 (Universally Unique Identifier versão 4), gerado aleatoriamente conforme a especificação RFC 4122, para identificação única da requisição. Para saber mais sobre o UUID v4 ver: https://www.rfc-editor.org/rfc/rfc4122.

Comparação entre versões:

Para /3ds-server/v2

Content-Type: application/json

merchant_id: {seu código de loja}

merchant_key: {chave da sua loja}

Para /3ds-server/v3

Content-Type: application/json

Client-Request-Id: {UUID versão 4}

Authorization: {HMAC signature}

Auth-Token-Type: HMAC

merchant_id: {seu código de loja}

merchant_key: {chave da sua loja}