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, compaymentMethod.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 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 objetothreeDS (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)
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:
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
Qual forma devo escolher?
Qual forma devo escolher?
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.
Preciso de 3DS no Apple Pay?
Preciso de 3DS no Apple Pay?
Não. No Apple Pay a autenticação já vem no token, e o 3DS não se aplica.
O cliente sempre vê uma tela do banco?
O cliente sempre vê uma tela do banco?
Não. No fluxo sem fricção (
frictionless), o emissor aprova sem interação. O desafio (challenge) só aparece quando o emissor pede.Posso usar 3DS com cartão salvo?
Posso usar 3DS com cartão salvo?
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 casos3ds_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.

