V2 — Novo Padrão

Entenda o novo formato de envelope versionado do Webhook v2 da Barte.

Sellers sem integração ativa: devem integrar diretamente pelo Webhook v2 — o v1 não é mais aceito para novas integrações. A partir de 10/08/2026: o formato v1 será descontinuado para todos os sellers. Todos deverão estar no v2.

Prazo de entrega: o endpoint receptor deve responder em até 20 segundos. Requisições que ultrapassem esse tempo serão consideradas falhas e poderão ser reenviadas.

---

O que mudou?

A versão 1 do webhook entregava um payload plano, com todos os campos no nível raiz do objeto. A versão 2 introduz um envelope de evento versionado, que organiza os dados em uma estrutura hierárquica com identificação explícita do tipo de evento.

Característica	v1 (legado)	v2 (novo padrão)
Estrutura	Payload plano	Envelope com eventData aninhado
Identificação do evento	Campo status	Campo eventType (ex: order.paid)
Dados da cobrança	Misturados no raiz	Isolados em eventData.charge
Dados do comprador	Campos planos	Objeto buyer em eventData
Dados físicos (POS/TEF)	Campos planos	Objeto physicalTransactionData em eventData
Identificador de evento	Não existe	Campo eventId único por evento
Quem recebe	Sellers existentes (legado)	Sellers sem integração ativa / migrados

---

Quem recebe o Webhook v2?

• Sellers sem integração ativa: devem integrar diretamente no v2. O v1 não é aceito para novas integrações.
• Sellers com integração existente em v1: devem migrar para v2 até 10/08/2026, quando o formato v1 será descontinuado.
• Assinaturas (SUBSCRIPTION): permanecem no formato v1 e não fazem parte desta migração.

---

Comportamento de transações físicas (POS/TEF)

Diferente de cobranças digitais, transações físicas nunca geram o evento order.sent. O primeiro evento recebido para uma transação de maquininha sempre será um status final:

Primeiro evento possível	Descrição
order.paid	Transação aprovada na maquininha.
order.canceled	Transação recusada ou cancelada no terminal.
order.pre_authorized	Transação pré-autorizada no terminal.

Isso ocorre porque a transação física é processada de forma síncrona no terminal — quando o webhook é emitido, o resultado já é definitivo.

---

Headers da requisição

Header	Tipo	Descrição
X-Webhook-Timestamp	integer	Unix epoch (segundos) no momento do envio.
X-Webhook-Nonce	string	32 caracteres hexadecimais — garante unicidade por requisição.
idempotency-key	string	Chave de idempotência.
authorization	string	Token de autenticação.

💡 Dica de Segurança: Valide o X-Webhook-Timestamp (tolerância de até 5 minutos) e verifique a unicidade do X-Webhook-Nonce para evitar processamento duplicado.

---

Estrutura do envelope v2

{
  "version": "2.0",
  "domain": "ORDER",
  "eventType": "order.paid",
  "eventId": "evt_abc123",
  "eventDatetime": "2026-01-30T10:30:00Z",
  "sellerId": 123,
  "metadata": [],
  "eventData": { ... }
}

Campos do envelope

Campo	Tipo	Descrição
version	string	Versão do formato do webhook. Valor: "2.0".
domain	string	Tipo de evento: ORDER para cobranças pontuais.
eventType	string	Tipo do evento ocorrido. Ver Tipos de evento abaixo.
eventId	string	Identificador único do evento (distinto do UUID do pedido).
eventDatetime	string	Data e hora do evento no formato ISO 8601.
sellerId	integer	Identificador interno do vendedor.
metadata	array	Lista de pares { key, value } com informações adicionais.
eventData	object	Dados completos do pedido e da cobrança. Ver Campos do eventData abaixo.

O campo version indica o formato de entrega. Sempre valide esse campo para garantir compatibilidade com a versão integrada.

---

Tipos de evento (eventType)

O campo eventType identifica o evento ocorrido e corresponde diretamente ao status do pedido:

eventType	Descrição
order.sent	Pedido criado.
order.paid	Pagamento confirmado.
order.partially_paid	Pagamento parcial recebido.
order.late	Pagamento em atraso.
order.abandoned	Pedido abandonado (atraso superior a 90 dias).
order.canceled	Pedido cancelado.
order.refund	Pedido estornado.
order.chargeback	Pedido com chargeback.
order.pre_authorized	Pedido pré-autorizado.
order.invalid	Pedido inválido.

---

Campos do eventData

O objeto eventData concentra todos os dados do pedido e da cobrança associada.

Campos do pedido

