> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks de cobrança

> Eventos do ciclo de vida da cobrança: criação, espera, pagamento, recusa, estorno, pré-chargeback, bloqueio e o postback legado charge.updated.

Os webhooks de cobrança avisam o seu sistema a cada passo de uma cobrança (charge): quando ela é criada, quando aguarda pagamento, quando é paga, recusada ou estornada, e quando entra em disputa. O postback legado `charge.updated`, entregue só ao `postbackUrl`, complementa esses eventos com recusas assíncronas e com o chargeback formalizado.

> [!NOTE]
>
> **Para o negócio:** `charge.paid` é o sinal para liberar o pedido, `charge.refunded` é o sinal para registrar a devolução e `charge.blocked` avisa que uma venda entrou em análise de disputa. O chargeback formalizado chega pelo `charge.updated`, no `postbackUrl`, e, quando o valor é revertido do saldo, também como `charge.refunded`. Se a sua operação vende com Pix, o `charge.paid` é a forma automática de saber que o cliente pagou.

## Quando usar

| Situação | Evento que importa |
| - | - |
| Liberar pedido ou acesso após o pagamento | `charge.paid` |
| Mostrar "aguardando pagamento" no painel do lojista | `charge.created` e `charge.pending` |
| Registrar uma recusa no seu sistema | Resposta de `POST /v1/charges` e, de forma complementar, `charge.refused` ou `charge.failed` |
| Registrar a devolução no financeiro | `charge.refunded` |
| Marcar o pedido como em disputa | `charge.pre_chargeback` (alerta) e `charge.blocked` (bloqueio por MED ou chargeback em análise) |
| Registrar o chargeback formalizado | `charge.updated` com `status: "chargeback"`, no `postbackUrl` |

## Como funciona

