Skip to main content
No 3DS gerenciado, a Finvia conduz a autenticação 3D Secure por você. O seu backend cria a cobrança de cartão com 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 em authentication_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

Uma cobrança em authentication_required não foi paga. Não libere o pedido nesse status e não trate como paga uma cobrança abandonada. Libere só quando a cobrança chegar a paid, confirmada por webhook ou por GET /v1/charges/{id}.

Passo a passo

1. Colete os dados do navegador

Para o desenvolvedor: o contrato dá -180 como exemplo de timezoneOffset para o horário de Brasília (UTC−3). O getTimezoneOffset() do JavaScript devolve 180 nesse fuso, com o sinal invertido. Converta antes de enviar.

2. Crie a cobrança no backend

Resposta 201 quando o banco pede verificação ou desafio:
O valor de 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 a authenticationUrl ao front-end e abra para o comprador. A página aceita ser exibida em iframe.
Se preferir, abra em nova aba (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 não leva o comprador de volta ao seu site e não informa o resultado à sua página. Ao final, ela pode mostrar uma mensagem de confirmação ou ficar em branco. Não use o que a página exibe como resultado do pagamento. O resultado vale só pelo webhook ou pela consulta da cobrança.
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:
Quando o status sair de authentication_required, feche o modal e mostre o resultado ao comprador.

5. Trate o abandono

Erros comuns

Perguntas frequentes

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.
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.
Não. Use o valor recebido na resposta, sem alterar. O host e os parâmetros são definidos pela Finvia e podem mudar.
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.
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.
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 com threeDSMode 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.