Pedido com Pré-captura

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

---

1. Criar um pedido (Order)

No payload da requisição, dentro do objeto payment, temos a propriedade "capture", que é um boolean (true or false).

capture = true → captura direta: Pedido simples (PIX, Boleto e Cartão de Crédito)

capture = false → pré-captura

Além disso, a pré-captura possui algumas regras que podem ser validadas em Como funciona a Pré-Captura

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": false, ← Aqui está o parâmetro que fine se é uma pré-captura ou não
    "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"
    }
  ]
}

Response

{
    "uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
    "status": "PRE_AUTHORIZED",
    "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": "PRE_AUTHORIZED",
            "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.

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:

Criar Pedido

---

2. Capturar cobrança (Charge)

Quando um pedido (order) é criado, a API retorna um array de charges. A captura do pagamento é feita utilizando o uuid da charge, e não o uuid da order.

⚠️ Importante: Se a cobrança não for capturada em até 6 dias, ela será cancelada automaticamente. Veja mais detalhes em Como funciona a Pré-Captura

Endpoint

POST /v2/charges/{uuid}/capture
https://api.barte.com/v2/charges/{uuid}/capture

{uuid} deve ser substituído pelo uuid da charge retornada na criação da order.

---

Headers

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

---

Body

Este endpoint não requer body.

---

Response

{
  "uuid": "3e40ddbe-6ef7-4cdb-ab22-6a54bc405abd",
  "title": "Fatura mensal do cliente",
  "expirationDate": "2025-09-18",
  "paidDate": "2025-09-18",
  "value": 1000,
  "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
  "status": "PAID",
  "customer": {
    "uuid": "",
    "document": "39600937000133",
    "type": "CNPJ",
    "name": "Daniel e Manoel Pães e Doces Ltda",
    "email": "[email protected]",
    "phone": "15982705981"
  },
  "authorizationCode": null,
  "authorizationNsu": "296",
  "retryable": false
}

Veja a referência api completa de como capturar uma cobrança clicando no link abaixo:

Capturar Cobrança

---

Observações importantes

• A captura sempre acontece no nível da charge

• Uma order pode possuir uma ou mais charges

• Após a captura bem-sucedida, o status da charge passa para PAID

• O uuid retornado permanece o mesmo da charge capturada

---

3. Cancelar pré-captura

O cancelamento de pré-captura deve ser utilizado somente quando a cobrança ainda não foi capturada, ou seja, quando a charge está com status PRE_AUTHORIZED.

⚠️ Importante: Se a cobrança já tiver sido capturada, este endpoint não deve ser utilizado. Nesse caso, o fluxo correto é realizar um estorno (refund).

---

Quando usar

• A charge foi criada com capture: false

• O pagamento foi apenas pré-autorizado

• O status da charge é PRE_AUTHORIZED

• O vendedor decidiu não capturar o valor

---

Endpoint

PATCH /v2/charges/{uuid}/cancel/pre-authorization
https://api.barte.com/v2/charges/{uuid}/cancel/pre-authorization

{uuid} deve ser o uuid da charge retornada na criação da order.

---

Headers

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

---

Body

Este endpoint não requer body.

---

Response

A resposta retorna um status 204 No content, indicando sucesso na operação.

---

Veja a referência completa de como cancelar uma pré-captura clicando no link abaixo:

Cancelar Pré-Captura

Observações importantes

• O cancelamento só é permitido se o status da charge for PRE_AUTHORIZED

• Após o cancelamento, o valor não será capturado

• Se a charge estiver com status PAID, o fluxo correto é estorno total ou parcial

• O cancelamento de pré-captura não gera estorno, pois o valor ainda não foi efetivamente debitado