O desenho abaixo mostra quais eventos saem da criação da cobrança até o pagamento ou a recusa.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    POST(["Sua aplicação chama<br/>POST /v1/charges"]):::lojista
    CR[["charge.created<br/>sempre, na criação"]]:::evento
    RES{"Como terminou<br/>a criação?"}:::decisao
    PEN["pending<br/>ex.: Pix gerado"]:::alerta
    AN["in_analysis<br/>análise antifraude"]:::alerta
    AUT["authentication_required<br/>3DS gerenciado"]:::alerta
    REC["refused ou failed"]:::erro
    EPEN[["charge.pending"]]:::evento
    PAID["paid<br/>pagamento confirmado"]:::ok
    EPAID[["charge.paid<br/>com paid_at"]]:::evento
    EREC[["charge.refused<br/>ou charge.failed"]]:::evento
    ASY["Recusa informada depois<br/>pelo adquirente: negada,<br/>cancelada ou expirada"]:::erro
    UPD[["Só charge.updated<br/>na postbackUrl"]]:::evento
    POST --> CR --> RES
    RES --> AN
    RES --> PEN
    RES -->|"aprovada na hora"| PAID
    RES --> AUT
    RES -->|"recusada"| REC
    PEN --> EPEN
    PEN -->|"comprador paga"| PAID
    AN -->|"aprovada"| PAID
    AUT -->|"autenticou"| PAID
    AUT -->|"3DS termina<br/>em recusa"| REC
    PAID --> EPAID
    REC --> EREC
    PEN -->|"cancelado<br/>ou expirado"| ASY
    AN -->|"negada"| ASY
    ASY --> UPD
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
```

Os eventos do envelope padrão vão aos endpoints e à `postbackUrl`. O `charge.updated` vai só à `postbackUrl` e também sai em outras situações, como o pagamento de um Pix.

**1. A cobrança é criada**

Sua aplicação chama `POST /v1/charges`. A resposta síncrona traz o `id`, o `status` e, no Pix, o QR Code.

**2. Eventos da criação**

A Finvia envia `charge.created`. Se o processamento termina em `pending` (por exemplo, Pix gerado), envia também `charge.pending`. Se a cobrança é recusada ou falha na criação, envia `charge.refused` ou `charge.failed`.

**3. Pagamento confirmado**

Quando o pagamento é confirmado, na hora ou depois, chega `charge.paid` com `paid_at` preenchido.

**4. Pós-venda**

Estorno concluído gera `charge.refunded`. Alerta de pré-chargeback gera `charge.pre_chargeback`. Bloqueio da cobrança gera `charge.blocked`. Quem informou `postbackUrl` recebe ainda o `charge.updated` legado nas situações descritas em [Postback legado](#postback-legado).

## Eventos disponíveis

| Evento | Quando é enviado | Destinos |
| - | - | - |
| `charge.created` | A cobrança foi criada | Endpoints e `postbackUrl` |
| `charge.pending` | O processamento terminou em `pending` (ex.: Pix com QR Code gerado) | Endpoints e `postbackUrl` |
| `charge.paid` | O pagamento foi confirmado, na hora ou depois, pelo adquirente | Endpoints e `postbackUrl` |
| `charge.refused` | A cobrança foi recusada na criação ou ao final do 3DS gerenciado | Endpoints e `postbackUrl` |
| `charge.failed` | A cobrança falhou na criação ou ao final do 3DS gerenciado | Endpoints e `postbackUrl` |
| `charge.refunded` | O estorno foi concluído, inclusive o estorno feito no alerta de pré-chargeback e a reversão de saldo de um chargeback | Endpoints e `postbackUrl` |
| `charge.pre_chargeback` | Um alerta de pré-chargeback foi registrado | Endpoints e `postbackUrl` |
| `charge.blocked` | A cobrança foi bloqueada (MED ou chargeback em análise) | Endpoints e `postbackUrl` |
| `charge.updated` | Postback legado: mudança de status informada pelo adquirente, fim do 3DS gerenciado com recusa ou falha, bloqueio e alerta de pré-chargeback | Só `postbackUrl` |

Os endpoints que recebem cada evento seguem a regra da conta dona da cobrança, explicada em [Quem recebe cada evento](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#quem-recebe-cada-evento). Uma cobrança que fica em `in_analysis` ou `authentication_required` na criação gera só o `charge.created`. O evento seguinte depende do desfecho.

## Status da cobrança

O campo `status` dentro de `data` pode ter estes valores:

| Valor | Significado |
| - | - |
| `pending` | Aguardando pagamento |
| `paid` | Pago com sucesso. Continua `paid` durante um bloqueio |
| `refused` | Recusado |
| `failed` | Falha no processamento |
| `refunded` | Estornado |
| `in_analysis` | Enviado para revisão manual pela análise antifraude |
| `authentication_required` | Aguardando o comprador concluir a autenticação no endereço de `authenticationUrl` |
| `pre_chargeback` | Alerta de pré-chargeback registrado (veja [Pré-chargeback](#pré-chargeback)) |
| `chargeback` | Chargeback formalizado (veja [Chargeback formalizado](#chargeback-formalizado)) |

A tabela completa, com o que fazer em cada status, está em [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md).

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Formato de nomes | O envelope padrão usa **snake\_case** no primeiro nível de `data` (`psp_ref_id`, `paid_at`) e camelCase dentro dos objetos aninhados. O `charge.updated` usa **camelCase** em todos os níveis. Veja [Formato por família](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#formato-por-família) |
| Valores | Em reais: `100` significa R\$ 100,00 |
| `charge.updated` | Vai **somente** ao `postbackUrl`. Os endpoints nunca recebem esse evento |
| Recusa síncrona | Volta na resposta de `POST /v1/charges` e também em `charge.refused` ou `charge.failed`, no máximo uma vez por cobrança. A resposta continua sendo a fonte principal |
| Recusa assíncrona | Recusa ou falha informada depois pelo adquirente gera só o `charge.updated` no `postbackUrl` |
| Motivo da recusa | O envelope padrão não traz o motivo. Ele aparece em `GET /v1/charges/{id}` e no `charge.updated` |
| Recusa em assinatura | A cobrança recorrente recusada gera `subscription.payment_failed` e não gera `charge.refused` nem `charge.failed` |
| Teste e produção | Cobranças de teste chegam com `livemode: false` e `data.is_test: true` nos mesmos endpoints |
| Entrega | Veja [Entrega e retentativas](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#entrega-e-retentativas) |

> [!WARNING]
>
> O status `chargeback` e as recusas assíncronas só chegam pelo `charge.updated`. Os endpoints recebem, no chargeback, apenas o `charge.refunded`, e só quando o valor é revertido do saldo. Se a sua operação precisa desses avisos, **informe `postbackUrl` em todas as cobranças**. Sem ele, confirme o estado das cobranças em disputa ou em análise com `GET /v1/charges/{id}`.

## Envelope padrão

Todos os eventos de cobrança, exceto o `charge.updated`, usam o envelope padrão:

```json theme={null}
{
  "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a",
  "event": "charge.paid",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid"
  }
}
```

O `id` da raiz identifica o evento: cada evento tem o seu, e é ele que a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos) usa. `livemode` é `false` em cobranças de teste. O objeto `data` traz a cobrança (o exemplo acima foi resumido).

### Campos do objeto `data`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID da cobrança. É o mesmo usado em `GET /v1/charges/{id}` |
| `status` | string | Status atual (veja a tabela de status) |
| `psp_ref_id` | string \| null | ID de referência no processador de pagamento |
| `amount` | number | Valor bruto, em reais |
| `currency` | string | Código ISO da moeda (ex.: `BRL`) |
| `spread` | number | Spread aplicado |
| `anticipation_fee_estimated` | number | Taxa de antecipação estimada (cartão de crédito; `0` para os outros meios) |
| `net` | number | Valor líquido, em reais |
| `customer` | object \| null | Dados do cliente |
| `payment_method` | object | Dados do meio de pagamento, com chaves internas em camelCase |
| `merchant_id` | string | ID da conta dona da cobrança. Em eventos de subconta recebidos pela master, é o id da subconta |
| `payment_details` | object \| null | Detalhes adicionais. No Pix, traz `endToEndId`, `copyPaste` e `qrCodeBase64` (chaves internas em camelCase) |
| `shipping_address` | object \| null | Endereço de entrega, com chaves internas em camelCase |
| `tracking_info` | object \| null | Informações de rastreio, com chaves internas em camelCase |
| `three_ds` | object \| null | Dados da autenticação 3D Secure, com chaves internas em camelCase |
| `freight_details` | object \| null | Dados de frete, com chaves internas em camelCase |
| `metadata` | object \| null | Metadados enviados por você na criação, com as chaves exatamente como foram enviadas |
| `postback_url` | string \| null | URL de postback informada na cobrança |
| `paid_at` | string \| null | Data e hora do pagamento (ISO 8601) |
| `is_test` | boolean \| null | `true` se a cobrança é de teste |
| `is_blocked`, `blocked_at`, `blocked_reason` | | Dados do bloqueio, presentes no `charge.blocked`. Veja [Bloqueio](#bloqueio) |
| `chargeback_alert_refunded` | boolean | `true` no `charge.refunded` gerado pelo estorno de um alerta de pré-chargeback |
| `created_at` | string | Data e hora de criação (ISO 8601) |
| `updated_at` | string | Data e hora da última atualização (ISO 8601) |
| `deleted_at` | string \| null | Data e hora de exclusão, se houver |

> [!TIP]
>
> **Para o desenvolvedor:** use `paid_at` como data oficial do pagamento na sua conciliação. O webhook pode chegar bem depois do pagamento.

### Objeto `customer`

```json theme={null}
{
  "id": "cu_abc123",
  "name": "Joao Silva",
  "email": "joao@email.com",
  "document": {
    "id": "52998224725",
    "type": "cpf"
  },
  "phone": "+5511987654321"
}
```

### Objeto `payment_method`

As chaves internas ficam em camelCase, no formato em que foram gravadas:

> [tab] Cartão de crédito
>
> ```json theme={null}
> {
>   "type": "credit_card",
>   "installments": 3,
>   "holderName": "JOAO SILVA",
>   "expirationMonth": "12",
>   "expirationYear": "2030",
>   "firstSix": "411111",
>   "lastFour": "1111"
> }
> ```

> [tab] Pix
>
> No Pix, o objeto contém apenas o tipo. Os dados do QR Code ficam em `payment_details`.
>
> ```json theme={null}
> { "type": "pix" }
> ```

### Objeto `payment_details` (Pix)

A chave externa é `payment_details` (snake\_case), mas os campos **internos** são camelCase, no mesmo formato da resposta da API:

```json theme={null}
{
  "endToEndId": "E12345678202401151035abcdef123456",
  "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `endToEndId` | string | Identificador End to End do Pix |
| `copyPaste` | string | Código Pix "copia e cola" (BR Code EMV) |
| `qrCodeBase64` | string \| null | Imagem do QR Code (PNG, 256x256) em data URI, gerada a partir do `copyPaste`. Pode ser usada direto no `src` de uma tag `<img>` |

> [!NOTE]
>
> `qrCodeBase64` pode vir `null` ou ausente em cobranças criadas antes da introdução do campo ou quando a imagem não pôde ser gerada. Nesses casos, gere o QR Code a partir do `copyPaste`.

### Objeto `shipping_address`

As chaves internas ficam em camelCase, como foram enviadas em `shippingAddress` na criação da cobrança. O país volta exatamente como foi enviado, no padrão ISO 3166-1 alpha-3 (envie em maiúsculas, como `BRA`).

```json theme={null}
{
  "postalCode": "01310-100",
  "addressLine1": "Av. Paulista, 1000",
  "addressLine2": "Apto 42",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BRA"
}
```

### Objeto `tracking_info`

```json theme={null}
{
  "trackingCode": "BR123456789BR",
  "shippingProvider": "Correios",
  "trackingUrl": "https://rastreamento.correios.com.br/...",
  "trackingStatus": "on_the_way"
}
```

`trackingStatus` pode ser `awaiting_shipment`, `on_the_way` ou `delivered`.

## Payloads por evento

> [tab] charge.created
>
> Enviado logo após a criação de uma nova cobrança.
>
> ```json theme={null}
> {
>   "id": "evt_5TzWq1Lb8NcY2dR7kH4mX9vJ",
>   "event": "charge.created",
>   "livemode": true,
>   "data": {
>     "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "status": "pending",
>     "psp_ref_id": null,
>     "amount": 100,
>     "currency": "BRL",
>     "spread": 0,
>     "anticipation_fee_estimated": 0,
>     "net": 96.5,
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "id": "52998224725", "type": "cpf" },
>       "phone": null
>     },
>     "payment_method": { "type": "pix" },
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_details": {
>       "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
>       "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
>     },
>     "shipping_address": null,
>     "tracking_info": null,
>     "metadata": { "orderId": "ORD-123" },
>     "postback_url": "https://meusite.com.br/webhooks/finvia",
>     "paid_at": null,
>     "is_test": false,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-15T10:30:00.000Z",
>     "deleted_at": null
>   }
> }
> ```

> [tab] charge.pending
>
> Enviado quando o processamento termina em `pending` (por exemplo, Pix gerado).
>
> ```json theme={null}
> {
>   "id": "evt_8GfK3sPq6VwD1yA9nE5rB2tM",
>   "event": "charge.pending",
>   "livemode": true,
>   "data": {
>     "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "status": "pending",
>     "psp_ref_id": "pix_ref_abc123",
>     "amount": 100,
>     "currency": "BRL",
>     "spread": 0,
>     "anticipation_fee_estimated": 0,
>     "net": 96.5,
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "id": "52998224725", "type": "cpf" },
>       "phone": null
>     },
>     "payment_method": { "type": "pix" },
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_details": {
>       "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
>       "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
>     },
>     "shipping_address": null,
>     "tracking_info": null,
>     "metadata": { "orderId": "ORD-123" },
>     "postback_url": "https://meusite.com.br/webhooks/finvia",
>     "paid_at": null,
>     "is_test": false,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-15T10:30:01.000Z",
>     "deleted_at": null
>   }
> }
> ```

> [tab] charge.paid
>
> Enviado quando o pagamento é confirmado.
>
> ```json theme={null}
> {
>   "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a",
>   "event": "charge.paid",
>   "livemode": true,
>   "data": {
>     "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "status": "paid",
>     "psp_ref_id": "pix_ref_abc123",
>     "amount": 100,
>     "currency": "BRL",
>     "spread": 1,
>     "anticipation_fee_estimated": 0,
>     "net": 95.5,
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "id": "52998224725", "type": "cpf" },
>       "phone": null
>     },
>     "payment_method": { "type": "pix" },
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_details": {
>       "endToEndId": "E12345678202401151035abcdef123456",
>       "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
>       "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
>     },
>     "shipping_address": null,
>     "tracking_info": null,
>     "metadata": { "orderId": "ORD-123" },
>     "postback_url": "https://meusite.com.br/webhooks/finvia",
>     "paid_at": "2024-01-15T10:35:00.000Z",
>     "is_test": false,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-15T10:35:00.000Z",
>     "deleted_at": null
>   }
> }
> ```

> [tab] charge.refused
>
> Enviado quando a cobrança é recusada na criação ou ao final do 3DS gerenciado. Em falha de processamento, o evento é `charge.failed`, com `status` `failed`. O motivo da recusa não vem no envelope: consulte `GET /v1/charges/{id}`.
>
> ```json theme={null}
> {
>   "id": "evt_6KpZ2wQ9mT4rV7cX1bN8yL3s",
>   "event": "charge.refused",
>   "livemode": true,
>   "data": {
>     "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
>     "status": "refused",
>     "psp_ref_id": "card_ref_def456",
>     "amount": 599.7,
>     "currency": "BRL",
>     "spread": 0,
>     "anticipation_fee_estimated": 0,
>     "net": 0,
>     "customer": {
>       "id": "cu_def456",
>       "name": "Maria Souza",
>       "email": "maria@email.com",
>       "document": { "id": "52998224725", "type": "cpf" },
>       "phone": null
>     },
>     "payment_method": {
>       "type": "credit_card",
>       "installments": 3,
>       "holderName": "MARIA SOUZA",
>       "expirationMonth": "10",
>       "expirationYear": "2028",
>       "firstSix": "444433",
>       "lastFour": "1112"
>     },
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_details": null,
>     "shipping_address": null,
>     "tracking_info": null,
>     "metadata": null,
>     "postback_url": null,
>     "paid_at": null,
>     "is_test": false,
>     "created_at": "2024-01-15T11:00:00.000Z",
>     "updated_at": "2024-01-15T11:00:02.000Z",
>     "deleted_at": null
>   }
> }
> ```

> [tab] charge.refunded
>
> Enviado depois que um estorno é concluído com sucesso.
>
> ```json theme={null}
> {
>   "id": "evt_4MbR9dT2gY7vC1xK5qW8nP3h",
>   "event": "charge.refunded",
>   "livemode": true,
>   "data": {
>     "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "status": "refunded",
>     "psp_ref_id": "pix_ref_abc123",
>     "amount": 100,
>     "currency": "BRL",
>     "spread": 1,
>     "anticipation_fee_estimated": 0,
>     "net": 95.5,
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "id": "52998224725", "type": "cpf" },
>       "phone": null
>     },
>     "payment_method": { "type": "pix" },
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_details": {
>       "endToEndId": "E12345678202401151035abcdef123456",
>       "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
>       "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
>     },
>     "shipping_address": null,
>     "tracking_info": null,
>     "metadata": { "orderId": "ORD-123" },
>     "postback_url": "https://meusite.com.br/webhooks/finvia",
>     "paid_at": "2024-01-15T10:35:00.000Z",
>     "is_test": false,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-15T11:00:00.000Z",
>     "deleted_at": null
>   }
> }
> ```

> [tab] charge.blocked
>
> Enviado quando a cobrança é bloqueada (MED ou chargeback em análise). O status continua `paid`.
>
> ```json theme={null}
> {
>   "id": "evt_9HqW3eR6tY1uI4oP7aS2dF5g",
>   "event": "charge.blocked",
>   "livemode": true,
>   "data": {
>     "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "status": "paid",
>     "amount": 100,
>     "currency": "BRL",
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "payment_method": { "type": "pix" },
>     "is_blocked": true,
>     "blocked_at": "2024-01-20T14:00:00.000Z",
>     "blocked_reason": "MED em análise",
>     "paid_at": "2024-01-15T10:35:00.000Z",
>     "is_test": false
>   }
> }
> ```
>
> O exemplo foi resumido. O `data` traz os mesmos campos dos outros eventos.

> [!NOTE]
>
> Repare nos exemplos que `spread` e `net` podem mudar entre `charge.pending` e `charge.paid` (de `0` e `96.5` para `1` e `95.5`). Grave os valores financeiros a partir do `charge.paid` ou da consulta à API depois do pagamento.

## Recusas

| Situação | O que você recebe |
| - | - |
| Recusa ou falha na criação (`POST /v1/charges` ou checkout do link devolvem `refused` ou `failed`) | A resposta HTTP e, de forma complementar, `charge.refused` ou `charge.failed` nos endpoints e no `postbackUrl` |
| Recusa ou falha ao final do 3DS gerenciado | `charge.refused` ou `charge.failed` nos endpoints e no `postbackUrl`, mais o `charge.updated` no `postbackUrl` |
| Recusa ou falha informada depois pelo adquirente (cobrança em `in_analysis` negada, Pix cancelado ou expirado) | Só o `charge.updated` no `postbackUrl`. Os endpoints não recebem nada |
| Cobrança recorrente de assinatura recusada | `subscription.payment_failed`. Não há `charge.refused` nem `charge.failed` |

Conforme o adquirente, o status final de uma recusa assíncrona pode ser `failed` em vez de `refused`. No adquirente principal de cartão, a recusa assíncrona, o cancelamento e a expiração terminam em `failed`. Trate os dois valores como "não pago".

## Bloqueio

Quando a cobrança é bloqueada, por exemplo por um MED (Mecanismo Especial de Devolução, do Pix) ou por um chargeback em análise, a Finvia envia `charge.blocked` aos endpoints e ao `postbackUrl`. Quem tem `postbackUrl` recebe também o `charge.updated`.

* O status continua `paid`. O bloqueio é uma marcação: `is_blocked: true`, com `blocked_at` e `blocked_reason` (no `charge.updated`, `isBlocked`, `blockedAt` e `blockedReason`).
* `blocked_reason` é um texto livre preenchido pela Finvia e pode vir vazio. Não decida o fluxo por ele.
* A liberação do bloqueio **não gera evento**. Para saber se uma cobrança continua bloqueada, consulte `GET /v1/charges/{id}` e leia `isBlocked`. O `blockedAt` continua preenchido depois da liberação, então não o use para esse fim.
* `GET /v1/charges?status=blocked` lista as cobranças bloqueadas.

O fluxo completo, com os desfechos, está em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Pré-chargeback

Um alerta de pré-chargeback chega quando o portador contestou a compra junto ao banco emissor **antes** de o chargeback ser formalizado (programas como Ethoca e Verifi). A cobrança passa para o status `pre_chargeback`, e a Finvia envia:

* `charge.pre_chargeback`, no envelope padrão, aos endpoints e ao `postbackUrl`;
* `charge.updated` ao `postbackUrl`, com `chargebackAlertRefunded` e `chargebackAlertReason`;
* `charge.refunded`, com `chargeback_alert_refunded: true`, quando o valor é estornado como parte do tratamento do alerta.

| Campo no `charge.updated` | Tipo | Descrição |
| - | - | - |
| `chargebackAlertRefunded` | boolean \| null | `true`: o valor **já foi estornado** ao portador como parte do tratamento do alerta. `false`: disputa aberta **sem** estorno |
| `chargebackAlertReason` | string \| null | Motivo ou referência informada no alerta (ex.: `"Chargeback - NSU 123456789"`) |

Ao registrar o alerta, a Finvia decide se devolve ou não o valor (por padrão, devolve):

* **Com estorno** (o caso padrão): o valor é devolvido imediatamente ao portador para evitar que o alerta vire um chargeback formal, com as taxas e penalidades que ele traz. O pedido deve ser tratado como **estornado**.
* **Sem estorno**: decisão operacional de contestar e não devolver (por exemplo, mercadoria já entregue com prova de entrega). A disputa segue aberta e o pedido **não** deve ser marcado como estornado.

```json theme={null}
{
  "event": "charge.updated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pre_chargeback",
    "chargebackAlertRefunded": true,
    "chargebackAlertReason": "Chargeback - NSU 123456789",
    "amount": 100,
    "currency": "BRL",
    "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "postbackUrl": "https://meusite.com.br/webhooks/finvia",
    "isTest": false
  }
}
```

| Recebido | O que fazer no pedido |
| - | - |
| `charge.refunded` com `chargeback_alert_refunded: true`, ou `charge.updated` com `chargebackAlertRefunded: true` | Marcar como **estornado** (o valor já voltou ao portador) |
| `charge.pre_chargeback` sem `charge.refunded`, ou `charge.updated` com `chargebackAlertRefunded: false` | Marcar como **em disputa**, sem estorno |

> [!NOTE]
>
> **Para o negócio:** num pré-chargeback com estorno, o dinheiro já saiu. Se o produto ainda não foi enviado, segure o envio. Se já foi, acione o seu processo de recuperação com o cliente. No caso sem estorno, prepare a documentação de entrega, porque a disputa continua.

## Chargeback formalizado

Não existe um evento dedicado ao chargeback formalizado no envelope padrão. Quando o adquirente informa a disputa, a cobrança passa para `chargeback` e a Finvia avisa assim:

| Situação | O que você recebe |
| - | - |
| Sempre que a cobrança vira `chargeback` | `charge.updated` com `status: "chargeback"`, no `postbackUrl` |
| A reversão devolve o valor do seu saldo (a cobrança não tinha sido estornada no pré-chargeback) | Também `charge.refunded`, no envelope padrão, aos endpoints e ao `postbackUrl`. O `status` dentro desse payload pode vir `refunded` ou `chargeback` |
| A cobrança já tinha sido estornada no alerta de pré-chargeback | Só o `charge.updated` no `postbackUrl`. Os endpoints não recebem nada |

A transição automática para `chargeback` acontece nos adquirentes de cartão que enviam esse aviso. Em qualquer caso, confirme o estado com `GET /v1/charges/{id}` antes de registrar a perda.

O desenho abaixo resume os eventos que podem chegar depois que a cobrança foi paga.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart LR
    PAID(["Cobrança paid"]):::ok
    EST["Estorno concluído<br/>refunded"]:::neutro
    BLQ["Bloqueio: MED ou<br/>chargeback em análise<br/>status continua paid"]:::alerta
    PRE["Alerta de pré-chargeback<br/>pre_chargeback"]:::alerta
    CB["Adquirente informa<br/>a disputa<br/>chargeback"]:::erro
    E1[["charge.refunded"]]:::evento
    E2[["charge.blocked<br/>+ charge.updated"]]:::evento
    LIB["Liberação do bloqueio<br/>nenhum evento: consulte<br/>isBlocked na API"]:::neutro
    E3[["charge.pre_chargeback<br/>+ charge.updated"]]:::evento
    Q1{"Valor estornado<br/>no alerta?"}:::decisao
    E4[["charge.refunded<br/>chargeback_alert_<br/>refunded: true"]]:::evento
    E5[["charge.updated<br/>status chargeback<br/>só na postbackUrl"]]:::evento
    Q2{"Já estornado no<br/>pré-chargeback?"}:::decisao
    E6[["charge.refunded<br/>quando o valor é<br/>revertido do saldo"]]:::evento
    FIM["Endpoints não<br/>recebem nada"]:::neutro
    PAID --> EST --> E1
    PAID --> BLQ --> E2
    BLQ -.-> LIB
    PAID --> PRE --> E3
    PRE --> Q1
    Q1 -->|"sim"| E4
    PAID --> CB --> E5
    CB --> Q2
    Q2 -->|"não"| E6
    Q2 -->|"sim"| FIM
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Onde aparece `+ charge.updated`, esse evento chega só à `postbackUrl`.

## Postback legado

O `charge.updated` é entregue **exclusivamente** ao `postbackUrl` informado na criação da cobrança, nunca aos endpoints, e tem envelope e convenção de nomes próprios. Ele é enviado quando:

* o adquirente informa uma mudança de status pelo webhook dele: pagamento, recusa ou falha assíncrona, estorno, chargeback;
* o 3DS gerenciado termina em recusa ou falha;
* a cobrança é bloqueada;
* a cobrança recebe um alerta de pré-chargeback.

Por isso, um Pix pago gera `charge.paid` e também `charge.updated` no `postbackUrl`.

### Envelope do charge.updated (camelCase)

O envelope **não** tem `id` nem `livemode`. O objeto `data` é a cobrança convertida para **camelCase** em todos os níveis, inclusive as chaves de `metadata`:

```json theme={null}
{
  "event": "charge.updated",
  "data": {
    "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
    "status": "failed",
    "reason": "card_declined",
    "pspRefId": "card_ref_def456",
    "amount": 100,
    "currency": "BRL",
    "spread": 0,
    "net": 0,
    "isBlocked": false,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": { "id": "52998224725", "type": "cpf" },
      "phone": null
    },
    "paymentMethod": {
      "type": "credit_card",
      "installments": 1,
      "holderName": "JOAO SILVA",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "firstSix": "411111",
      "lastFour": "1111"
    },
    "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "paymentDetails": null,
    "shippingAddress": null,
    "trackingInfo": null,
    "metadata": { "orderId": "ORD-123" },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia",
    "paidAt": null,
    "isTest": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:31:00.000Z",
    "deletedAt": null
  }
}
```

| Envelope padrão (snake\_case) | `charge.updated` (camelCase) |
| - | - |
| `psp_ref_id` | `pspRefId` |
| `payment_method` | `paymentMethod` (chaves internas iguais: `firstSix`, `lastFour`, `holderName`) |
| `merchant_id` | `merchantId` |
| `payment_details` | `paymentDetails` |
| `shipping_address` | `shippingAddress` |
| `tracking_info` | `trackingInfo` |
| `postback_url` | `postbackUrl` |
| `paid_at` | `paidAt` |
| `is_test` | `isTest` |
| `is_blocked`, `blocked_at`, `blocked_reason` | `isBlocked`, `blockedAt`, `blockedReason` |
| `metadata` com as chaves como foram enviadas | `metadata` com as chaves convertidas para camelCase (veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata)) |
| `created_at`, `updated_at`, `deleted_at` | `createdAt`, `updatedAt`, `deletedAt` |
| (não vem) | `reason`, o motivo do status |

