# Pedido com 3DS (3D Secure)

### 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](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api.md)

***

#### 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](/guias/pedidos-e-cobrancas/criando-um-comprador.md)

***

#### 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: [/pages/lLLeZrln6j9sahQycPri#id-1.-criar-card-token-tokenizacao-de-cartao](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-1.-criar-card-token-tokenizacao-de-cartao "mention")

***

#### 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: [/pages/lLLeZrln6j9sahQycPri#id-2.-criar-sessao-3ds](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-2.-criar-sessao-3ds "mention")

***

#### 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: [/pages/lLLeZrln6j9sahQycPri#id-3.-coletar-dados-do-navegador-browser-data-collection](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-3.-coletar-dados-do-navegador-browser-data-collection "mention")

***

#### 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: [/pages/lLLeZrln6j9sahQycPri#id-4.-criar-pedido-com-3ds](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-4.-criar-pedido-com-3ds "mention")

***

### 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: [/pages/lLLeZrln6j9sahQycPri#id-5.-desafio-3ds-step-up-challenge](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-5.-desafio-3ds-step-up-challenge "mention")

***

### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pedido-com-3ds-3d-secure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.