threeDS. É o mesmo fluxo que o SDK faz por dentro, com controle total sobre cada tela.
Para o negócio: esta forma dá ao seu time controle completo sobre a experiência do checkout durante a autenticação, ao custo de mais desenvolvimento. Se esse controle não for necessário, o SDK entrega o mesmo resultado com menos código.
Quando usar
As rotas
Todas as rotas de 3DS usam a chave pública (pk_) no cabeçalho Basic, porque são chamadas a partir do navegador.
Como funciona
O desenho abaixo mostra a sequência completa de chamadas, com os dois passos que só acontecem quando o emissor pede: a verificação do dispositivo e o desafio. As mensagenspostMessage chegam com o type completo (3ds-authentication-fingerprinting-complete e 3ds-authentication-challenge-complete). O status da mensagem de fim do desafio é só informativo: o resultado que vale é o de challenge-result.
1
Inicie a autenticação
O navegador chama
POST /v1/three-ds/authenticate com valor, moeda, dados do cartão e dados do navegador. A resposta traz o authenticationId e o status.2
Verificação do dispositivo em iframe oculto
Se o
status for requires_submission com fingerprintingUrl, carregue essa URL em um iframe oculto e aguarde a mensagem 3ds-authentication-fingerprinting-complete, com o fingerprintingResult. Se ela não chegar em cerca de 60 segundos, siga sem ele.3
Envie a autenticação
Chame
POST /v1/three-ds/submit com o authenticationId e, se houver, o fingerprintingResult. Se o status era requires_submission sem fingerprintingUrl, chame o submit direto. A resposta traz o novo status.4
Desafio em iframe visível
Se o
status for requires_challenge (vindo do authenticate ou do submit), carregue a challengeUrl em um iframe visível em até 30 segundos. O cliente confirma a compra na tela do banco, e a página avisa o fim com a mensagem 3ds-authentication-challenge-complete.5
Busque o resultado
Depois da mensagem de fim do desafio, ou quando
authenticate ou submit já devolveram status final, chame POST /v1/three-ds/challenge-result com o authenticationId. A resposta traz state, cryptogram, eci, version e os IDs da transação.6
Crie a cobrança com threeDS
O seu backend chama
POST /v1/charges com o resultado em paymentMethod.threeDS, usando a chave secreta.Status da autenticação
Em estados finais, a resposta pode trazer
outcome, com um destes valores: authenticated, informational, attempt_acknowledged, rejected, denied, abandoned, not_supported, processing_error, internal_error ou canceled.
Os
status acima são da autenticação, não da cobrança. A cobrança só é criada no fim, com o state devolvido por challenge-result.status da autenticação.
Se authenticate ou submit devolverem processing, aguarde antes de seguir. O cancelamento só vale para autenticações em requires_submission ou requires_challenge.
Regras de negócio
Passo a passo
Os exemplos usamfetch no navegador com a chave pública. Defina uma função auxiliar:
1. Inicie a autenticação
200:
2. Faça a verificação do dispositivo em um iframe oculto
Se ostatus for requires_submission e vier fingerprintingUrl, carregue a URL em um iframe oculto. Quando a coleta termina, a página do provedor de 3DS envia à sua janela, por postMessage, esta mensagem:
fingerprintingResult é um texto em Base64 que você repassa ao submit sem alterar.
3. Envie a autenticação
200:
submit devolve um destes status: requires_challenge, succeeded, failed, error ou processing.
4. Mostre o desafio em um iframe visível
Quando ostatus é requires_challenge, a challengeUrl (que pode vir tanto do authenticate quanto do submit) precisa ser exibida ao cliente em um iframe visível, em até 30 segundos.
- Não use o atributo
sandboxno iframe. Alguns emissores falham com ele. - Tamanhos recomendados: 250×400, 390×400, 500×600, 600×400 ou tela cheia.
- Espere no máximo cerca de 10 minutos. Depois disso, cancele a autenticação.
postMessage:
status da mensagem pode ser succeeded, failed, error ou canceled. Ele é só informativo: o resultado que vale é o devolvido por challenge-result no passo 5.
Neste fluxo não há redirecionamento: o fim do desafio é avisado só pela mensagem
postMessage. Os campos challenge.returnUrl e deviceData do objeto threeDS não se aplicam ao 3DS da Finvia (SDK, via API ou gerenciado) e são ignorados. Não é preciso enviá-los.200:
5. Busque o resultado
Depois da mensagem de fim do desafio, ou quandoauthenticate ou submit já devolveram status final (succeeded, failed, error ou canceled), busque o resultado:
200:
6. Crie a cobrança com o objeto threeDS
O navegador envia o resultado ao seu backend, que cria a cobrança com a chave secreta. O objeto devolvido porchallenge-result vai em paymentMethod.threeDS.
A resposta de
challenge-result nunca traz campos com null: quando não há valor (por exemplo, cryptogram numa autenticação sem sucesso), o campo fica ausente. Repasse o objeto como veio. O objeto threeDS da cobrança exige type e state; com state success, cryptogram e eci são, na prática, obrigatórios. Nos campos opcionais, omita o campo quando não tiver valor e não envie null. Não envie mode, que é de uso interno.id, status (paid, refused ou failed), paymentDetails e reason.
Erros comuns
Perguntas frequentes
Sempre vai ter fingerprinting e desafio?
Sempre vai ter fingerprinting e desafio?
Não. A resposta de
authenticate pode trazer fingerprintingUrl, challengeUrl ou nenhum dos dois, conforme o emissor. Trate cada caso pelo status.Qual a diferença entre status, outcome e state?
Qual a diferença entre status, outcome e state?
status mostra em que etapa a autenticação está. outcome aparece nos estados finais e detalha como ela terminou. state é o resultado devolvido por challenge-result, usado no objeto threeDS da cobrança.Posso chamar as rotas de 3DS pelo backend?
Posso chamar as rotas de 3DS pelo backend?
As rotas usam a chave pública e foram desenhadas para o navegador, que exibe os iframes. A criação da cobrança, essa sim, é sempre feita pelo backend, com a chave secreta.
Para que serve challenge.returnUrl?
Para que serve challenge.returnUrl?
No 3DS da Finvia, esse campo não tem uso. O fim do desafio é avisado pela mensagem
postMessage, sem redirecionamento. Os campos challenge.returnUrl e deviceData são ignorados; não é preciso enviá-los.Uso o mesmo resultado em mais de uma cobrança?
Uso o mesmo resultado em mais de uma cobrança?
A documentação não prevê isso. Faça uma autenticação para cada cobrança.
Como testar
O 3D Secure é homologado em um cenário específico da sua conta, conforme o roteiro de homologação. Inclua no teste os caminhos com e sem fingerprinting, com e sem desafio, o cancelamento e a cobrança comstate success.
Veja também
Iniciar autenticação
Referência de
POST /v1/three-ds/authenticate.Resultado do desafio
Referência de
POST /v1/three-ds/challenge-result.SDK de segurança
O mesmo fluxo com menos código.
3D Secure: visão geral
Estados, ECI e comparativo.