Campo	Tipo	Descrição
id	string	Identificador único do pedido. Use com GET /v2/orders/{uuid}.
status	string	Status atual do pedido. Espelha o eventType em formato legado.
amount	number	Valor total da transação (com decimal, ex: 150.00).
paymentMethod	string	Método de pagamento utilizado (ex: CREDIT_CARD_EARLY_SELLER, PIX, BOLETO).
description	string	Descrição informada na criação do pedido.
charge	object	Dados da cobrança associada. Ver Campos da cobrança abaixo.
physicalTransactionData	object	Dados do terminal físico. null em transações online. Ver Campos de transação física abaixo.
refunds	array	Lista de estornos. Ver Estrutura de refunds abaixo.
buyer	object	Dados do comprador. Ver Campos do comprador abaixo.

Campos da cobrança (charge)

Campo	Tipo	Descrição
id	string	UUID da cobrança.
originRequest	string	Origem da transação: API, POS, TEF, entre outros.
authorizationCode	string	Código de autorização da transação.
authorizationNsu	string	NSU (Número Sequencial Único) da transação.
acquirerAuthorizationCode	string	Código de autorização da adquirente.
acquirerAuthorizationNsu	string	NSU da adquirente.
paidDate	string	Data de pagamento no formato YYYY-MM-DD.
cardId	string	Em transações online: ID do cartão gerado para a transação. Em transações físicas (POS/TEF): BIN do cartão utilizado.
brand	string	Bandeira do cartão (ex: VISA, MASTERCARD, ELO).
fees	array	Lista de taxas cobradas. null se o evento for order.sent ou sem charge associada; [] se não há taxas registradas. Ver Estrutura de fees abaixo.
installments	integer	Número de parcelas.

Campos de transação física (physicalTransactionData)

Presentes apenas quando originRequest for POS ou TEF. Caso contrário, o objeto é null.

Campo	Tipo	Descrição
providerTransactionId	string	ID gerado na transação física (correlation ID).
terminalId	string	Identificador do terminal POS.
serialNumber	string	Número de série do terminal POS.

Campos do comprador (buyer)

Campo	Tipo	Descrição
uuid	string	Identificador único do comprador. Use com GET /v2/buyers/{uuid}.
documentBuyer	string	CPF ou CNPJ do comprador.
email	string	E-mail do comprador.
address	object	Endereço do comprador. Ver Estrutura de address abaixo.

---

Estrutura de refunds

"refunds": [
  {
    "chargeCode": "CHG-001",
    "amount": 150.00,
    "status": "SUCCESS",
    "createdAt": "2026-01-30",
    "errorReason": null
  }
]

Campo	Tipo	Descrição
chargeCode	string	Código da cobrança estornada.
amount	number	Valor estornado.
status	string	Status do estorno (SUCCESS, PENDING, ERROR).
createdAt	string	Data de criação do estorno (YYYY-MM-DD).
errorReason	string	Motivo do erro, quando aplicável.

---

Estrutura de fees

"fees": [
  {
    "name": "Credit card",
    "amount": 3.49
  }
]

Campo	Tipo	Descrição
name	string	Tipo da taxa. Ver valores possíveis abaixo.
amount	number	Valor da taxa em reais.

Valores possíveis para name:

Valor	Descrição
Bankslip	Taxa sobre transação de boleto bancário.
Credit card	Taxa sobre transação de cartão de crédito.
Debit card	Taxa sobre transação de cartão de débito.
PIX	Taxa sobre transação via PIX.
Reversal	Taxa cobrada sobre estornos.
Antifraud	Taxa de antifraude.
Gateway	Taxa de gateway (pode ser débito ou crédito).
Barte	Taxa da plataforma Barte (pode ser débito ou crédito).
Reversal Barte	Estorno de taxa da plataforma Barte.
Revenue Anticipation	Imposto incidente sobre antecipação de recebíveis.
Anticipation	Taxa de antecipação de recebíveis (pode ser débito ou crédito).
Partner	Taxa cobrada pelo parceiro integrador.
POS Rental	Taxa de aluguel de terminal POS.

---

Estrutura de address

"address": {
  "country": "BR",
  "state": "SP",
  "city": "São Paulo",
  "district": "Pinheiros",
  "street": "Rua dos Pinheiros",
  "zipCode": "05422-001",
  "number": "850",
  "complement": "Sala 12"
}

---

Exemplos de payload

order.paid — via API

