Antifraude 3DS

O que é 3Ds ?

3DS (3D Secure) é um protocolo de autenticação utilizado em transações online com cartão, projetado para adicionar uma camada extra de segurança. Durante o processo de pagamento, o titular do cartão pode ser solicitado a realizar uma verificação adicional — como inserir uma senha, um código enviado por SMS ou autenticar via biometria — garantindo que a transação esteja sendo feita de forma legítima.

Como irá aparecer?

Cada banco emissor define como a autenticação 3DS será exibida para o usuário. Ela pode ocorrer de diferentes formas, como:

Redirecionamento para uma nova tela no navegador;

Notificação no aplicativo do banco;

Solicitação de código via token, SMS ou outro canal.

O tipo e o nível do desafio (senha, token, biometria, etc.) variam de acordo com a instituição financeira emissora do cartão.

Exemplo:

3ds-pagbank-3d-secure-pagseguro-token-aplicativo-app-jpg.webp

Objetivo do 3Ds?

O principal objetivo do 3DS é aumentar a segurança nas transações online com cartão, reduzindo o risco de fraudes e a ocorrência de chargebacks (estornos de pagamento).

Fluxo de execução do 3Ds.

Início da Transação

analyse_required = THREEDS

Gerar id no SDK 3Ds

Confirmar autenticação da transação

1. Início da Transação

Sempre que a rota de transações do cartão retornar o objeto "THREEDS" o fluxo do 3DS será obrigatório para conclusão do pagamento.

2. analyse_required = THREEDS

📌

Contém na resposta da Rota Transactions:
analyse_required = THREEDS

3. Gerar id no SDK 3Ds

Após identificar que a transação requer autenticação 3DS (analyse_required = THREEDS), é necessário integrar o SDK do 3DS no frontend da sua aplicação. O primeiro passo é gerar o ID de autenticação, que será utilizado posteriormente na comunicação com a API Paytime.

Esse ID é obtido ao configurar e executar o SDK do PagBank em sua aplicação. Para isso, é necessário:

Incluir o script do SDK na sua página.

Inicializar o SDK com a session obtida na criação da transação.

Montar e enviar os dados da transação usando o método PagSeguro.authenticate3DS.

O SDK retornará um id único e um status da autenticação, que devem ser enviados para a Paytime por meio da rota de autenticação antifraude.

Adicione e configure o SDK PagBank

Para que você utilize o sistema de validação do Pagbank você adicionará o SDK PagBank na sua aplicação. Dessa forma, a sua página terá acesso aos métodos de autenticação disponibilizados pelo PagBank.

Para utilizar o SDK do PagBank você deve incluir o script apresentado a seguir antes de fechar a tag <body> da sua página:

Depois de adicionar o SDK Pagbank a sua aplicação, você irá utilizar o método setUp. Você deve fornecer a session, criada utilizando o endpoint Criar sessão de autenticação 3DS e definir o ambiente que será utilizado através do parâmetro env, conforme demonstrado a seguir:

Parâmetro	definição
`session`	Define a Seção (máximo 30 minutos)
`env`	Ambiente: `PROD` ou`SANDBOX`

Monte o Payload abaixo com os dados a ser enviado para o SDK.

const request = {  
data: {  
customer: {  
  name: 'Jose da Silva',  
  mail: '[jose@gmail.com](mailto:jose@gmail.com)',  
phones: [  
      {  
        country: '55',  
        area: '11',  
        number: '999999999',  
        type: 'MOBILE'  
      },  
      {  
      country: '55',  
      area: '11',  
      number: '999999999',  
      type: 'HOME'  
      },  
      {  
      country: '55',  
      area: '11',  
      number: '999999999',  
      type: 'BUSINESS'  
      }  
    ]  
  },  
  paymentMethod: {  
    type: 'CREDIT_CARD',  
    installments: 1,  
    card: {  
    number: number,  
    expMonth: "02",  
    expYear: "2026",  
    holder: {  
    name: "Joao Silva"  
    }  
    }  
  },  
  amount: {  
  value: 500,  
  currency: 'BRL'  
  },  
  billingAddress: {  
  street: 'Av. Paulista',  
  number: '2073',  
  complement: 'Apto 100',  
  regionCode: 'SP',  
  country: 'BRA',  
  city: 'São Paulo',  
  postalCode: '01311300'  
  },  
  shippingAddress: {  
  street: 'Av. Paulista',  
  number: '2073',  
  complement: 'Apto 100',  
  regionCode: 'SP',  
  country: 'BRA',  
  city: 'São Paulo',  
  postalCode: '01311300'  
  },  
  dataOnly: false  
  }  
}

Após estruturar o Payload, adicione no método PagSeguro.authenticate3DS

Fazendo o método de Autenticação 3DS deverá retornar os seguintes parâmetros:

Cartões de Teste para o 3DS

Para testar os possíveis fluxos e retorno do 3DS em ambiente de desenvolvimento você poderá utilizar os cartões abaixo:

Bandeira	Card Number	Response
Visa	4000000000002701	Internal 3DS authenticated without challenge e charges.status = PAID e charges.threeds.status = AUTHENTICATED
Mastercard	5200000000001005	Mesmo do acima
Visa	4000000000002503	Internal 3DS authenticated with challenge e charges.status = PAID e charges.threeds.status = AUTHENTICATED
Mastercard	5200000000001096	Mesmo do acima
Visa	4000000000002925	Internal 3DS Unauthenticated unchallenged e charges.status = PAID e charges.threeds.status = NOT_AUTHENTICATED
Mastercard	5200000000001013	Mesmo do acima
Visa	4000000000002370	Internal 3DS Unauthenticated with challenge e charges.status = PAID e charges.threeds.status = NOT_AUTHENTICATED
Mastercard	5200000000001104	Mesmo do acima

Confirmar Autenticação

Para finalizar a transação basta enviar os parâmetros retornados na autenticação, para que finalizemos o processamento da mesma:

Método Finalizar Transação 3DS

O que é 3Ds ?#

Como irá aparecer?#

Objetivo do 3Ds?#

Fluxo de execução do 3Ds.#

1. Início da Transação#

2. analyse_required = THREEDS#

3. Gerar id no SDK 3Ds#

Adicione e configure o SDK PagBank#

Monte o Payload abaixo com os dados a ser enviado para o SDK.#

Após estruturar o Payload, adicione no método PagSeguro.authenticate3DS#

Cartões de Teste para o 3DS#

Confirmar Autenticação#