O `charge.updated` traz mais campos que o envelope padrão. Use só os documentados nesta página. Em cobranças Pix, `paymentDetails` traz os mesmos campos descritos em [Objeto payment\_details (Pix)](#objeto-payment_details-pix).

> [!TIP]
>
> **Para o desenvolvedor:** o `charge.updated` não tem `id` de evento. Use a chave definida na [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos).

## Passo a passo

O exemplo trata os dois formatos (envelope padrão e `charge.updated`) na mesma rota. Ele responde primeiro e processa depois. Para descartar eventos repetidos, aplique antes do `switch` a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos), como no exemplo completo da visão geral.

```javascript Node.js theme={null}
// webhook-cobranca.mjs (Node.js 18+, ESM)
import express from 'express';

const API_URL = 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

async function getCharge(id) {
  const res = await fetch(`${API_URL}/v1/charges/${id}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  return res.json();
}

// Troque estas funções pelas regras do seu sistema
async function releaseOrder(chargeId, info) { console.log('liberar', chargeId, info); }
async function markNotPaid(chargeId, status) { console.log('não pago', chargeId, status); }
async function markRefunded(chargeId, reason) { console.log('estornado', chargeId, reason); }
async function markDisputed(chargeId, reason) { console.log('em disputa', chargeId, reason); }
async function markChargeback(chargeId) { console.log('chargeback', chargeId); }

