Pedido com Cartão Tokenizado

Este guia descreve o passo a passo para um vendedor criar um pedido (order) com cartão tokenizado utilizando a API da Barte, desde a autenticação até possíveis ações após o pagamento.

---

1. Criar Card Token (Tokenização de Cartão)

A tokenização permite armazenar um cartão de forma segura e reutilizá-lo em cobranças futuras, sem a necessidade de reenviar os dados sensíveis do cartão.

Após a geração do token, o cartão pode ser utilizado na criação de pedidos (orders).

---

Endpoint

POST /payment/v1/cards
https://api.barte.com/payment/v1/cards

---

Headers

X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*

---

Body

{
  "holderName": "JOSE DAS NEVES TEST",
  "number": "5383638854440891",
  "cvv": "220",
  "expiration": "12/2025",
  "checkZeroDollar": false,
  "buyerUuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}

Campos importantes

• buyerUuid: UUID do comprador previamente criado

• checkZeroDollar:

  • true: realiza uma validação do cartão sem cobrança

  • false: não realiza a validação zero-dólar

---

Response

{
  "uuid": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
  "status": "ACTIVE",
  "createdAt": "2025-08-21",
  "brand": "mastercard",
  "cardHolderName": "JOSE DAS NEVES TEST",
  "cvvChecked": true,
  "fingerprint": "d1Epx4VTTGp1KdCtVvcGK0oPA//ZR6jMlEcrdVjbt28=",
  "first6digits": "518688",
  "last4digits": "5601",
  "buyerId": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
  "expirationMonth": "10",
  "expirationYear": "2025",
  "cardId": "83d353d2-716f-45cf-837f-50c18f10efa0"
}

---

⚠️ Atenção — Qual campo usar na criação da transação

Na criação do pedido (order), o cardToken que deve ser enviado é:

👉 uuid retornado neste endpoint

❌ Não utilizar o campo cardId para criação de transações.

Exemplo conceitual:

cardToken = response.uuid

---

Observações importantes

• O token retornado representa o cartão de forma segura

• O status ACTIVE indica que o cartão está pronto para uso

• O token pode ser reutilizado em múltiplas cobranças

• Os dados sensíveis do cartão não devem ser armazenados pelo vendedor

• Caso o checkZeroDollar não seja realizado, a tokenização será criada com status PENDING e será automaticamente atualizada para ACTIVE após a primeira transação bem-sucedida.

---

2. Criar um pedido (Order)

Com o comprador e token de cartão criados, a próxima etapa é a criação do pedido.

No payload da requisição, dentro do objeto payment, a propriedade card terá apenas cardToken e cvv.

⚠️ Importante: Também é possível criar a transação com cardToken em formato de pré-captura. Para isso, basta seguir todo o processo acima até a tokenização do cartão e, após isso, seguir o processo de pré-captura em Pedido com Pré-captura. A única diferença é que o objeto card terá cardToken e cvv, apenas.

Endpoint

POST /v2/orders
https://api.barte.com/v2/orders

Headers

X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*

Body

{
  "startDate": "2026-01-30",
  "value": 100,
  "installments": 1,
  "title": "Compra de produto",
  "description": "Descrição da compra",
  "payment": {
    "method": "CREDIT_CARD_EARLY_SELLER",
    "capture": true,
    "softDescriptor": "Soft Descriptor 123456",
    "card": {
      "cardToken": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
      "cvv": "220"
    },
    "fraudData": {
      "document": "48637879012",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "34999991111",
      "billingAddress": {
        "country": "BR",
        "state": "Minas Gerais",
        "city": "Uberlândia",
        "district": "Jardim Europa",
        "street": "Rua Orleans",
        "zipCode": "38414552",
        "number": "100",
        "complement": "Bloco A"
      }
    }
  },
  "uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
  "metadata": [
    {
      "key": "código",
      "value": "YMC"
    }
  ]
}

Response

{
    "uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
    "status": "PAID",
    "title": "Compra de produto",
    "description": "Descrição da compra",
    "value": 100.00,
    "installments": 1,
    "startDate": "2026-01-30",
    "payment": "CREDIT_CARD_EARLY_SELLER",
    "customer": {
        "document": "48637879012",
        "type": "CPF",
        "documentCountry": "BR",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "34999991111"
    },
    "idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
    "subSellerPaymentResponse": [
        {
            "subSellerPaymentResponse": [],
            "amountForSubSellers": 0
        }
    ],
    "charges": [
        {
            "uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
            "title": "Compra de produto",
            "expirationDate": "2026-01-30",
            "value": 100.00,
            "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
            "status": "PAID",
            "customer": {
                "document": "48637879012",
                "type": "CPF",
                "name": "John Doe",
                "email": "[email protected]",
                "phone": "34999991111"
            },
            "authorizationCode": "558520",
            "authorizationNsu": "169556",
            "acquirerAuthorizationCode": "null",
            "acquirerAuthorizationNsu": "169556"
        }
    ]
}

📌 O uuid da charge será necessário para ações como estorno.

Campos mais importantes da resposta

• uuid - Identificador único do pedido (Order). Este campo deve ser salvo para:

  • Consultas futuras do pedido

  • Validação de notificações recebidas via webhook

  • Conciliação financeira

  • Rastreabilidade da transação no seu sistema

• status - Status atual do pedido, exemplo:

  • PAID → pagamento confirmado

  • SENT → cobrança criada e aguardando pagamento

  • CANCELED → pedido cancelado

  • FAILED → falha no pagamento

⚠️ Nunca utilize apenas este campo como confirmação final sem validar via webhook.

• charges[].uuid - Identificador único da cobrança gerada dentro do pedido. Este campo é obrigatório para:

  • Solicitação de estorno

  • Consultas específicas da cobrança

  • Auditoria e conciliação

  📌 O uuid da charge é diferente do uuid do pedido. Ambos devem ser armazenados.

Você pode ver mais detalhes na referência completa da API clicando no link abaixo:

Criar Pedido com Token do Cartão

---

Confirmação do pagamento

Após a criação de um pedido:

• A API pode retornar o pedido como PAID de forma síncrona

• Mesmo assim, um webhook será disparado confirmando o evento

• Utilize o webhook como fonte de verdade

---

Fluxo resumido

1. Você cria o pedido via API

2. A Barte processa a cobrança

3. O cliente realiza o pagamento

4. O status da transação é atualizado

5. Um webhook é enviado ao seu sistema

6. Seu sistema valida o evento e confirma o pagamento

---

Boas práticas

• Sempre armazene:

  • uuid do pedido

  • uuid da charge

• Utilize o webhook como fonte de confirmação de pagamento

• Trate o webhook de forma idempotente

• Valide o status antes de liberar produtos ou serviços

• Use metadata para rastrear pedidos internos (ex: IDs do seu sistema)

---

O que não fazer

• Confirmar pagamento apenas pela resposta síncrona da API

• Ignorar webhooks de atualização de status

• Reutilizar pedidos para novas cobranças

• Expor sua chave de API no frontend

Criar Pedido