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. É a diferença entre discutir a venda e perdê-la de antemão.

​
Quem decide

Você pede; a decisão é nossa. O campo é three_d_secure, em POST /v1/charges, com três valores: A ordem das perguntas é a regra inteira:
1

A sua loja está habilitada a cobrar no cartão?

Se não, não há o que autenticar, e o campo é ignorado.
2

A sua conta exige autenticação?

Se exige, acabou: autentica. Essa configuração é o piso, e um three_d_secure: "off" na requisição não a desliga. É o que impede que um trecho de código esquecido tire a proteção de uma loja inteira sem ninguém perceber.
3

Você pediu required?

Então autentica, mesmo que a sua conta não exija.
4

Você pediu off?

Então não autentica. A conta já respondeu no passo anterior, e daqui para baixo quem assume a contestação é quem pediu.
5

O valor chegou ao piso da plataforma?

Se chegou, autentica.
Ligar a exigência para a conta inteira é feito no painel, e é o caminho recomendado: uma regra num lugar só resiste melhor do que um campo repetido em cada chamada.

​
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 e autenticação do portador são excludentes. O autenticador precisa do número do cartão em claro, e um cartão no cofre é uma referência sem número — por isso um card.id numa loja que exige autenticação volta 403 one_click_requires_three_ds. Cobrar assim mesmo, fingindo que autenticou, entregaria a venda sem transferência de responsabilidade, e a loja descobriria isso depois de já ter perdido a contestação.

​
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.