const app = express();
app.use(express.json());

app.post('/webhooks/finvia', async (req, res) => {
  const { event, data, livemode } = req.body;
  res.status(200).send('OK');

  // Eventos de teste chegam nos mesmos endpoints: em produção, descarte-os
  const isTestEvent = livemode === false || data?.isTest === true;
  if (process.env.NODE_ENV === 'production' && isTestEvent) return;

  switch (event) {
    case 'charge.created':
    case 'charge.pending':
      // Pedido aguardando pagamento
      break;

    case 'charge.paid': {
      // Confirmar na API antes de liberar
      const charge = await getCharge(data.id); // GET /v1/charges/{id}
      if (charge.status === 'paid') {
        await releaseOrder(data.id, { paidAt: data.paid_at, net: data.net });
      }
      break;
    }

    case 'charge.refused':
    case 'charge.failed':
      await markNotPaid(data.id, data.status);
      break;

    case 'charge.refunded':
      await markRefunded(data.id);
      break;

    case 'charge.pre_chargeback':
      // Se houver estorno no alerta, chega também um charge.refunded
      await markDisputed(data.id);
      break;

    case 'charge.blocked':
      await markDisputed(data.id, data.blocked_reason);
      break;

    case 'charge.updated':
      // Canal legado, entregue só ao postbackUrl, campos em camelCase
      if (data.status === 'chargeback') {
        await markChargeback(data.id);
      } else if (data.status === 'failed' || data.status === 'refused') {
        await markNotPaid(data.id, data.status); // recusa assíncrona
      } else if (data.status === 'pre_chargeback' && data.chargebackAlertRefunded) {
        await markRefunded(data.id, data.chargebackAlertReason);
      }
      break;

    default:
      console.log(`Evento não tratado: ${event}`);
  }
});

