Pedido simples (PIX, Boleto e Cartão de Crédito)

Este guia descreve o passo a passo para um vendedor criar um pedido (order) utilizando a API da Barte.

---

Criar um pedido (Order)

Endpoint

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

Headers

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

Body

Você pode ver mais detalhes sobre os métodos de pagamento aqui → Métodos de Pagamento

Cartão de Crédito

{
  "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": "Testando Criação de Order",
    "card": {
      "holderName": "JOSE DAS NEVES TEST",
      "number": "5560738292679681",
      "expiration": "10/2026",
      "cvv": "290"
    },
    "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"
    }
  ]
}

PIX

Boleto

Response

Cartão de Crédito

{
    "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"
        }
    ]
}

PIX

Boleto

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

Veja a referencia API do endpoint de criação de orders clicando no link abaixo para entender sobre todos os campos, métodos de pagamento, retornos de sucesso e erro e demais informações:

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

---

Confirmação do pagamento

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

Cartão de crédito

• 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

PIX e Boleto

• O pedido será criado com status SENT

• A cobrança ficará como SCHEDULED

• Após o pagamento:

  • O status do pedido é atualizado

  • Um webhook é disparado para o seu sistema

👉 Sempre confirme o pagamento exclusivamente via webhook.

---

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 única de confirmação de pagamento

• Trate o webhook de forma idempotente

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

• Utilize expirationDate para PIX e boleto

• 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