Autenticação 3DS

No contexto de autorização, também existem os eventos de autenticação 3DS. Estes eventos não fazem parte do processo de autorização de uma transação com um cartão, porém informam ao parceiro sobre a necessidade da criação de um desafio de autenticação para o prosseguimento de uma compra realizada pelo cliente.

É somente por meio do evento PREAUTHENTICATIONCHALLENGE_WAS_REQUESTED que o parceiro poderá obter o challengeId, identificador do desafio que deverá ser informado no endpoint de confirmação do desafio.

Para mais informações sobre quando essas mensagens são disparadas e sobre o seu conteúdo, consulte as páginas:

• Visão geral - Autenticação 3 DS;
• Confirmação do desafio.

Pré-requisitos

Para receber esses eventos, o parceiro deverá:

• Configurar previamente o recebedor de eventos do webhook.
• Conhecer a estrutura básica dos eventos que acompanha o objeto data.

Informações sobre os eventos

Contexto e nome do evento

Os campos context e name poderão variar de acordo com a tabela a seguir:

Identificador (entityId)

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.

No contexto de autorização, o entityId é o identificador único do desafio (challengeId).

Atualização do contrato: Operational.Flow3DS (data.error)

Com a implementação de melhorias no fluxo de autenticação 3DS no Autorizador, o objeto data.error passa a expor informações de erro e falhas ocorridas durante o processo de autenticação 3DS nos eventos de pré-autenticação.

Os novos campos permitem que consumidores identifiquem e monitorem problemas no fluxo 3DS, como erros de formato, falhas de componentes ou timeouts durante a comunicação com Directory Server (DS) ou Access Control Server (ACS).

Todos os campos do objeto data.error são opcionais (nullable) e somente serão preenchidos quando ocorrer erro durante o fluxo de autenticação 3DS.

Características do campo

Regras de presença

• O objeto data.error estará presente apenas nos eventos PRE_AUTHENTICATION_WAS_RECEIVED e PRE_AUTHENTICATION_CHALLENGE_WAS_REQUESTED quando ocorrer erro durante o fluxo de autenticação 3DS.
• Todos os campos do objeto data.error são nullable.
• O objeto data.error será preenchido apenas quando houver erro, falha ou timeout no processo de autenticação 3DS.
• Quando a autenticação 3DS ocorre com sucesso, o objeto data.error não estará presente (ausente/nulo).
• Campos individuais dentro de data.error podem ser nulos se a informação específica não estiver disponível.
• O Autorizador apenas propaga as informações de erro recebidas, sem inferir ou complementar valores ausentes.
• Integrações devem estar preparadas para consumir esse campo em todos os eventos documentados.

Exemplo de payload

{
  "name": "PRE_AUTHENTICATION_WAS_RECEIVED",
  "context": "Authorization",
  "data": {
    "holder": {
      "document": {
        "value": "12345678900"
      }
    },
    "card": {
      "proxy": "1234567890"
    },
    "channel": {
      "name": "3DS",
      "directoryServerTransactionID": "abc-123-def",
      "amount": {
        "value": 150.00,
        "currency": {
          "code": 986
        }
      },
      "merchant": {
        "name": "Loja X",
        "stateOrCountryCode": "BRA"
      }
    },
    "riskAnalysisResult": "DENIED",
    "error": {
      "code": "203",
      "component": "S",
      "description": "Data element not in the correct format",
      "detail": "Field dsTransID is invalid",
      "messageType": "AReq"
    }
  }
}

{
  "name": "PRE_AUTHENTICATION_WAS_RECEIVED",
  "context": "Authorization",
  "data": {
    "holder": {
      "document": {
        "value": "12345678900"
      }
    },
    "card": {
      "proxy": "1234567890"
    },
    "channel": {
      "name": "3DS",
      "directoryServerTransactionID": "abc-123-def",
      "amount": {
        "value": 150.00,
        "currency": {
          "code": 986
        }
      },
      "merchant": {
        "name": "Loja X",
        "stateOrCountryCode": "BRA"
      }
    },
    "riskAnalysisResult": "APPROVED"
  }
}

Compatibilidade

Esta alteração é compatível com versões anteriores do contrato. O objeto data.error é novo, todos os seus campos são opcionais e nullable, e não substitui nenhum campo existente — portanto não há quebra de contrato para integrações existentes.

Histórico de alterações

Dados dos eventos

PRE_AUTHENTICATION_WAS_RECEIVED

Esse evento sinaliza que, após receber uma solicitação de pré-autenticação 3DS, o Bankly realizou uma análise antifraude para identificar a necessidade de criação de um desafio por parte do parceiro.

Descrição do objeto data do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

{
      "entityId": "dcbf96e1-7595-4bbb-8692-48532c96f0b9",
      "companyKey": "COMPANY_KEY",
      "idempotencyKey": "dcbf96e1-7595-4bbb-8692-48532c96f0b9",
      "context": "Authorization",
      "name": "PRE_AUTHENTICATION_WAS_RECEIVED",
      "timestamp": "2023-01-19T18:09:57.2303277Z",
      "correlationId": "3ebd795e-2c4f-467d-b3e5-35099888445d",
      "data": {
         "transactionTimeStamp": "2023-01-19T18:09:57.2303514Z",
         "riskAnalysisResult": "CHALLENGE",
         "holder": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                  "ispb": "13140088",
                  "code": "332",
                  "name": "Acesso Soluções De Pagamento S.A."
               }
            }
         },
         "card": {
            "proxy": "2229041000032008041"
         },
         "channel": {
            "name": "3DS",
            "directoryServerTransactionID": "dcbf96e1-7595-4bbb-8692-48532c96f0b9",
            "merchant": {
               "name": "Editora Nísia Floresta",
               "stateOrCountryCode": "196"
            },
            "amount": {
               "value": 3,
               "currency": "BRL"
            }
         }
      }
   }

PRE_AUTHENTICATION_CHALLENGE_WAS_REQUESTED

Este evento sinaliza que um desafio foi requisitado. Após receber este evento, o parceiro deverá criar um desafio e enviá-lo a seu cliente para que ele possa confirmar a tentativa de compra.

Descrição do objeto data do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

{
      "entityId": "812ghb1-9jkb-4fda-94e1-06d49defdf67d",
      "companyKey": "COMPANY_KEY",
      "idempotencyKey": "902ghj8-9fdb-4fga-94e1-06d49ghbe67d",
      "context": "Authorization",
      "name": "PRE_AUTHENTICATION_CHALLENGE_WAS_REQUESTED",
      "timestamp": "2022-07-12T12:50:05.046+00:00",
      "correlationId": "f50d7f8-3iyt-4eac-83e9-c02e430b7836",
      "data": {
         "challengeId": "806tag8-9fdb-4wrf-94e1-06d49dhjk67d",
         "transactionTimeStamp": "2022-07-12T12:50:05.046+00:00",
         "expirationTimeStamp": "2022-07-12T13:00:05.08+00:00",
         "holder": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                  "ispb": "13140088",
                  "code": "332",
                  "name": "Acesso Soluções De Pagamento S.A."
               }
            }
         },
         "card": {
            "proxy": "1234567765432123"
         },
         "channel": {
            "name": "3DS",
            "directoryServerTransactionID": "812fab8-6fdb-4fda-94e1-06d49dfbe67d",
            "merchant": {
               "name": "Editora Nísia Floresta",
               "stateOrCountryCode": "196"
            },
            "amount": {
               "value": 3,
               "currency": "BRL"
            }
         }
      }
   }

Possíveis resultados da análise antifraude