Autenticação 3DS

O 3D Secure (3DS) é um protocolo de autenticação adicional que pode solicitar que o portador do cartão confirme a transação junto ao banco emissor. Isso reduz chargebacks e pode aumentar a taxa de aprovação em transações de alto risco.

[!NOTE] O 3DS usa o mesmo SDK da tokenização, mas com um campo extra (finger_print). Se você já tem tokenização implementada, a adaptação é mínima.

Como funciona

Importe o SDK 3DS

Use a versão 3DS do SDK Dom. A URL é diferente da tokenização padrão.

Obtenha o `finger_print`

Chame `getTokenCard()` com o campo `finger_print: true`. O SDK coleta informações do dispositivo e retorna o token junto com a impressão digital.

Crie a transação com `finger_print`

Envie o `finger_print` junto com o `card_token` na criação da transação.

Verifique se há desafio 3DS

Se a resposta incluir `three_ds_challenge: true`, exiba o iframe com o HTML do desafio para o usuário completar a autenticação.

Conclua a transação

Após o usuário completar o desafio, o status da transação é atualizado automaticamente.

Passo 1 — Importar o SDK 3DS

<!-- Sandbox -->
<script src="https://hml-static.dompagamentos.com.br/dom-checkout-3ds.js"></script>

<!-- Produção -->
<!-- <script src="https://static.dompagamentos.com.br/dom-checkout-3ds.js"></script> -->

Passo 2 — Obter token com `finger_print`

async function tokenizarCom3DS() {
  const resultado = await DomCheckout.getTokenCard({
    publicKey: 'SUA_CHAVE_PUBLICA',
    number: '4111111111111111',
    holder_name: 'João Silva',
    exp_month: '12',
    exp_year: '2028',
    cvv: '123',
    document: '11144477735',
    finger_print: true, // habilita coleta 3DS
  });

  return {
    cardToken: resultado.token,
    fingerPrint: resultado.finger_print,
  };
}

Passo 3 — Criar transação com 3DS

Envie finger_print junto com card_token na requisição:

curl --request POST \
  --url "{apiUrl}/transactions" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 25000,
    "payment_method": "credit_card",
    "card_token": "TOKEN_DO_SDK",
    "finger_print": "FINGER_PRINT_DO_SDK",
    "installments": 1,
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "document": "11144477735"
    }
  }'

Passo 4 — Tratar o desafio 3DS

Se o banco exigir autenticação adicional, a resposta inclui three_ds_challenge: true e o HTML do iframe:

const { order } = await res.json();

if (order.three_ds_challenge) {
  // Exibe o iframe com o desafio
  const container = document.getElementById('three-ds-container');
  container.innerHTML = order.three_ds_html;
  container.style.display = 'block';

  // Escuta o evento de conclusão do desafio
  window.addEventListener('message', async (event) => {
    if (event.data?.type === 'three_ds_complete') {
      container.style.display = 'none';

      // Consulta o status final da transação
      const statusRes = await fetch(`{apiUrl}/transactions/${order.id}`, {
        headers: { 'Authorization': 'Bearer {token}' },
      });
      const { order: finalOrder } = await statusRes.json();
      console.log(finalOrder.status); // "paid" ou "refused"
    }
  });
} else {
  // Sem desafio — transação processada diretamente
  console.log(order.status);
}

Status possíveis após 3DS

Status	`status_detail`	Descrição
`paid`	`approved`	Autenticado e aprovado
`refused`	`rejected`	Autenticação recusada pelo banco
`refused`	`cancelled`	Usuário cancelou o desafio
`pending`	`pending`	Aguardando conclusão do desafio

Cartões de teste (Sandbox)

Cartão	Fluxo	Número	CVV	Vencimento
Mastercard	Challenge com sucesso	`5483 9281 6457 4623`	`123`	`11/25`
Mastercard	Challenge não autorizado	`5361 9568 0611 7557`	`123`	`11/25`

Próximos passos

Tokenizando Cartões — tokenização sem 3DS
3DS — Referência — documentação técnica completa do SDK
Testando em Sandbox — cartões de teste disponíveis