Criando e pagando com autenticação 3DS - Validação interna

O 3DS (3-Domain Secure) é um protocolo de segurança para transações financeiras realizadas no comércio eletrônico com o objetivo de autenticar e fornecer ao usuário uma boa experiência de compra.

Para integradores PagSeguro, que desejam realizar cobranças mais seguras e evitar os custos com chargeback em possíveis transações fraudulentas, o 3DS PagSeguro é uma solução que permite o envio das transações para autenticação via PagSeguro.

Existem dois tipos de autenticação:

Sem desafio (sem atrito): quando o banco emissor entende que as informações fornecidas são suficientes para autenticar o consumidor
Com desafio (com atrito): quando é necessária uma etapa de validação adicional, uma ação que o consumidor precisa realizar, por exemplo fornecer algum dado enviado via SMS ou a abertura do aplicativo para confirmação da compra. A decisão sobre a aplicação do desafio, o tipo e a tela de desafio no checkout são de responsabilidade do banco emissor do cartão.

JavaScript PagSeguro

Essa SDK é responsável por oferecer a funcionalidade de autenticação 3DS pelo PagSeguro.

🚧

IMPORTANTE

Antes de utilizar a SDK, devem ser geradas uma chave pública e uma sessão conforme os exemplos disponibilizados nesta documentação.

Utilizando a SDK

Para utilizar a SDK de autenticação serão necessários 4 passos:

1. Importar a SDK
2. Configurar a SDK
3. Montar o objeto de request
4. Chamar o método de autenticação da SDK

1. Importar a SDK

Para importar a SDK você deve adicionar a seguinte tag em seu arquivo HTML:

<script src="https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js"></script>

🚧

IMPORTANTE

Caso você faça algum controle de acesso por domínios na sua aplicação, é necessário permitir a execução de js e abertura de iframe de domínio "*.cardinalcommerce.com"

2. Configurar a SDK

Para configurar a SDK é necessário criar uma chave pública e em seguida gerar uma sessão, como exemplificado em Criar suas chaves públicas e Criar uma sessão desta documentação. Em seguida, você deve chamar o método setUp e informar a sessão e o ambiente a serem utilizados.

PagSeguro.setUp({
    session: 'SUA_SESSAO',
    env: 'ENV'
});

🚧

Sessão expirada

Caso a sessão expire durante o fluxo, deve ser gerada uma nova sessão e chamar novamente o método setUp:

PagSeguro.setUp({
    session: 'SUA_NOVA_SESSAO',
});

3. Montar o objeto de request

Para realizar a autenticação você precisará criar uma request informando os dados da compra:

Caso você utilize a função beforeChallenge você receberá um parâmetro nessa função que contém os seguintes atributos:

4. Chamar o método de autenticação da SDK

Chamar o método authenticate3DS com a request montada e tratar o retorno.

 const request = {
                data: {
                    customer: {
                        name: 'Jose da Silva',
                        email: '[email protected]',
                        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: 'DEBIT_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
                }
            }
            PagSeguro.setUp({
                session: document.querySelector('SUA_SESSAO').value,
                env: document.querySelector('ENV').value
            });
            PagSeguro.authenticate3DS(request).then( result => {
                this.logResponseToScreen(result);
                this.stopLoading();
            }).catch((err) => {         
                if(err instanceof PagSeguro.PagSeguroError ) {
                    console.log(err);
                    console.log(err.detail);
                    this.stopLoading();
                }           
            })

O método authenticate3DS retorna uma Promise. Caso a Promisse conclua com sucesso (seja resolvida), o método then é acionado com objeto contendo os seguintes atributos:

Exemplo dos possíveis retornos e tomadas de decisão:

📘

DECISÃO NO BACKEND

Os exemplos estão apenas ilustrando o uso dos dados, é recomendado que a decisão do que fazer com o resultado da autenticação seja tomada no backend.

Ao receber o retorno com status AUTH_FLOW_COMPLETED, uma cobrança deve ser criada utilizando o ID informado conforme a documentação Criar um pagamento com autenticação 3DS.

PagSeguro.authenticate3DS(request).then(result => {
  let authenticationStatus = result.status;
     
  switch (authenticationStatus) {
    case 'AUTH_FLOW_COMPLETED':
      let authenticationId = result.id;  // Seguir o fluxo para cobrança repassando o authenticationId para a API de Cobrança.
      break;
    case 'AUTH_NOT_SUPPORTED':   // Cartão não elegível ao 3DS. Para o meio de pagamento `DÉBITO` a transação deve ser finalizada após este retorno.
      break;
    case 'CHANGE_PAYMENT_METHOD':  // Solicite que o comprador troque o meio de pagamento, pois o mesmo não será aceito na cobrança.
      break;
  }
}).catch(err => {
  if (err instanceof PagSeguro.PagSeguroError) {   // No objeto de err podem ser encontrados mais detalhes sobre o erro.
    let traceId = err.details.traceId;
  }
});

Caso a Promisse conclua com erro (seja rejeitada), o método catch é acionado com um erro contendo um atributo chamado detail.

Erros em geral:

{
    httpStatus: 403,
    traceId: "afef73f5c5738c2b",
    message: "Expired session. Create a new session and call PagSeguro.setUp({ session: 'YOUR_NEW_SESSION'})"
}

Erros de validação (400 Bad Request):

{
    httpStatus: 400,
    traceId: "ad05751ed04291e3",
    message: "Invalid request parameters",
    errorMessages: [
        {
            code: "40002",
            description: "must be a well-formed email address",
            parameterName: "customer.email"
        },
        {
            code: "40001",
            description: "required parameter",
            parameterName: "billingAddress.regionCode"
        }
    ]
}

Cenários de teste

📘

Cartões de teste

Por se tratar de um ambiente controlado, devem ser informados os seguintes valores para simular diferentes cenários no ambiente Sandbox:

Status atuais