Skip to main content
O 3D Secure (3DS) é uma etapa de autenticação do titular do cartão feita pelo banco emissor durante a compra online. Antes de a cobrança ser processada, o banco confere se quem está comprando é mesmo o dono do cartão. Às vezes isso acontece sem o cliente perceber (fluxo sem fricção, frictionless); outras vezes o banco pede uma confirmação, como um código enviado por SMS ou uma aprovação no app do banco (desafio, challenge).
Para o negócio: o 3DS acrescenta uma confirmação do titular do cartão na compra. Quando a configuração da sua conta exige 3DS, a cobrança de cartão só segue com a autenticação bem-sucedida (state success); sem ela, a cobrança é recusada. Converse com o time Finvia para saber se o 3DS é exigido no seu perfil.

Quando usar

Termos que aparecem nesta seção

O desenho abaixo mostra o caminho de uma autenticação 3DS, com e sem desafio, e o que acontece com a cobrança em cada resultado. O fingerprinting e o desafio só acontecem quando o emissor pede. No 3DS gerenciado, a página da Finvia conduz essas telas. No SDK, o próprio SDK faz isso dentro do seu checkout. No 3DS via API, quem exibe os iframes é o seu checkout.

As três formas de integrar

3DS gerenciado

Você cria a cobrança com threeDSMode: "managed", abre a authenticationUrl para o comprador e acompanha o resultado.

SDK de segurança

Um SDK no front-end faz a autenticação completa e devolve o resultado para a cobrança.

3DS via API

Você conduz cada etapa pelas rotas de 3DS e monta o objeto threeDS.

Como cada forma funciona

3DS gerenciado. Você cria a cobrança normalmente, com paymentMethod.threeDSMode managed e o objeto browser com os dados do navegador. Se o banco aprova sem interação, a resposta já traz o status final. Se o banco pede verificação ou desafio, a cobrança fica em authentication_required e a resposta traz a authenticationUrl, que você abre para o comprador (modal, iframe ou nova aba). A página da Finvia conduz a autenticação e conclui a cobrança, e o resultado chega pelos webhooks ou por GET /v1/charges/{id}. O comprador não volta automaticamente para a loja ao final. SDK de segurança. No seu checkout, o SDK @fastpaybr/security-sdk (publicado com o nome anterior da marca) faz o fluxo inteiro com o método process(): coleta de dados do navegador, desafio em um modal quando o emissor pede, e resultado final. Você envia esse resultado no campo paymentMethod.threeDS de POST /v1/charges. 3DS via API (BYO, bring your own). Você chama as rotas de 3DS uma a uma (POST /v1/three-ds/authenticate, submit, challenge-result), exibe os iframes de fingerprinting e de desafio no seu front-end e monta o objeto threeDS para a cobrança.

Comparativo

Para o desenvolvedor: em todas as formas, a cobrança continua sendo criada pelo seu backend com a chave secreta. A chave pública (pk_) é usada apenas nas etapas de autenticação que rodam no navegador.
Para escolher a forma de integrar, siga as perguntas do desenho abaixo. Nas três formas, a cobrança é criada pelo seu backend com a chave secreta. A diferença está em quem conduz as telas e em que momento a cobrança nasce.

Resultado da autenticação

No SDK e no 3DS via API, o resultado de uma autenticação 3DS é o objeto threeDS (schema CreditCardThreeDS), que você envia em POST /v1/charges. Os campos type e state são obrigatórios. Nos demais, omita o campo quando não tiver valor e não envie null.
O schema também lista mode, deviceData e challenge.returnUrl. Não envie esses campos: mode é de uso interno, e deviceData e challenge.returnUrl não são lidos no 3DS da Finvia.

Estados (state)

Quando o 3DS é exigido pela configuração da sua conta, só state success permite que a cobrança siga. Qualquer outro estado leva à recusa.

ECI

Esses são os valores comuns citados no contrato.

O que acontece se o 3DS faltar

As validações abaixo só valem quando o 3DS é obrigatório para a sua conta. Nos outros casos, os dados 3DS enviados são repassados sem validação. Trecho da resposta de uma cobrança recusada por falta de 3DS:
A recusa vem na resposta da criação da cobrança e também no webhook charge.refused (ou charge.failed), enviado aos seus endpoints e à postbackUrl da cobrança (Webhooks de cobrança). O texto de reason mistura português e inglês e aparece aqui exatamente como a API devolve. Trate pelo prefixo (3ds_required, 3ds_failed, 3ds_incomplete).

Perguntas frequentes

Se você quer usar um componente pronto no navegador, que conduz fingerprinting e desafio, use o SDK. Se você quer delegar as telas de autenticação à Finvia e pode acompanhar o resultado por webhook, sem volta automática do comprador para a loja, use o 3DS gerenciado. Se precisa controlar cada tela e cada etapa, use o 3DS via API.
Não. No Apple Pay a autenticação já vem no token, e o 3DS não se aplica.
Não. No fluxo sem fricção (frictionless), o emissor aprova sem interação. O desafio (challenge) só aparece quando o emissor pede.
Sim. A variante de cartão salvo aceita threeDSMode, browser e threeDS, com as mesmas regras do cartão digitado.

Como testar

O roteiro de homologação informa que o 3D Secure, quando se aplica ao seu perfil, é coberto em um cenário específico da sua conta. Combine esse cenário com o time Finvia e, nos testes de cartão (CHG-01 a CHG-03), confira também os casos 3ds_required e de state diferente de success.

Veja também

3DS gerenciado

Fluxo com threeDSMode e resume-3ds.

SDK de segurança

Autenticação completa no front-end.

3DS via API

Rotas de autenticação passo a passo.

Cartão de crédito

Cobrança com cartão digitado.