> ## 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.

# Bloqueio, chargeback e MED

> O que acontece quando um pagamento é contestado no cartão ou no Pix, como a Finvia avisa você, como enviar a defesa e como tratar cada desfecho.

Depois de paga, uma cobrança ainda pode ser contestada. No cartão, o titular pede ao banco emissor que desfaça a compra (chargeback). No Pix, a instituição do pagador pode pedir a devolução pelo MED (Mecanismo Especial de Devolução). Enquanto o caso é analisado, a equipe Finvia pode **bloquear** a cobrança e reter o valor. Esta página explica cada etapa, os avisos que você recebe, como enviar a defesa e como tratar cada desfecho.

> [!NOTE]
>
> **Para o negócio:** o aviso de chargeback ou MED chega **por e-mail**, com os detalhes do caso. A defesa é enviada **respondendo a esse e-mail**, dentro do prazo indicado nele. Pela API, o seu sistema acompanha o bloqueio e o desfecho, mas não envia defesa. Se a disputa for ganha, o bloqueio é retirado e o valor fica com você. Se for perdida, o valor volta ao comprador.

## Conceitos

| Termo | O que é |
| - | - |
| Chargeback | Contestação de uma compra com cartão, aberta pelo banco emissor do cartão a pedido do titular, por meio da bandeira. Chega à Finvia pela adquirente. Existe só no cartão |
| Pré-chargeback | Alerta recebido quando o titular contestou a compra **antes** de o chargeback ser formalizado (programas Ethoca e Verifi). A cobrança vai para `pre_chargeback` |
| MED | MED (Mecanismo Especial de Devolução) é o mecanismo do Pix, definido pelo Banco Central, que permite à instituição do pagador pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. Durante a análise, o valor fica bloqueado. Se a contestação for aceita, ele é devolvido ao pagador. Existe só no Pix |
| Bloqueio cautelar | Outra ferramenta do Pix, diferente do MED: uma retenção preventiva e curta, feita pela instituição do recebedor quando suspeita de fraude. Na API, usa o mesmo bloqueio da cobrança |
| Bloqueio da cobrança | Retenção aplicada pela equipe Finvia a uma cobrança `paid` durante uma disputa. Aparece como `isBlocked: true`, e o `status` continua `paid` |
| Defesa | Evidências da venda que você envia para contestar a disputa (comprovante de entrega, nota fiscal, conversa com o cliente) |

**Em validação (V-32 e V-53):** compliance revisa a definição do MED, a citação normativa e o texto do fluxo de defesa (MED e chargeback), inclusive o prazo para envio de evidências.

## Quando usar este guia

