Skip to main content
POST
Quando a autenticação 3DS termina, esta rota entrega o que a cobrança precisa para provar que o comprador foi autenticado: o estado final, o criptograma (CAVV), o ECI, a versão do protocolo e os identificadores da transação no banco e na bandeira. Esse conjunto vai no campo paymentMethod.threeDS de POST /v1/charges. É a última chamada do 3DS via API, antes da criação da cobrança.

Quando usar

Antes de chamar

  • Tenha o authenticationId devolvido por POST /v1/three-ds/authenticate.
  • Chame só depois da mensagem de fim do desafio (3ds-authentication-challenge-complete), ou quando authenticate ou submit já devolveram um status final (succeeded, failed, error ou canceled). Antes disso, a rota responde 500 com a mensagem Authentication challenge not yet completed... ou devolve state error.
  • Use a chave pública (pk_, ou pk_test_ no sandbox) no cabeçalho Basic, como usuário e com senha vazia.
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. Ex.: tdsa_1QmCRMJM0r9zBvr4OVmMRa6X.
O authenticationId é gerado pelo provedor de 3DS e deve ser tratado como texto opaco. Repasse exatamente o valor recebido em POST /v1/three-ds/authenticate, sem validar prefixo nem tamanho.

Respostas

A resposta 200 é o resultado final do desafio (schema ThreeDSChallengeResult). Os campos type e state vêm sempre. Os demais nunca vêm null: quando o provedor não devolve um valor, o campo fica ausente da resposta.
string
Tipo de autenticação 3DS. Hoje vem sempre full. Ex.: full.
string
Estado da autenticação: success, failure, unenrolled, error, unsupported_brand ou disabled. Ex.: success.
string
CAVV, o valor de autenticação gerado pelo banco. Ausente quando não houver valor. Ex.: Vt5xwasruB0Q6qRoG9mpzdRPqQs=.
string
ID da transação no Directory Server (bandeira). Ex.: 607bb317-8d24-45a7-a3c0-7ae1fdca56d0.
string
ID da transação no 3DS Server. Ex.: 59588a8b-955e-4aa8-bae1-338bbfdba8fa.
string
ID da transação no ACS (banco emissor). Ex.: 6bf18a7a-3a7b-488f-bce1-3da96c73e746.
string
Electronic Commerce Indicator. Ex.: 05.
string
Versão do protocolo 3DS. Ex.: 2.2.0.

O que fazer com cada state

Quando a configuração da sua conta exige 3DS, só state success permite que a cobrança siga. Uma cobrança enviada com outro estado é recusada, com o motivo em reason (por exemplo, 3ds_failed: The cardholder failed to authenticate. Please try again or use a different card). Quando o 3DS não é obrigatório para a conta, os dados 3DS são repassados sem essa validação.
Para o negócio: unenrolled e disabled são casos em que o banco não autenticou, mas também não recusou. O que fazer nesses casos é uma decisão de risco da sua empresa. Combine a regra com a área responsável antes de liberar o checkout.
Os erros vêm no formato { statusCode, message, error }. Trate o erro pelo código HTTP, não pelo texto da mensagem.

Usar o resultado na cobrança

O resultado é obtido no navegador, com a chave pública. A cobrança é criada no seu servidor, com a chave secreta. Envie o resultado do front-end para o seu servidor e inclua-o em paymentMethod.threeDS:
Para o desenvolvedor: repasse a resposta desta rota do jeito que veio, sem alterar valores e sem acrescentar campos. No objeto threeDS da cobrança, type e state são obrigatórios; 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 nunca envie null: o null é gravado e repassado ao adquirente, e alguns adquirentes recusam. Com 3DS obrigatório, cryptogram ou eci nulos fazem a cobrança ser recusada com 3ds_incomplete. Use o mesmo cartão e o mesmo valor da autenticação.

Erros comuns

Veja também

Criar uma cobrança

Campo paymentMethod.threeDS.

Retomar cobrança após 3DS

Continuação do 3DS gerenciado.

3DS via API

Guia do fluxo completo.

SDK de 3D Secure

O mesmo resultado obtido pelo SDK.