app.listen(3000);
```

> [!TIP]
>
> **Para o desenvolvedor:** cobranças de assinatura pagas também disparam `charge.created` e `charge.paid`. O `metadata` dessas cobranças traz `subscription_id` e `billing_cycle`, o que permite saber que o pagamento é de uma assinatura. Veja [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md).

### Fluxo típico de um Pix

O desenho abaixo mostra o fluxo típico de um Pix, com os webhooks de cada etapa.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant C as Comprador
    end
    box rgb(243,245,248) Sua aplicação
        participant L as Seu servidor
        participant W as Seu receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant B as Banco do comprador
    end
    L->>F: POST /v1/charges (type pix)
    F-->>L: id · status pending · QR Code
    L-->>C: Mostra o QR Code
    F-)W: charge.created e charge.pending
    C->>B: Paga o Pix no app do banco
    B->>F: Confirma o pagamento
    F-)W: charge.paid
    opt Cobrança com postbackUrl
        F-)W: charge.updated na postbackUrl
    end
    W->>F: GET /v1/charges/{id}
    F-->>W: status paid
    W-->>C: Libera o acesso ou o pedido
```

**1. Sua aplicação cria a cobrança**

`POST /v1/charges` com `paymentMethod.type` `pix`.

**2. A resposta traz o QR Code**