| Situação | O que fazer |
| - | - |
| Recebeu e-mail de alerta de chargeback ou MED | Reúna as evidências e responda ao e-mail dentro do prazo indicado |
| Recebeu `charge.blocked` | Marque o pedido como "em disputa" e segure envios ainda não feitos |
| Recebeu `charge.pre_chargeback` | Leia `chargebackAlertRefunded` para saber se o valor já foi devolvido |
| O pedido está "em disputa" há dias | Consulte a cobrança: a liberação do bloqueio não gera webhook |
| A cobrança foi para `chargeback` ou `refunded` | Registre a perda e siga o seu fluxo de cancelamento |
| Você quer devolver o valor por iniciativa própria | Use o [estorno](https://docs.fastpaybrasil.com/guias/estorno.md) |

## Como você fica sabendo

O aviso operacional e o aviso técnico chegam por canais diferentes.

| Canal | O que chega | Para quem |
| - | - | - |
| E-mail | Alerta de chargeback ou de MED, com os detalhes do caso e o prazo para a defesa | O e-mail da conta. No Connect, o e-mail da conta master |
| `charge.blocked` (envelope padrão) | Bloqueio da cobrança, com `is_blocked`, `blocked_at` e `blocked_reason` | Endpoints de webhook e `postbackUrl` |
| `charge.pre_chargeback` (envelope padrão) | Alerta de pré-chargeback | Endpoints de webhook e `postbackUrl` |
| `charge.refunded` (envelope padrão) | Valor devolvido ao comprador (estorno no pré-chargeback, MED aceito ou chargeback revertido do saldo) | Endpoints de webhook e `postbackUrl` |
| `charge.updated` (legado, camelCase) | Bloqueio, pré-chargeback e chargeback formalizado (`status: "chargeback"`) | Só a `postbackUrl` |
| Nenhum | Liberação do bloqueio | Acompanhe pela consulta da cobrança |

Na API não existe status nem evento chamado MED. O MED aparece como bloqueio da cobrança.

> [!WARNING]
>
> O status `chargeback` só é avisado pelo `charge.updated`, que vai **somente à `postbackUrl`**. Os endpoints recebem apenas o `charge.refunded`, e só quando o valor é revertido do saldo. Informe a `postbackUrl` em todas as cobranças de cartão e confirme sempre com `GET /v1/charges/{id}`.

## Como funciona o bloqueio

O desenho abaixo mostra como uma contestação chega ao bloqueio da cobrança e quais avisos saem em cada canal.

```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 TB
    PAID(["Cobrança paid"]):::ok
    MED["Pix: a instituição do<br/>pagador abre o MED"]:::externo
    CBK["Cartão: o emissor abre<br/>a disputa, que chega<br/>pela adquirente"]:::externo
    CAU["Pix: bloqueio cautelar<br/>da instituição<br/>do recebedor"]:::externo
    NOT["A Finvia é notificada"]:::neutro
    MAIL[["E-mail de alerta<br/>para a conta, com os<br/>detalhes e o prazo"]]:::evento
    EQ["Equipe Finvia<br/>bloqueia a cobrança"]:::finvia
    DEF["Você responde ao<br/>e-mail com as evidências,<br/>dentro do prazo"]:::lojista
    EST["status continua paid<br/>isBlocked: true<br/>blockedAt, blockedReason"]:::alerta
    SAL["Valor já liquidado vai<br/>do saldo disponível<br/>para o bloqueado"]:::alerta
    EV[["charge.blocked<br/>endpoints e postbackUrl"]]:::evento
    UPD[["charge.updated<br/>só na postbackUrl"]]:::evento
    PAID --> MED
    PAID --> CBK
    PAID --> CAU
    MED --> NOT
    CBK --> NOT
    NOT --> MAIL
    NOT --> EQ
    CAU -->|"mesmo bloqueio<br/>na API"| EQ
    MAIL --> DEF
    EQ --> EST
    EST --> SAL
    EST --> EV
    EST --> UPD
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    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 alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

A liberação do bloqueio não gera webhook. Veja [Desfechos](#desfechos).

**1. Cobrança paga**

A cobrança está `paid`. Só cobranças `paid` podem ser bloqueadas.

**2. A Finvia é notificada**

No Pix, a instituição do pagador abre o MED. No cartão, o emissor abre a disputa e ela chega pela adquirente. Você recebe o alerta por e-mail.

**3. A equipe Finvia bloqueia a cobrança**

O bloqueio é aplicado pela equipe Finvia (ele não chega automaticamente do banco). A cobrança continua `paid` e passa a ter `isBlocked: true`, `blockedAt` e `blockedReason`. Os endpoints e a `postbackUrl` recebem `charge.blocked`.

**4. O valor fica retido**

O que a venda já liquidou (o líquido mais as taxas da venda) sai do saldo disponível e vai para o saldo bloqueado. Parcelas que liquidarem enquanto o bloqueio durar também caem no saldo bloqueado.

**5. Você envia a defesa**

Responda ao e-mail do alerta com as evidências, dentro do prazo indicado.

**6. Desfecho**

Se a disputa for ganha, o bloqueio é retirado. Se for perdida, o valor volta ao comprador. Veja [Desfechos](#desfechos).

### O que a API mostra durante o bloqueio

| Campo na consulta | No envelope padrão | Significado |
| - | - | - |
| `status` | `status` | Continua `paid` |
| `isBlocked` | `is_blocked` | `true` enquanto a cobrança está bloqueada. É o campo que diz se ela está bloqueada |
| `blockedAt` | `blocked_at` | Data e hora do bloqueio. Continua preenchido depois da liberação |
| `blockedReason` | `blocked_reason` | Texto livre preenchido pela equipe Finvia (pode indicar MED ou chargeback). Pode vir vazio e é apagado na liberação |

Para listar as cobranças bloqueadas, use `GET /v1/charges?status=blocked`.

## Defesa

Não existe rota de API para enviar defesa de MED ou de chargeback. A defesa é tratada com a equipe Finvia, pelo e-mail do alerta.

**1. Leia o e-mail do alerta**

Ele traz os detalhes do caso e o prazo para a defesa. No Connect, o e-mail vai para a conta master.

**2. Reúna as evidências**

Comprovante de entrega, nota fiscal, registro de acesso ao produto digital, conversa com o cliente e qualquer outro documento que mostre que a venda foi legítima e entregue.

**3. Responda ao e-mail dentro do prazo**

Envie as evidências em resposta ao e-mail do alerta. Uma contestação respondida fora do prazo pode ser perdida mesmo com todas as evidências.

Como cada caso é analisado:

* **Pix (MED):** a contestação é aberta pela instituição financeira do pagador e analisada pela instituição do recebedor, seguindo as regras do Pix definidas pelo Banco Central. A Finvia encaminha as suas evidências à instituição responsável pela análise. Se a devolução for aceita, o valor volta ao pagador e a cobrança fica `refunded`. Se for recusada, o bloqueio é retirado.
* **Cartão (chargeback):** a disputa é aberta pelo banco emissor do cartão, por meio da bandeira, e chega à Finvia pela adquirente. A Finvia reúne as suas evidências e as apresenta à adquirente, que as leva ao emissor. O resultado depende do emissor e segue o fluxo das bandeiras.

O desenho abaixo junta a defesa por e-mail e os desfechos possíveis no Pix e no cartão.

```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
    MAIL[["E-mail de alerta<br/>com o prazo da defesa"]]:::evento
    EVI["Reúna as evidências<br/>entrega, nota fiscal,<br/>conversa com o cliente"]:::lojista
    PRZ{"Respondeu<br/>no prazo?"}:::decisao
    TARDE["Pode ser perdida<br/>mesmo com todas<br/>as evidências"]:::erro
    MEIO{"Pix ou<br/>cartão?"}:::decisao
    PIX["Finvia encaminha<br/>as evidências a quem<br/>analisa o MED"]:::finvia
    CART["Finvia apresenta<br/>à adquirente, que<br/>leva ao emissor"]:::finvia
    R1{"Devolução<br/>aceita?"}:::decisao
    R2{"Disputa<br/>ganha?"}:::decisao
    RFD["refunded<br/>valor volta<br/>ao pagador"]:::erro
    LIB["Bloqueio liberado<br/>isBlocked: false, valor<br/>volta ao disponível"]:::ok
    CB["chargeback<br/>informado pela<br/>adquirente"]:::erro
    E1[["charge.refunded"]]:::evento
    SEM["Nenhum webhook:<br/>confirme com<br/>GET /v1/charges/{id}"]:::neutro
    E2[["charge.updated<br/>status chargeback<br/>só na postbackUrl"]]:::evento
    E3[["charge.refunded<br/>quando o valor é<br/>revertido do saldo"]]:::evento
    MAIL --> EVI --> PRZ
    PRZ -->|"sim"| MEIO
    PRZ -->|"não"| TARDE
    MEIO -->|"Pix, MED"| PIX --> R1
    MEIO -->|"cartão, chargeback"| CART --> R2
    R1 -->|"sim"| RFD
    R1 -->|"não"| LIB
    R2 -->|"sim"| LIB
    R2 -->|"não"| CB
    RFD --> E1
    LIB -.-> SEM
    CB --> E2
    CB --> E3
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    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 decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

O fluxo da defesa e o prazo para envio das evidências estão em validação (V-32 e V-53), como indicado no início da página.

## Desfechos

| Desfecho | O que muda na cobrança | Aviso |
| - | - | - |
| Bloqueio liberado (disputa ganha ou MED recusado) | `isBlocked: false`, `blockedReason` apagado, `blockedAt` mantido. O valor volta ao saldo disponível | **Nenhum webhook**. Consulte a cobrança |
| MED aceito (Pix) | Estorno: `status` `refunded` | `charge.refunded` |
| Chargeback perdido (cartão) | `status` `chargeback`, informado pela adquirente | `charge.updated` com `status: "chargeback"` na `postbackUrl` e, quando o valor é revertido do saldo, `charge.refunded` (o `status` dentro desse payload pode vir `refunded` ou `chargeback`) |

A passagem para `chargeback` acontece quando a adquirente informa a disputa à Finvia. Nem todas as adquirentes enviam esse aviso: confirme sempre o estado com `GET /v1/charges/{id}`.

> [!TIP]
>
> **Para o desenvolvedor:** como a liberação não gera webhook, guarde as cobranças que você marcou como "em disputa" e consulte cada uma periodicamente com `GET /v1/charges/{id}`, ou compare com a lista de `GET /v1/charges?status=blocked`. Quando `isBlocked` voltar a `false` com `status` `paid`, restaure o pedido.

## Pré-chargeback

O pré-chargeback é um alerta recebido pelos programas Ethoca e Verifi quando o titular contestou a compra no emissor, antes de o chargeback ser formalizado. O serviço é ativado conforme o seu contrato:

* **Alerta com reembolso automático**, quando previsto em contrato: o valor é devolvido ao titular para que o alerta não evolua para chargeback formal.
* O **custo do serviço de pré-alerta** (Ethoca/Verifi) é debitado da sua conta.

Na API, a cobrança passa para `pre_chargeback` e os endpoints e a `postbackUrl` recebem `charge.pre_chargeback`. A `postbackUrl` recebe também o `charge.updated`. Se houve reembolso, sai ainda `charge.refunded`, com `chargeback_alert_refunded: true` no payload.

| Campo (consulta e listagem) | Tipo | Significado |
| - | - | - |
| `chargebackAlertRefunded` | boolean ou `null` | `true`: o valor **já foi estornado** ao titular. `false`: alerta registrado **sem** estorno. `null` quando não há alerta |
| `chargebackAlertReason` | string ou `null` | Motivo ou referência informado no alerta (ex.: `"Chargeback - NSU 123456789"`) |

| `chargebackAlertRefunded` | Como marcar o pedido |
| - | - |
| `true` | Estornado (o valor já voltou ao titular) |
| `false` | Em disputa, sem estorno |

Uma cobrança já estornada no pré-chargeback não pode receber outro estorno. Se depois o chargeback for formalizado, só a `postbackUrl` recebe o `charge.updated` com `status: "chargeback"`.

O desenho abaixo mostra o caminho de um alerta de pré-chargeback e como marcar o pedido em cada caso.

```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 TB
    TIT(["Titular contesta a compra<br/>no banco emissor"]):::comprador
    ALR["Alerta Ethoca ou Verifi<br/>antes do chargeback formal"]:::externo
    PRE["pre_chargeback<br/>alerta de pré-chargeback"]:::alerta
    CUS["Custo do serviço<br/>Ethoca/Verifi debitado<br/>da sua conta"]:::alerta
    EV[["charge.pre_chargeback<br/>endpoints e postbackUrl<br/>+ charge.updated na postbackUrl"]]:::evento
    Q{"chargebackAlert<br/>Refunded?"}:::decisao
    DEV["Valor devolvido ao titular<br/>reembolso automático<br/>previsto em contrato"]:::neutro
    RF[["charge.refunded com<br/>chargeback_alert_<br/>refunded: true"]]:::evento
    PED1(["Marque o pedido<br/>como estornado"]):::lojista
    PED2(["Marque o pedido como<br/>em disputa, sem estorno"]):::lojista
    FORM["Se o chargeback for<br/>formalizado: charge.updated<br/>status chargeback na postbackUrl"]:::erro
    TIT --> ALR --> PRE
    PRE --> EV
    PRE --> CUS
    PRE --> Q
    Q -->|"true"| DEV --> RF --> PED1
    Q -->|"false"| PED2
    PED1 -.-> FORM
    PED2 -.-> FORM
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    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
```

## Exemplos de payload

> [tab] charge.blocked
>
> Envelope padrão, com as chaves de `data` em snake\_case. O exemplo mostra parte do objeto `data`.
>
> ```json theme={null}
> {
>   "id": "2xKs9To6VbY1dP5rN0eX3fA8jLg",
>   "event": "charge.blocked",
>   "livemode": true,
>   "data": {
>     "id": "2vorkPx3Bl4Oc5Ke6Dd7Ab8CdEf",
>     "status": "paid",
>     "amount": 100,
>     "currency": "BRL",
>     "net": 99,
>     "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
>     "payment_method": { "type": "pix" },
>     "is_blocked": true,
>     "blocked_at": "2026-10-20T09:00:00.000Z",
>     "blocked_reason": "MED em análise",
>     "metadata": { "orderId": "ORD-456" },
>     "paid_at": "2026-10-15T14:31:00.000Z",
>     "is_test": false
>   }
> }
> ```

> [tab] charge.updated (bloqueio)
>
> Postback legado, só na `postbackUrl`: camelCase em todos os níveis, inclusive em `metadata`, sem `id` e sem `livemode`. O exemplo mostra parte do objeto `data`.
>
> ```json theme={null}
> {
>   "event": "charge.updated",
>   "data": {
>     "id": "2vorkDcXyvzifL63YX09S9VqcnI",
>     "status": "paid",
>     "pspRefId": "card_ref_abc123",
>     "amount": 100,
>     "currency": "BRL",
>     "isBlocked": true,
>     "blockedAt": "2026-10-20T09:00:00.000Z",
>     "blockedReason": "Chargeback em análise",
>     "paymentMethod": {
>       "type": "credit_card",
>       "installments": 1,
>       "firstSix": "411111",
>       "lastFour": "1111",
>       "holderName": "JOAO DA SILVA"
>     },
>     "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
>     "metadata": { "orderId": "ORD-123" },
>     "postbackUrl": "https://meusite.com.br/webhooks/finvia",
>     "isTest": false,
>     "updatedAt": "2026-10-20T09:00:00.000Z"
>   }
> }
> ```

> [tab] charge.pre\_chargeback
>
> Envelope padrão. O exemplo mostra parte do objeto `data`.
>
> ```json theme={null}
> {
>   "id": "2xKt0Up7WcZ2eQ6sO1fY4gB9kMh",
>   "event": "charge.pre_chargeback",
>   "livemode": true,
>   "data": {
>     "id": "2vorkDcXyvzifL63YX09S9VqcnI",
>     "status": "pre_chargeback",
>     "amount": 100,
>     "currency": "BRL",
>     "chargeback_alert_refunded": true,
>     "chargeback_alert_reason": "Chargeback - NSU 123456789",
>     "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
>     "is_test": false
>   }
> }
> ```

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Quem bloqueia | A equipe Finvia, só em cobrança `paid` |
| Status durante o bloqueio | Continua `paid`. Use `isBlocked` |
| Saldo | O valor já liquidado da venda vai para o saldo bloqueado; parcelas que liquidarem durante o bloqueio também |
| Alerta | Por e-mail à conta (no Connect, à conta master), com os detalhes e o prazo |
| Defesa | Em resposta ao e-mail do alerta, dentro do prazo. Não existe envio de defesa pela API |
| Defesa fora do prazo | Pode ser perdida mesmo com todas as evidências |
| Resultado | No cartão, depende do emissor e segue o fluxo das bandeiras. No Pix, segue as regras do MED |
| Liberação | Sem webhook. Acompanhe pela consulta |
| Pré-chargeback | Alerta mais reembolso automático quando previsto em contrato. O custo do serviço (Ethoca/Verifi) é debitado da conta |
| Estorno | O lojista pede estorno só pela API (`POST /v1/refunds`). A Finvia não faz estorno por chamado, exceto em erro sistêmico. A devolução de um MED aceito e os débitos de chargeback são feitos pela Finvia |

> [!WARNING]
>
> Uma cobrança em disputa ainda pode terminar com o valor devolvido ao cliente. Se o pedido é de produto físico ainda não enviado, avalie com a sua operação se o envio deve esperar o resultado.

## Implementação recomendada

O desenho abaixo resume a lógica do código: o que fazer com cada aviso e a rotina que detecta a liberação do bloqueio.

```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 TB
    REQ(["POST no seu endpoint"]):::neutro
    R200["Responda 200 primeiro"]:::lojista
    ID{"O corpo tem id<br/>de evento?"}:::decisao
    EVT{"Qual evento?"}:::decisao
    BLK["Pedido em disputa"]:::alerta
    AR{"chargeback_alert_<br/>refunded?"}:::decisao
    EST["Pedido estornado"]:::neutro
    DIS["Pedido em disputa"]:::alerta
    REG["Registre o estorno<br/>MED aceito ou chargeback<br/>revertido do saldo"]:::neutro
    GET1["Legado charge.updated:<br/>GET /v1/charges/{id}"]:::lojista
    CBQ{"status<br/>chargeback?"}:::decisao
    PERDA["Registre a perda"]:::erro
    ROT(["Rotina periódica"]):::neutro
    GET2["GET /v1/charges/{id}<br/>de cada pedido em disputa"]:::lojista
    LIBQ{"paid e<br/>isBlocked false?"}:::decisao
    REST(["Restaure o pedido"]):::ok
    REQ --> R200 --> ID
    ID -->|"sim"| EVT
    ID -->|"não"| GET1
    EVT -->|"charge.blocked"| BLK
    EVT -->|"charge.pre_chargeback"| AR
    EVT -->|"charge.refunded"| REG
    AR -->|"true"| EST
    AR -->|"false"| DIS
    GET1 --> CBQ
    CBQ -->|"sim"| PERDA
    ROT --> GET2 --> LIBQ
    LIBQ -->|"sim"| REST
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    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
```

```javascript Node.js theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  res.status(200).send('OK');

  // Envelope padrão (endpoints e postbackUrl): snake_case, com id de evento
  if (id) {
    if (event === 'charge.blocked') {
      await marcarPedido(data.id, 'em_disputa', data.blocked_reason);
    }
    if (event === 'charge.pre_chargeback') {
      const estado = data.chargeback_alert_refunded ? 'estornado' : 'em_disputa';
      await marcarPedido(data.id, estado, data.chargeback_alert_reason);
    }
    if (event === 'charge.refunded') {
      await registrarEstorno(data.id); // inclui MED aceito e chargeback revertido do saldo
    }
    return;
  }

  // Postback legado (só postbackUrl): camelCase, sem id. Confirme na API antes de agir.
  if (event === 'charge.updated') {
    const charge = await consultarCobranca(data.id); // GET /v1/charges/{id}
    if (charge?.status === 'chargeback') {
      await registrarPerda(charge.id);
    }
  }
});

// Rotina periódica: a liberação do bloqueio não gera webhook
async function verificarDisputas() {
  for (const chargeId of await pedidosEmDisputa()) {
    const charge = await consultarCobranca(chargeId);
    if (charge?.status === 'paid' && charge.isBlocked === false) {
      await restaurarPedido(chargeId);
    }
  }
}
```

> [!NOTE]
>
> O `charge.updated` chega só à `postbackUrl`, em camelCase e sem `id`/`livemode`. Os demais eventos seguem o envelope padrão, em snake\_case, e chegam aos endpoints e à `postbackUrl`. Se a mesma URL está cadastrada nos dois canais, ela recebe cada evento duas vezes: deduplique pelo `id` do evento.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Disputa perdida por prazo | A defesa foi enviada depois do prazo indicado no e-mail | Monitore o e-mail da conta (no Connect, da master) e responda dentro do prazo |
| Ninguém viu o alerta | O e-mail da conta não é acompanhado pela equipe responsável | Garanta que o e-mail cadastrado chega a quem cuida das disputas |
| Pedido fica "em disputa" para sempre | A liberação do bloqueio não gera webhook | Consulte a cobrança periodicamente e leia `isBlocked` |
| Pedido tratado como liberado durante o bloqueio | O código olhou só `status` (`paid`) | Leia também `isBlocked` |
| Pedido tratado como bloqueado depois da liberação | O código usou `blockedAt` | Use `isBlocked`: `blockedAt` continua preenchido |
| Chargeback formalizado não chegou ao sistema | Cobrança criada sem `postbackUrl` | Informe `postbackUrl` em todas as cobranças de cartão |
| Pedido marcado como estornado sem devolução | Pré-chargeback tratado sem ler `chargebackAlertRefunded` | Só marque como estornado quando `chargebackAlertRefunded` for `true` |

## Perguntas frequentes

> [accordion] Como envio a defesa?
>
> Respondendo ao e-mail do alerta de chargeback ou MED, com as evidências, dentro do prazo indicado. Não existe envio de defesa pela API.

> [accordion] MED e bloqueio cautelar são a mesma coisa?
>
> Não. O MED é o pedido de devolução de um Pix feito pela instituição do pagador. O bloqueio cautelar é uma retenção preventiva e curta, feita pela instituição do recebedor quando suspeita de fraude. Na API, os dois aparecem como bloqueio da cobrança (`isBlocked`).

> [accordion] Existe MED no cartão?
>
> Não. O MED existe só no Pix. No cartão, o equivalente é o chargeback.

> [accordion] Por que o status continua paid durante o bloqueio?
>
> Porque o pagamento aconteceu. O bloqueio só retém o valor enquanto o caso é analisado. Para saber se a cobrança está bloqueada, leia `isBlocked`.

> [accordion] Qual a diferença entre pré-chargeback e chargeback?
>
> O pré-chargeback é um alerta recebido antes de o chargeback ser formalizado, e pode vir com o valor já devolvido ao titular. O chargeback é a disputa formal aberta pelo emissor.

> [accordion] Posso filtrar as cobranças em disputa?
>
> Sim. `GET /v1/charges` aceita `status=blocked`, `status=pre_chargeback` e `status=chargeback`.

## Como testar

O reenvio de webhook de teste ([`POST /v1/charges/{id}/resend-webhook`](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste)) não aceita `pre_chargeback` nem `chargeback` e não simula o bloqueio. Para testar o seu handler, envie ao seu próprio endpoint os payloads de exemplo desta página. Garanta também que o seu endpoint responde 2xx (cenários **CHG-08** e **CHG-09** do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)).

## Veja também

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Formato do `charge.updated` e dos demais eventos.

> [card] [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md)
>
> Devolução por iniciativa do merchant.

> [card] [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md)
>
> Campos `isBlocked`, `blockedAt` e `blockedReason`.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> Todos os status e transições.


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