{
  "version": "2.0",
  "domain": "ORDER",
  "eventType": "order.paid",
  "eventId": "evt_abc123",
  "eventDatetime": "2026-01-30T10:30:00Z",
  "sellerId": 123,
  "metadata": [
    { "key": "pedido_interno", "value": "PED-9981" }
  ],
  "eventData": {
    "id": "5503ad3a-d9c4-4072-a7cb-12cf2dd0eaa7",
    "status": "PAID",
    "amount": 150.00,
    "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
    "description": "Compra de produto X",
    "charge": {
      "id": "c1f2e3d4-5678-9abc-def0-1234567890ab",
      "originRequest": "API",
      "authorizationCode": "496847",
      "authorizationNsu": "155224",
      "acquirerAuthorizationCode": "",
      "acquirerAuthorizationNsu": "",
      "paidDate": "2026-01-30",
      "cardId": "card_789",
      "brand": "VISA",
      "fees": [
        { "name": "Credit card", "amount": 16.21 },
        { "name": "Antifraud", "amount": 0.50 }
      ],
      "installments": 1
    },
    "physicalTransactionData": null,
    "refunds": [],
    "buyer": {
      "uuid": "33236116-743a-4c1c-afc4-79b8d5dbb5b5",
      "documentBuyer": "12345678900",
      "email": "[e-mail]",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "Pinheiros",
        "street": "Rua dos Pinheiros",
        "zipCode": "05422-001",
        "number": "850",
        "complement": "Sala 12"
      }
    }
  }
}

---

order.paid — via POS/maquininha

{
  "version": "2.0",
  "domain": "ORDER",
  "eventType": "order.paid",
  "eventId": "c542447a-4918-4225-aab8-3e374ca927ef",
  "eventDatetime": "2026-07-07T13:40:00.656126122Z",
  "sellerId": 4924,
  "metadata": null,
  "eventData": {
    "id": "b513157e-0f23-410c-9f98-ee0c0b11a628",
    "status": "PAID",
    "amount": 25.00,
    "paymentMethod": "CREDIT_CARD",
    "description": "Pagamento referente à transação realizada em ponto de venda físico.",
    "charge": {
      "id": "020207c2-247d-487a-a1b2-2a2cd618c357",
      "originRequest": "POS",
      "authorizationCode": "627632",
      "authorizationNsu": "237645",
      "acquirerAuthorizationCode": "282240",
      "acquirerAuthorizationNsu": "000282240",
      "paidDate": "2026-07-07",
      "cardId": "554529******6673",
      "brand": "mastercard",
      "fees": [
        { "name": "Credit card", "amount": 1.07 }
      ],
      "installments": 1
    },
    "physicalTransactionData": {
      "providerTransactionId": "00902339-2439-3159-815b-6f1eda2e1dec",
      "terminalId": "00000112",
      "serialNumber": "PB1S248S76065"
    },
    "refunds": [],
    "buyer": {
      "uuid": "32110b1a-388d-4568-be9a-0892df055487",
      "documentBuyer": "44522660000108",
      "email": "[e-mail]",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "BELA VISTA",
        "street": "PAULISTA",
        "zipCode": "01310200",
        "number": "1636",
        "complement": "SALA  1504"
      }
    }
  }
}

---

order.refund

{
  "version": "2.0",
  "domain": "ORDER",
  "eventType": "order.refund",
  "eventId": "evt_refund_001",
  "eventDatetime": "2026-02-05T14:20:00Z",
  "sellerId": 123,
  "metadata": [],
  "eventData": {
    "id": "5503ad3a-d9c4-4072-a7cb-12cf2dd0eaa7",
    "status": "REFUND",
    "amount": 150.00,
    "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
    "description": "Compra de produto X",
    "charge": {
      "id": "c1f2e3d4-5678-9abc-def0-1234567890ab",
      "originRequest": "API",
      "authorizationCode": "496847",
      "authorizationNsu": "155224",
      "acquirerAuthorizationCode": "",
      "acquirerAuthorizationNsu": "",
      "paidDate": "2026-01-30",
      "cardId": "card_789",
      "brand": "VISA",
      "fees": [
        { "name": "Credit card", "amount": 16.21 },
        { "name": "Antifraud", "amount": 0.50 }
      ],
      "installments": 1
    },
    "physicalTransactionData": null,
    "refunds": [
      {
        "chargeCode": "CHG-001",
        "amount": 150.00,
        "status": "SUCCESS",
        "createdAt": "2026-02-05",
        "errorReason": null
      }
    ],
    "buyer": {
      "uuid": "33236116-743a-4c1c-afc4-79b8d5dbb5b5",
      "documentBuyer": "12345678900",
      "email": "[e-mail]",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "Pinheiros",
        "street": "Rua dos Pinheiros",
        "zipCode": "05422-001",
        "number": "850",
        "complement": "Sala 12"
      }
    }
  }
}

---

Em caso de dúvidas, entre em contato com o nosso time através do suporte disponibilizado.