A resposta síncrona traz o `id`, `status` `pending` e o QR Code. Mostre-o ao cliente.

**3. Webhooks de criação e espera**

Chegam `charge.created` e `charge.pending`.

**4. O cliente paga**

O cliente paga o Pix no aplicativo do banco.

**5. Webhook de pagamento**

Chega `charge.paid` e, se a cobrança tem `postbackUrl`, também o `charge.updated`. Sua aplicação confirma em `GET /v1/charges/{id}` e libera o acesso.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `charge.updated` nunca chega | Cobrança criada sem `postbackUrl`, ou esperado nos endpoints | Informe `postbackUrl` na criação da cobrança |
| Campos `undefined` no `charge.updated` | Parser lendo snake\_case (`paid_at`) em um payload camelCase (`paidAt`) | Trate o `charge.updated` com o mapeamento de camelCase |
| `metadata.order_id` vazio no postback | No `charge.updated`, chaves enviadas em snake\_case chegam em camelCase | Leia `metadata.orderId` nesse evento ou envie as chaves em camelCase. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |
| Cobrança em análise negada sem aviso nos endpoints | Recusas assíncronas só geram `charge.updated` | Use `postbackUrl` ou consulte `GET /v1/charges/{id}` |
| Pedido continua "em disputa" depois da liberação do bloqueio | A liberação não gera evento | Consulte `isBlocked` em `GET /v1/charges/{id}` |
| QR Code em branco | `qrCodeBase64` veio `null` | Gere a imagem a partir de `copyPaste` |
| Pedido de pré-chargeback marcado errado | Status lido sem olhar se houve estorno | Use `charge.refunded` ou `chargebackAlertRefunded` para decidir entre estornado e em disputa |

