Pedido com 3DS (3D Secure)

Este caso de uso descreve como um vendedor cria um pedido com cartão de crédito autenticado via 3DS (EMV 3DS), incluindo coleta de dados do navegador e execução do desafio (Step Up), quando exigido pe

Atores

• Vendedor (Seller) Sistema integrador que cria compradores, tokeniza cartões e cria pedidos.

• Comprador (Buyer) Pessoa física responsável pelo pagamento.

• Barte API Responsável pela tokenização, orquestração do 3DS, autorização e cobrança.

• Emissor do Cartão Banco responsável pela autenticação 3DS e autorização financeira.

---

Pré-condições

• O vendedor possui um Token de API válido

• O Buyer é obrigatório e deve ser criado previamente

• O pagamento será realizado via Cartão de Crédito

• O cartão será tokenizado antes da criação do pedido

• O vendedor implementou:

  • Coleta de dados do navegador (Browser Data Collection)

  • Tela ou iframe para o Step Up Challenge, quando necessário

---

Fluxo Principal

1. Autenticação na API

Todas as requisições devem conter o token no header:

X-Token-Api: YOUR_API_KEY

📌 Referência: Obtendo o Token de API

---

2. Criar um Comprador (Buyer) — Obrigatório

O Buyer representa o pagador e é obrigatório para pedidos com 3DS.

Objetivo

• Identificar corretamente o comprador

• Atender requisitos de antifraude, autenticação e conciliação

Resultado esperado

• A API retorna o uuid do Buyer

📌 Esse uuid será utilizado nas próximas etapas.

📌 Referência: Criando um Comprador

---

3. Tokenizar o Cartão (Card Token)

O vendedor tokeniza o cartão do comprador de forma segura.

Pontos importantes

• Os dados sensíveis do cartão não devem ser armazenados por vendedores não compatíveis com PCI DSS

• O token retornado substitui os dados reais do cartão

Resultado esperado

• Retorno de:

  • uuid → Card Token (usado na transação)

  • cardId → usado exclusivamente para criar a sessão 3DS

📌 Caso checkZeroDollar = false, o token pode iniciar como PENDING.

📌 Referência: 1. Criar Card Token (Tokenização de Cartão)

---

4. Criar Sessão 3DS

A sessão 3DS inicia o processo de autenticação.

Objetivo

• Preparar a comunicação com o provedor 3DS (ex.: Cybersource)

Resultado esperado

• Retorno de:

  • id → será enviado como setupId na criação do pedido

  • token e collectUrl → usados na coleta de dados do navegador

📌 Referência: 2. Criar sessão 3DS

---

5. Coletar Dados do Navegador (Browser Data Collection)

Antes de criar o pedido, o vendedor deve obrigatoriamente coletar os dados do navegador do comprador.

Objetivo

• Enviar informações de background para o emissor

• Permitir decisão de frictionless flow ou challenge

Regras

• A coleta ocorre em background

• O vendedor deve aguardar a finalização da coleta

Resultado esperado

• Coleta concluída com sucesso (≈ 1 segundo)

📌 Sem essa etapa, o pedido com 3DS pode falhar.

📌 Referência: 3. Coletar dados do navegador (Browser Data Collection)

---

6. Criar Pedido com 3DS

Com a coleta concluída, o vendedor cria o pedido informando os dados de 3DS.

Configurações importantes

• Informar:

  • setupId da sessão 3DS

  • Dados do navegador

  • Endereço de cobrança

  • redirectURL para retorno pós-autenticação

• O uuidBuyer é obrigatório

O que acontece

• A Barte envia os dados ao provedor 3DS

• O emissor decide se haverá desafio

Resultado esperado

• Pedido criado

• Uma ou mais charges associadas

• Retorno do objeto threeDSResponse

📌 Referência: 4. Criar pedido com 3DS

---

Fluxos Alternativos

7. Desafio 3DS (Step Up Challenge)

O desafio é necessário quando:

threeDSResponse.challenged = true

O que acontece

• O vendedor deve renderizar o iframe de desafio

• O comprador autentica no banco emissor (senha, app, biometria)

Após o desafio

• O cliente é redirecionado para o redirectURL

• O resultado final não é garantido imediatamente

📌 O status definitivo é enviado via webhook.

📌 Referência: 5. Desafio 3DS (Step Up Challenge)

---

Decisão de Fluxo

Situação	Comportamento
challenged = false	Pagamento segue sem interação do cliente
challenged = true	Exige Step Up Challenge
Autenticação aprovada	Charge pode ser PAID
Autenticação recusada	Charge será FAILED

---

Pós-condições

Ao final deste caso de uso, o vendedor consegue:

• Autenticar-se na API

• Criar obrigatoriamente um Buyer

• Tokenizar cartões com segurança

• Executar autenticação 3DS completa

• Criar pedidos com ou sem desafio

• Receber o status final via webhook

---

Observações Importantes

• Buyer é obrigatório

• A coleta de dados do navegador é obrigatória

• O Step Up Challenge depende do emissor

• O status final da transação sempre deve ser confirmado via webhook

• 3DS reduz fraude e pode gerar liability shift, conforme decisão do emissor