Skip to main content
No 3DS via API, a sua aplicação conduz cada etapa da autenticação 3D Secure. Ela inicia a autenticação, exibe o iframe de coleta de dados do navegador e envia o resultado. Depois, exibe o desafio do banco quando ele é pedido e, no fim, busca o resultado com o criptograma. Com esse resultado, o seu backend cria a cobrança informando o objeto 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 mensagens postMessage 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.
O desenho abaixo mostra qual rota chamar a partir de cada 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 usam fetch no navegador com a chave pública. Defina uma função auxiliar:

1. Inicie a autenticação

Resposta 200:
Para o desenvolvedor: o cvv não faz parte da autenticação. Ele vai só na criação da cobrança, feita pelo backend.

2. Faça a verificação do dispositivo em um iframe oculto

Se o status 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:
O fingerprintingResult é um texto em Base64 que você repassa ao submit sem alterar.
Quem envia a mensagem é a página do provedor de 3DS carregada no iframe, e o host dela pode mudar. Valide event.source === iframe.contentWindow e event.data.type. Não fixe um domínio de provedor em event.origin.
Para o desenvolvedor: se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), chame o submit sem fingerprintingResult. O campo é opcional. Se o status for requires_submission sem fingerprintingUrl, chame o submit direto.

3. Envie a autenticação

Resposta 200:
O submit devolve um destes status: requires_challenge, succeeded, failed, error ou processing.

4. Mostre o desafio em um iframe visível

Quando o status é 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 sandbox no 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.
Quando o cliente termina, a página do desafio envia esta mensagem por postMessage:
O 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.
Se o cliente desistir, cancele a autenticação:
Resposta 200:

5. Busque o resultado

Depois da mensagem de fim do desafio, ou quando authenticate ou submit já devolveram status final (succeeded, failed, error ou canceled), busque o resultado:
Resposta 200:
Não chame challenge-result antes do fim do desafio. Nesse caso, a rota responde 500 com a mensagem Authentication challenge not yet completed... ou devolve state error.

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 por challenge-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.
A resposta da cobrança é a de sempre: id, status (paid, refused ou failed), paymentDetails e reason.

Erros comuns

Perguntas frequentes

Não. A resposta de authenticate pode trazer fingerprintingUrl, challengeUrl ou nenhum dos dois, conforme o emissor. Trate cada caso pelo status.
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.
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.
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.
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 com state 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.