## Perguntas frequentes

> [accordion] Qual evento devo usar para liberar o pedido?
>
> `charge.paid`, sempre confirmado por `GET /v1/charges/{id}`. Os webhooks não têm assinatura HMAC, por isso a confirmação na API é necessária antes de liberar.

> [accordion] Por que existem dois formatos de payload?
>
> O envelope padrão atende os eventos entregues aos endpoints e ao `postbackUrl`. O `charge.updated` é um canal legado, entregue só ao `postbackUrl`, com a cobrança em camelCase. Os dois formatos são mantidos por compatibilidade com integrações em produção.

> [accordion] Recebo webhook de recusa de cartão?
>
> Sim, quando a recusa acontece na criação ou ao final do 3DS gerenciado: chega `charge.refused` ou `charge.failed`. A resposta de `POST /v1/charges` continua sendo a fonte principal, com o motivo em `reason`. Recusas informadas depois pelo adquirente chegam só pelo `charge.updated`.

> [accordion] Como recebo aviso de chargeback e MED?
>
> O bloqueio chega como `charge.blocked`, nos endpoints e no `postbackUrl`. O chargeback formalizado chega como `charge.updated` com `status: "chargeback"` no `postbackUrl` e, quando o valor sai do saldo, também como `charge.refunded`. A liberação do bloqueio não gera aviso. O fluxo completo está em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

