Pedido com Cartão Tokenizado

Este caso de uso descreve como um vendedor cria um pedido com cartão de crédito utilizando tokenização, garantindo que os dados sensíveis do cartão não trafeguem novamente após a primeira captura.

O fluxo é indicado para:

• Ambientes que exigem maior segurança
• Reutilização de cartões
• Conformidade com boas práticas de PCI
• Fluxos compatíveis com autenticação forte (ex.: 3DS quando aplicável)

---

Atores

• Vendedor (Seller) Sistema integrador que cria compradores, tokeniza cartões e gera pedidos.
• Comprador (Buyer) Pessoa responsável pelo pagamento.
• Barte API Responsável pela tokenização, autorização do cartão, captura e pós-pagamento.

---

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

---

Fluxo Principal

1. Autenticação na API

Todas as requisições devem conter o Token de API 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:

• Tokenização de cartão
• Criação de pedidos
• Antifraude e rastreabilidade

Resultado esperado

• A API retorna o uuid do Buyer

📌 Esse uuid será utilizado:

• Na tokenização do cartão
• Na criação do pedido

📌 Referência: Criando um Comprador

---

3. Tokenizar o Cartão (Card Token)

A tokenização cria uma representação segura do cartão, permitindo reutilização sem reenvio dos dados sensíveis.

O que acontece

• Os dados do cartão são enviados uma única vez
• A Barte gera um token seguro
• O cartão pode ser reutilizado em cobranças futuras

Configurações importantes

• buyerUuid é obrigatório
• checkZeroDollar define se haverá validação sem cobrança

Resultado esperado

• Um token de cartão é criado com status:

  • ACTIVE → pronto para uso
  • PENDING → será ativado após a primeira transação bem-sucedida

⚠️ Atenção — Campo correto

• O cardToken a ser usado na order é:

  response.uuid

• ❌ Não utilizar cardId para criar transações

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

---

4. Criar um Pedido utilizando Card Token

Com o Buyer e o cardToken criados, o vendedor cria o pedido normalmente.

Regra importante

• No objeto payment.card, devem ser enviados apenas:

  • cardToken
  • cvv

O que acontece

• O cartão tokenizado é utilizado
• O valor é autorizado e capturado conforme configuração
• Uma ou mais charges são criadas

Resultado esperado

• Pedido criado com sucesso
• Status da charge:

  • PAID (quando capture = true)
  • ou PRE_AUTHORIZED (se usado com pré-captura)

📌 O uuid da charge será necessário para ações de pós-pagamento.

📌 Referência: Pedido com Cartão Tokenizado

---

Fluxos Pós-Pagamento

Após a captura (PAID), entram os fluxos padrão de pós-pagamento.

5.1 Estorno Total

Permite estornar integralmente o valor capturado.

📌 Referência:

---

5.2 Estorno Parcial

Permite estornar parte do valor capturado.

📌 Referência: Estorno de um Pedido

---

Pós-condições

Ao final deste caso de uso, o vendedor consegue:

• Autenticar-se na API
• Criar obrigatoriamente um Buyer
• Tokenizar um cartão com segurança
• Criar pedidos utilizando card token
• Reutilizar o cartão em cobranças futuras
• Realizar estornos totais ou parciais

---

Observações Importantes

• Buyer é obrigatório em todo o fluxo
• O token pode ser reutilizado em múltiplas transações
• A captura ocorre sempre no nível da charge
• Tokenização pode ser combinada com pré-captura
• O armazenamento de dados sensíveis de cartão é permitido apenas para vendedores compatíveis com o PCI DSS. Vendedores sem certificação PCI DSS não devem, em hipótese alguma, armazenar esses dados.