> 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/webhook-v2-campos.md).
# Campos do Webhook v2
Especificação completa dos campos do Webhook v2, com exemplos de payload.
***
## Tipos de evento (`eventType`)
O campo `eventType` identifica o evento ocorrido e corresponde diretamente ao status do pedido (`OrderStatus`):
| 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. |
| **cards** | `array` | Lista de cartões usados no pedido (quando disponível). Veja [Estrutura de cards](#estrutura-de-cards). |
| **refunds** | `array` | Lista de estornos. Veja [Estrutura de refunds](#estrutura-de-refunds). |
| **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. Veja [Estrutura de address](#estrutura-de-address). |
***
## Estrutura de `cards`
```json
"cards": [
{
"uuid": "0f3c2a9e-6b1d-4f7a-9c2e-8d5b1a7e4c30",
"holderName": "MARIA SILVA",
"bin": "650956",
"lastFourDigits": "1842",
"brand": "elo",
"expirationMonth": "08",
"expirationYear": "2028",
"uuidCharge": "9a1d7c52-3e84-4b6f-a0d9-27c6e5f81b44"
}
]
```
| Campo | Tipo | Descrição |
| ------------------- | -------- | -------------------------------------------------------------- |
| **uuid** | `string` | Identificador do cartão na cobrança. |
| **holderName** | `string` | Nome do titular. `""` quando o titular não é informado. |
| **bin** | `string` | Primeiros 6 dígitos do cartão. |
| **lastFourDigits** | `string` | Últimos 4 dígitos do cartão. |
| **brand** | `string` | Bandeira do cartão. |
| **expirationMonth** | `string` | Mês de validade (`MM`). `""` em pedidos de maquininha (POS). |
| **expirationYear** | `string` | Ano de validade (`YYYY`). `""` em pedidos de maquininha (POS). |
| **uuidCharge** | `string` | UUID da cobrança em que o cartão foi usado. |
{% hint style="info" %}
Em pedidos feitos na maquininha (POS), a validade do cartão não é informada: `expirationMonth` e `expirationYear` vêm como `""`. Pedidos sem pagamento com cartão enviam `cards` como `[]`.
{% endhint %}
***
## Estrutura de `refunds`
```json
"refunds": [
{
"chargeCode": "CHG-001",
"amount": 150.00,
"status": "SUCCESS",
"createdAt": "2026-01-30T10:35:00Z",
"errorReason": null
}
]
```
| Campo | Tipo | Descrição |
| --------------- | -------- | ----------------------------------------------------------------- |
| **chargeCode** | `string` | Código da cobrança estornada. |
| **amount** | `number` | Valor estornado. |
| **status** | `string` | Status do estorno (`PROCESSING`, `SUCCESS`, `FAILED`). |
| **createdAt** | `string` | Data de criação do estorno, em ISO-8601 (`YYYY-MM-DDTHH:mm:ssZ`). |
| **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"
}
```
***
## Exemplo completo — `order.paid`
```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,
"cards": [
{
"uuid": "0f3c2a9e-6b1d-4f7a-9c2e-8d5b1a7e4c30",
"holderName": "MARIA SILVA",
"bin": "411111",
"lastFourDigits": "1111",
"brand": "visa",
"expirationMonth": "08",
"expirationYear": "2028",
"uuidCharge": "c1f2e3d4-5678-9abc-def0-1234567890ab"
}
],
"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"
}
}
}
}
```
***
## Exemplo completo — `order.paid` (POS/maquininha)
{% hint style="info" %}
Transações físicas **nunca geram `order.sent`**. O primeiro evento recebido sempre será um status final (`order.paid`, `order.canceled`, `order.pre_authorized`, entre outros).
{% endhint %}
```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"
},
"cards": [
{
"uuid": "7e2b9c14-5a3d-4f81-b6e0-c9d4a1f3e872",
"holderName": "",
"bin": "554529",
"lastFourDigits": "6673",
"brand": "mastercard",
"expirationMonth": "",
"expirationYear": "",
"uuidCharge": "020207c2-247d-487a-a1b2-2a2cd618c357"
}
],
"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"
}
}
}
}
```
***
## Exemplo completo — `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,
"cards": [
{
"uuid": "0f3c2a9e-6b1d-4f7a-9c2e-8d5b1a7e4c30",
"holderName": "MARIA SILVA",
"bin": "411111",
"lastFourDigits": "1111",
"brand": "visa",
"expirationMonth": "08",
"expirationYear": "2028",
"uuidCharge": "c1f2e3d4-5678-9abc-def0-1234567890ab"
}
],
"refunds": [
{
"chargeCode": "CHG-001",
"amount": 150.00,
"status": "SUCCESS",
"createdAt": "2026-02-05T14:25:00Z",
"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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral/webhook-v2-campos.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.