Skip to main content
POST
O 3D Secure (3DS) é a verificação em que o banco emissor do cartão confirma que quem está comprando é o titular. Esta rota abre essa verificação: você envia o valor, o cartão e os dados do navegador, e a Finvia devolve um authenticationId e o próximo passo. Às vezes o banco aprova sem interagir com o comprador (fluxo sem atrito, ou frictionless). Outras vezes ele pede um desafio: o comprador se autentica diretamente no banco emissor, em uma tela exibida dentro do seu checkout. Esta é a primeira chamada do 3DS via API, o fluxo em que você conduz cada etapa. Se prefere que a Finvia conduza tudo, use o 3DS gerenciado. Se usa o SDK de segurança, ele faz estas chamadas por você (SDK de 3D Secure).

Quando usar

Para o negócio: quando a configuração da sua conta exige 3DS, uma cobrança de cartão sem autenticação bem-sucedida é recusada. O 3DS acrescenta uma etapa ao checkout e, em alguns casos, um desafio para o comprador. Decida com o time técnico qual dos três caminhos (gerenciado, SDK ou via API) combina com o seu checkout.

Antes de chamar

  • Use a chave pública (pk_, ou pk_test_ no sandbox) no cabeçalho Basic, como usuário e com senha vazia. Esta rota foi feita para ser chamada do navegador, onde a chave secreta nunca pode aparecer.
  • A conta precisa ter um provedor de 3DS configurado. Sem ele, a rota responde 404 com a mensagem No 3DS provider configured for this gateway.
  • Colete os dados do navegador do comprador (objeto browser).
Nunca use a chave secreta (sk_) no front-end. As rotas de 3D Secure usam a chave pública.
O contrato desta rota declara a autenticação basic e diz, na descrição da rota, que a chave usada é a pública (pk_) como usuário do Basic. A descrição genérica do esquema basic no contrato fala em chave secreta. Siga a descrição da rota: chave pública.

Corpo da requisição

Campos obrigatórios: amount, currency, card e browser.
number
required
Valor da transação na moeda informada, em reais quando a moeda é BRL. Ex.: 100.
string
required
Código da moeda no padrão ISO 4217. Ex.: BRL.
object
required
Cartão que será autenticado.
object
required
Dados do navegador do comprador, usados pelo banco na análise (schema BrowserInfo).
Para o desenvolvedor: quase todos os campos de browser saem direto do JavaScript da página: navigator.userAgent, navigator.language, screen.width, screen.height e screen.colorDepth. Para timezoneOffset, inverta o sinal de new Date().getTimezoneOffset(): no horário de Brasília ele devolve 180, e o exemplo do contrato é -180. O ipAddress precisa vir do seu servidor, que enxerga o IP de quem fez a requisição.

Respostas

string
Identificador da autenticação 3DS. Guarde: ele é enviado em enviar, cancelar e resultado do desafio. O valor é gerado pelo provedor de 3DS e deve ser tratado como texto opaco: repasse exatamente o que recebeu, sem validar prefixo nem tamanho. Ex.: tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string
Situação atual da autenticação: requires_submission, requires_challenge, succeeded, failed, error, canceled ou processing. Ex.: requires_submission.
string | null
URL para carregar em um iframe oculto, que coleta dados do dispositivo (fingerprinting). Ao terminar, a página envia por postMessage a mensagem { "type": "3ds-authentication-fingerprinting-complete", "fingerprintingResult": "<Base64>" }. Depois chame POST /v1/three-ds/submit. Ex.: https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string | null
URL para carregar em um iframe visível quando o status é requires_challenge. É nesse iframe que o comprador faz o desafio do banco. Ao final, a página envia por postMessage a mensagem { "type": "3ds-authentication-challenge-complete", "status": "succeeded" } (ou failed, error, canceled). Ex.: https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string | null
Resultado da autenticação. Só vem preenchido em estados finais. Valores: authenticated, informational, attempt_acknowledged, rejected, denied, abandoned, not_supported, processing_error, internal_error, canceled. Ex.: authenticated.
As URLs de fingerprintingUrl e challengeUrl são da página do provedor de 3DS, e o host pode mudar. Não fixe o domínio no código. Ao receber uma mensagem, confira se event.source === iframe.contentWindow e se event.data.type é o tipo esperado. O fluxo completo, com exemplos, está no guia 3DS via API.

O que fazer com cada status

Trate o erro pelo código HTTP, não pelo texto da mensagem. O corpo de erro tem três campos:
integer
Código HTTP.
string
Mensagem descritiva do erro.
string
Tipo do erro.

Fluxo completo do 3DS via API

1

Inicie a autenticação

Chame esta rota com o cartão, o valor e os dados do navegador. Guarde o authenticationId.
2

Faça o fingerprinting, se pedido

Se a resposta trouxer fingerprintingUrl, carregue a URL em um iframe oculto e espere a mensagem 3ds-authentication-fingerprinting-complete, com o fingerprintingResult.
3

Envie a autenticação

Chame POST /v1/three-ds/submit com o authenticationId e, se houver, o fingerprintingResult.
4

Mostre o desafio, se pedido

Se o status for requires_challenge, carregue challengeUrl em um iframe visível para o comprador concluir o desafio e espere a mensagem 3ds-authentication-challenge-complete.
5

Busque o resultado

Chame POST /v1/three-ds/challenge-result depois do fim do desafio, ou quando a autenticação já estiver em estado final. A resposta traz o criptograma e os identificadores da autenticação.
6

Crie a cobrança

Envie o resultado no campo paymentMethod.threeDS de POST /v1/charges, chamado do seu servidor com a chave secreta.

Erros comuns

Veja também

3DS via API

Guia do fluxo completo com as rotas de 3DS.

Enviar autenticação

Próximo passo depois do fingerprinting.

Visão geral do 3D Secure

Gerenciado, SDK ou via API.

SDK de 3D Secure

O mesmo fluxo com o SDK no navegador.