threeDSMode: "managed" e os dados do navegador do comprador. Quando o banco emissor pede uma verificação, a resposta traz uma authenticationUrl: você abre esse endereço para o comprador, e a página da Finvia faz a verificação do dispositivo, mostra o desafio do banco e conclui a cobrança. O resultado chega pelos webhooks e pela consulta da cobrança.
Para o negócio: é a forma de 3DS com menos trabalho no checkout. A cobrança existe desde o início, com um
id que você grava no pedido, e só é processada depois que o comprador conclui a autenticação. O comprador não volta sozinho para a loja ao final: o seu checkout precisa abrir a página de autenticação e acompanhar o resultado.Quando usar
Como funciona
O primeiro desenho mostra o que pode voltar na resposta da criação, conforme a política de 3DS da conta e a decisão do banco. Só o caminho que termina emauthentication_required exige que o comprador abra a página de autenticação. Nos outros, a resposta já traz o status final.
O segundo desenho mostra esse caminho com autenticação, da criação da cobrança ao resultado.
As chamadas challenge-result e resume-3ds são feitas pela própria página de autenticação. A sua integração só cria a cobrança, abre a página e acompanha o resultado.
1
Crie a cobrança
O seu backend chama
POST /v1/charges com a chave secreta, cartão, paymentMethod.threeDSMode: "managed" e paymentMethod.browser. Não envie threeDS.2
A Finvia decide se o 3DS começa
O 3DS só é iniciado quando a política de 3DS da sua conta dispara: 3DS habilitado e obrigatório, ou valor da cobrança igual ou acima do mínimo configurado para a conta.
3
Leia a resposta
Se o banco aprova sem interação (autenticação sem atrito, ou frictionless), a resposta já traz o status final da cobrança. Se o banco pede verificação de dispositivo ou desafio, a resposta é
201 com status authentication_required, reason Autenticação 3DS gerenciada necessária, paymentDetails null e o campo authenticationUrl.4
Leve o comprador à authenticationUrl
Abra o endereço recebido em um modal com iframe, em um iframe na página, em uma nova aba ou janela, ou redirecione na mesma aba. Use o valor exatamente como veio.
5
A página conduz a autenticação
A página de autenticação faz a verificação do dispositivo e o desafio do banco emissor. Ao final, ela mesma busca o resultado e retoma a cobrança (
POST /v1/three-ds/challenge-result e POST /v1/charges/{id}/resume-3ds). Você não chama essas rotas.6
Receba o resultado
O resultado chega pelos webhooks da cobrança e pelo postback na
postbackUrl: charge.paid, charge.pending, charge.refused ou charge.failed. Você também pode consultar GET /v1/charges/{id}.7
Trate o abandono
Se o comprador não concluir, a cobrança continua em
authentication_required, sem expiração automática e sem webhook. Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra.Regras de negócio
Passo a passo
1. Colete os dados do navegador
2. Crie a cobrança no backend
201 quando o banco pede verificação ou desafio:
authenticationUrl no exemplo é ilustrativo. Use sempre o endereço que vier na resposta: o host pode mudar, e a URL carrega parâmetros da autenticação que não devem ser alterados.
Quando o banco aprova sem interação, a mesma chamada devolve direto o status final (por exemplo,
paid), sem authenticationUrl. Trate os dois casos no seu código.3. Abra a página de autenticação
Envie aauthenticationUrl ao front-end e abra para o comprador. A página aceita ser exibida em iframe.
window.open(authenticationUrl, '_blank')) ou redirecione a aba atual. No redirecionamento, o comprador não volta sozinho para a loja: ele fica na página de autenticação ao final.
A página de autenticação ainda exibe o logotipo e o rodapé com o nome anterior da marca. Isso é esperado.
4. Acompanhe o resultado
Ao concluir a autenticação, a página retoma a cobrança e a Finvia envia o evento correspondente aos seus endpoints de webhook e àpostbackUrl da cobrança:
No front-end, enquanto o modal está aberto, consulte o seu backend para saber se o webhook já chegou. No backend, você pode confirmar com a consulta da cobrança:
authentication_required, feche o modal e mostre o resultado ao comprador.
5. Trate o abandono
Erros comuns
Perguntas frequentes
Preciso chamar resume-3ds ou challenge-result?
Preciso chamar resume-3ds ou challenge-result?
Não. No 3DS gerenciado, a página aberta pela
authenticationUrl faz essas chamadas. A sua integração só cria a cobrança, abre a página e acompanha o resultado.Toda cobrança com threeDSMode managed vai para authentication_required?
Toda cobrança com threeDSMode managed vai para authentication_required?
Não. Isso só acontece quando a política de 3DS da conta dispara e o banco pede verificação de dispositivo ou desafio. Na autenticação sem atrito, a resposta já traz o status final. Sem os dados do navegador ou com falha do serviço de 3DS, a cobrança segue sem 3DS, ou é recusada se o 3DS for obrigatório para a conta.
Posso montar a authenticationUrl no meu código?
Posso montar a authenticationUrl no meu código?
Não. Use o valor recebido na resposta, sem alterar. O host e os parâmetros são definidos pela Finvia e podem mudar.
O comprador volta para a minha loja ao final?
O comprador volta para a minha loja ao final?
Não. A página de autenticação não redireciona para o seu site. Por isso, a recomendação é abrir a página em modal, iframe ou nova aba e acompanhar o resultado por webhook ou consulta.
Quanto tempo o comprador tem para concluir?
Quanto tempo o comprador tem para concluir?
Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra.
Posso usar o 3DS gerenciado com cartão salvo?
Posso usar o 3DS gerenciado com cartão salvo?
Sim. A variante de cartão salvo aceita
threeDSMode managed, com browser junto.Como testar
O 3D Secure é homologado em um cenário específico da sua conta, conforme o roteiro de homologação. Inclua no teste: criação comthreeDSMode managed que volte authentication_required com authenticationUrl, autenticação concluída na página com o webhook charge.paid recebido, e o tratamento de uma cobrança abandonada em authentication_required.
Veja também
3D Secure: visão geral
Comparativo das três formas de integrar.
Criar uma cobrança
Campos
threeDSMode, browser e authenticationUrl.Webhooks de cobrança
Eventos que trazem o resultado.
Retomar cobrança
Rota usada pela página de autenticação.