> [accordion] Sou conta master. Recebo os eventos das cobranças das subcontas?
>
> Sim, se o seu endpoint tiver a opção de incluir subcontas (`include_submerchants: true`). O `merchant_id` do payload indica a subconta. Veja [Quem recebe cada evento](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#quem-recebe-cada-evento).

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| CHG-01 | Cartão aprovado à vista | Webhook `charge.paid` recebido |
| CHG-03 | Cartão recusado | Recusa na resposta síncrona e webhook `charge.refused` (ou `charge.failed`) |
| CHG-04 | Pix gerado | Webhook `charge.pending` |
| CHG-05 | Pix pago no sandbox | Webhook `charge.paid` para o mesmo `id` |
| CHG-07 | Estorno total | Webhook `charge.refunded` |
| CHG-08 | Recebimento de webhook | Seu endpoint responde `2xx` em poucos segundos |
| CHG-09 | Simulação de evento no sandbox | Evento simulado recebido nos endpoints e no `postbackUrl` |

Para testar o tratamento de outros status, use [`POST /v1/charges/{id}/resend-webhook`](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste) com uma cobrança de teste. A rota aceita `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` e `authentication_required`, gera um evento novo e não muda a cobrança. Bloqueio, pré-chargeback e chargeback não podem ser simulados por ela.

## Veja também

> [card] [Webhooks: visão geral](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Destinos, formatos, entrega e deduplicação.

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> O fluxo de disputa e o campo isBlocked.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> Todos os status e o que fazer em cada um.

> [card] [Reenviar webhook de teste](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste.md)
>
> Simule eventos no sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.