Skip to main content
POST
Depois de iniciar a autenticação e, se pedido, coletar os dados do dispositivo (fingerprinting), esta rota envia a autenticação para o banco emissor decidir. A resposta diz se o banco aprovou sem interação, se ele quer um desafio do comprador ou se a autenticação falhou. É a segunda chamada do 3DS via API. A primeira é Iniciar autenticação.

Quando usar

Antes de chamar

  • Tenha o authenticationId devolvido por POST /v1/three-ds/authenticate.
  • Use a chave pública (pk_, ou pk_test_ no sandbox) no cabeçalho Basic, como usuário e com senha vazia.
  • Se houve fingerprinting, espere a mensagem de fim do iframe oculto (ou o tempo limite de cerca de 60 segundos) antes de chamar.
O contrato desta rota declara a autenticação basic e diz, na descrição da rota, que a chave usada é a pública (pk_). 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

string
required
ID da autenticação 3DS devolvido por POST /v1/three-ds/authenticate. Trate como texto opaco e repasse exatamente o valor recebido. Ex.: tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string
Resultado do fingerprinting em Base64, recebido pelo postMessage do iframe oculto. Omita se não houve etapa de fingerprinting. Ex.: VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==.

Respostas

string
ID da autenticação 3DS. Ex.: tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string
Status da autenticação depois do envio: requires_challenge, succeeded, failed, error ou processing. Ex.: requires_challenge.
string | null
URL do desafio. Carregue em um iframe visível quando o status for requires_challenge. Ex.: https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
string | null
Resultado da autenticação. Só vem preenchido em estados finais. Ex.: authenticated.
Para o negócio: a resposta desta rota decide se o comprador vai ver uma tela do banco. Com succeeded, o pagamento segue sem interação extra. Com requires_challenge, o checkout precisa mostrar o desafio do banco emissor e esperar o comprador concluir.
Os erros vêm no formato { statusCode, message, error }. Trate o erro pelo código HTTP, não pelo texto da mensagem.

Capturar o resultado do fingerprinting

A página carregada no iframe oculto avisa o fim da coleta com uma mensagem postMessage neste formato:
Registre o listener antes de carregar o iframe e aceite só mensagens que venham desse iframe e tenham o type esperado. Se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), siga sem o resultado: fingerprintingResult é opcional.
Para o desenvolvedor: a mensagem vem da página do provedor de 3DS, o host da fingerprintingUrl. Esse host pode mudar: valide event.source e event.data.type e não fixe um domínio em event.origin.

Erros comuns

Veja também

Iniciar autenticação

Primeiro passo do 3DS via API.

Resultado do desafio

Dados para criar a cobrança autenticada.

Cancelar autenticação

Quando o comprador desiste no meio do fluxo.

3DS via API

Guia do fluxo completo.