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", juntamente com a chave HMAC no header "api-key". A inclusão do header HTTP "Auth-Token-Type", com o valor "HMAC" também é necessária. A especificação técnica de como gerar a assinatura HMAC está disponível pelo link: Geracao de HMAC.

Para essa versão, os headers "merchant_id" e "merchant_key" são substituídos por "merchant-id" e "merchant-key", mantendo os mesmos valores.

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

api-key: HMAC key

merchant-id: {seu código de loja}

merchant-key: {chave da sua loja}