Skip to main content
A autenticação do portador — 3-D Secure — pede ao banco emissor que confirme quem está usando o cartão. Autenticada a compra, uma contestação por “não fui eu” é respondida pelo emissor, e não pelo seu saldo.
É opcional, e o padrão é não autenticar. Você cobra no cartão sem passar por aqui — veja Cobrar no cartão. Esta página é para quando você QUER a transferência de responsabilidade e está disposto a um passo a mais no navegador.

​
Você precisa disto?

Vale a pena quando o seu produto atrai fraude: ticket alto, entrega digital imediata, comprador novo. Não vale quando o desafio custaria mais conversão do que a fraude custa — e essa conta é sua, não nossa.

​
Como pedir

Um campo, em POST /v1/charges:
Com required, a cobrança passa a exigir card.three_ds — pedir autenticação e não autenticar é incoerente, e volta 422. Sem o campo, nada é exigido.
O interruptor de 3DS da sua conta, no painel, não vale nesta API. Ele governa os checkouts hospedados por nós, onde somos nós que montamos a tela e podemos pedir o desafio ao comprador. Aqui quem monta a tela é você, e exigir um identificador que só o navegador produz devolveria um 422 impossível de resolver a quem cobra de um servidor.

​
Como rodar o desafio

Três passos, e a ordem importa:
1

Peça o token, no envio do formulário

POST /v1/three_ds_tokens devolve o token e o endereço da biblioteca do mesmo ambiente. O token vale cinco minutos e serve uma vez só — pedi-lo na abertura da página entrega um token morto a quem demora a preencher o endereço.
2

Rode o desafio, com o número do cartão em claro

O autenticador precisa do número, da validade e do endereço de cobrança. É por isso que o desafio vem antes de vext.createToken(): tokenizar primeiro queimaria o token de um minuto durante o desafio, que pode levar mais que isso.
3

Tokenize e cobre

Com o desafio concluído, chame vext.createToken() e crie a cobrança com three_d_secure: "required" e o resultado em card.three_ds.
Se a sua loja não autentica, POST /v1/three_ds_tokens responde 422 three_ds_unavailable com o motivo — e não um erro genérico. Quem lê é o seu servidor, para quem o motivo é acionável.

​
O que você precisa repassar

Quem tokeniza o cartão na própria página recebe do autenticador o resultado do desafio. Repasse-o ao seu servidor exatamente como veio e envie-o em card.three_ds. Esse par transaction_id + status é a prova da autenticação. Perdê-lo no caminho significa ter incomodado o comprador com um desafio e pagado a contestação assim mesmo.

​
O resultado, na cobrança

card.three_d_secure.status traz uma letra do padrão da bandeira: Na entrada, em card.three_ds.status, aceitamos só Y e A. Os outros descrevem uma autenticação que não deu certo, e mandá-los seria declarar uma proteção que não existe.

​
Cartão guardado não autentica

O autenticador precisa do número do cartão em claro, e um cartão no cofre é uma referência sem número. Os dois são fisicamente excludentes. Por isso three_d_secure: "required" junto de um card.id volta 403 one_click_requires_three_ds: você pediu autenticação num cartão que não pode autenticar. Cobrar assim mesmo, fingindo que autenticou, entregaria a venda sem transferência de responsabilidade — e você descobriria depois de já ter perdido a contestação. Sem pedir required, o cartão guardado cobra normalmente. Ele só não tem liability shift, como qualquer cobrança sem autenticação.

​
E na assinatura?

Uma cobrança de série não tem comprador na tela para desafiar, então ela nunca autentica.
Declarar a recorrência não devolve a proteção. É conformidade de bandeira — evita multa de Mastercard, Visa e Elo —, e nada mais. Uma assinatura corre sem liability shift, e você arca com a contestação por fraude.O caminho que preserva a proteção é autenticar a primeira cobrança, com o comprador na tela e o cartão digitado, e deixar as seguintes correrem com o pm_.

​
O que dá errado

O token que inicia a autenticação vale cinco minutos e serve uma vez só. Peça-o no momento em que o comprador envia o formulário, e não quando a página abre: emitido cedo, ele já estaria morto para quem levou algum tempo preenchendo o endereço.

​
Veja também

Cobrança no cartão

O objeto card, parcelas e a recusa que cria cobrança.

Cofre de cartões

Por que o cofre e a autenticação não convivem.
Ficou algo de fora? Chame no WhatsApp. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.