> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral.md).
# V2 — Novo Padrão
{% hint style="info" %}
**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.
{% endhint %}
{% hint style="warning" %}
**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.
{% endhint %}
***
## 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. |
{% hint style="info" %}
Isso ocorre porque a transação física é processada de forma síncrona no terminal — quando o webhook é emitido, o resultado já é definitivo.
{% endhint %}
***
## 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
```json
{
"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](#tipos-de-evento-eventtype) 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](#campos-do-eventdata) abaixo. |
{% hint style="warning" %}
O campo `version` indica o formato de entrega. Sempre valide esse campo para garantir compatibilidade com a versão integrada.
{% endhint %}
***
## 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](#campos-da-cobrança-charge) abaixo. |
| **physicalTransactionData** | `object` | Dados do terminal físico. `null` em transações online. Ver [Campos de transação física](#campos-de-transação-física-physicaltransactiondata) abaixo. |
| **refunds** | `array` | Lista de estornos. Ver [Estrutura de refunds](#estrutura-de-refunds) abaixo. |
| **buyer** | `object` | Dados do comprador. Ver [Campos do comprador](#campos-do-comprador-buyer) 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](#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](#estrutura-de-address) abaixo. |
***
## Estrutura de `refunds`
```json
"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`
```json
"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`
```json
"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
```json
{
"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": "cliente@example.com",
"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
```json
{
"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": "teste@barte.com",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "BELA VISTA",
"street": "PAULISTA",
"zipCode": "01310200",
"number": "1636",
"complement": "SALA 1504"
}
}
}
}
```
***
### `order.refund`
```json
{
"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": "cliente@example.com",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
}
}
}
}
```
***
:tickets: Em caso de dúvidas, entre em contato com o nosso time através do suporte disponibilizado.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.