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

# Catálogo de eventos

> Todos os eventos de webhook da Finvia nas quatro famílias (cobrança, assinatura, saque e conta), com destinos e formato de cada uma.

Esta página lista todas as notificações que a Finvia envia ao seu sistema. Use-a para saber quais eventos tratar, em que destino cada um chega e como reconhecer o formato do corpo. O detalhe de cada família, com payloads completos, está no guia correspondente.

> [!NOTE]
>
> **Para o negócio:** cada família tem destinos próprios. O `charge.updated` com o chargeback formalizado, por exemplo, chega só no `postbackUrl` da cobrança, e o aviso de aprovação de subconta chega só na URL de aviso de status da subconta. Defina com o time técnico quais destinos a operação precisa antes de ir para produção.

## Destinos de entrega

| Destino | Onde é configurado | O que recebe |
| - | - | - |
| **Endpoints de webhook** | Painel: **Configurações** > **Webhooks**, com a conta selecionada. API: [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint) | Eventos de cobrança, assinatura e saque da conta. Pela API, dá para filtrar com `enabled_events`; pelo painel, o endpoint recebe todos |
| **Endpoints da master com subcontas** | Os mesmos endpoints da conta master, com a opção de incluir subcontas (`include_submerchants: true`) | Também os eventos de cobrança, assinatura e saque das subcontas |
| **`postbackUrl` da cobrança** | Campo `postbackUrl` em `POST /v1/charges` | Os mesmos eventos de cobrança dos endpoints, mais o `charge.updated` legado. Não há filtro de eventos |
| **URL de aviso de status de conta** | Campo `postbackUrl` em `POST /v1/submerchants`, gravado como `merchant_status_postback_url` da subconta | Só o aviso de status da subconta |

Os eventos são roteados pela conta dona do recurso. A regra completa está em [Quem recebe cada evento](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#quem-recebe-cada-evento).

## Todos os eventos

| Evento | Família | Quando é enviado | Endpoints | `postbackUrl` |
| - | - | - | - | - |
| `charge.created` | Cobrança | A cobrança é criada | Sim | Sim |
| `charge.pending` | Cobrança | O processamento termina em `pending` (ex.: QR Code Pix gerado) | Sim | Sim |
| `charge.paid` | Cobrança | O pagamento é confirmado, na hora ou depois | Sim | Sim |
| `charge.refused` | Cobrança | A cobrança é recusada na criação ou ao final do 3DS gerenciado | Sim | Sim |
| `charge.failed` | Cobrança | A cobrança falha na criação ou ao final do 3DS gerenciado | Sim | Sim |
| `charge.refunded` | Cobrança | O estorno é concluído (inclusive no alerta de pré-chargeback com estorno e na reversão de saldo de um chargeback) | Sim | Sim |
| `charge.pre_chargeback` | Cobrança | Um alerta de pré-chargeback é registrado | Sim | Sim |
| `charge.blocked` | Cobrança | A cobrança é bloqueada (MED ou chargeback em análise) | Sim | Sim |
| `charge.updated` | Cobrança (legado) | O adquirente informa mudança de status (pagamento, recusa ou falha assíncrona, estorno, chargeback), o 3DS gerenciado termina em recusa ou falha, a cobrança é bloqueada ou recebe alerta de pré-chargeback | **Não** | Sim |
| `subscription.created` | Assinatura | Uma nova assinatura é criada | Sim | Não se aplica |
| `subscription.activated` | Assinatura | A assinatura é ativada (primeira cobrança aprovada, início do trial ou aprovação da primeira cobrança que estava em análise) | Sim | Não se aplica |
| `subscription.renewed` | Assinatura | Uma cobrança recorrente é aprovada (inclui a primeira cobrança cheia depois do trial) | Sim | Não se aplica |
| `subscription.payment_failed` | Assinatura | Cada tentativa de cobrança da assinatura que falha | Sim | Não se aplica |
| `subscription.cancelled` | Assinatura | A assinatura é cancelada | Sim | Não se aplica |
| `subscription.expired` | Assinatura | A assinatura é encerrada (retentativas esgotadas ou `endDate` do plano) | Sim | Não se aplica |
| `payout.approved` | Saque | O saque de uma subconta é aprovado e enviado para pagamento | Sim | Não se aplica |
| `payout.rejected` | Saque | O saque de uma subconta é rejeitado | Sim | Não se aplica |
| (sem nome de evento) | Conta | O status da subconta muda para `pre_approved`, `correcting`, `active` (aprovação ou desbloqueio), `rejected` ou `blocked` | Não | Não. Vai para a URL de aviso de status |

> [!NOTE]
>
> `subscription.trial_started` e `subscription.trial_ended` existem no contrato de tipos, mas **não são entregues** hoje. Para acompanhar o trial, use `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial`. Não há evento para a liberação de um bloqueio nem para a criação de um saque.

> [!WARNING]
>
> Recusas e falhas informadas **depois** pelo adquirente (cobrança em análise negada, Pix cancelado ou expirado) geram só o `charge.updated` no `postbackUrl`. A cobrança recorrente de assinatura recusada gera `subscription.payment_failed` e não gera `charge.refused`. O chargeback formalizado chega como `charge.updated` com `status: "chargeback"` e, quando o valor sai do saldo, também como `charge.refunded`.

O desenho abaixo mostra quais eventos saem da criação da cobrança até o primeiro resultado, e para qual destino vai cada um.

```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(234,243,255) Finvia
        participant F as Finvia
    end
    box rgb(243,245,248) Sua aplicação
        participant E as Endpoints de webhook
        participant P as postbackUrl da cobrança
    end
    box rgb(244,240,255) Fora da Finvia
        participant A as Adquirente ou Pix
    end
    Note over F,P: Cobrança gravada
    F-)E: charge.created
    F-)P: charge.created
    alt Termina em pending (Pix com QR Code)
        F-)E: charge.pending
        F-)P: charge.pending
    else Aprovada na hora
        F-)E: charge.paid
        F-)P: charge.paid
    else Recusada ou falhou (inclusive no fim do 3DS gerenciado)
        F-)E: charge.refused ou charge.failed
        F-)P: charge.refused ou charge.failed · no fim do 3DS gerenciado, também charge.updated
    else in_analysis ou authentication_required
        Note over F,P: Só o charge.created. O próximo evento depende do desfecho
    end
    opt Mudança informada depois pelo adquirente
        A->>F: pagamento, recusa, falha ou estorno
        F-)E: charge.paid ou charge.refunded, se for o caso
        F-)P: os mesmos eventos e também charge.updated
        Note over E,P: Recusa, falha, cancelamento ou expiração depois da criação: só charge.updated na postbackUrl
    end
```

O desenho abaixo mostra os eventos que podem chegar depois que a cobrança está 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<br/>paid"]):::ok
    M1["Estorno concluído"]:::neutro
    M2["Alerta de<br/>pré-chargeback"]:::alerta
    M3["Bloqueio<br/>MED ou disputa"]:::alerta
    M5["Chargeback<br/>formalizado"]:::erro
    E1[["charge.refunded<br/>endpoints e postbackUrl"]]:::evento
    E2[["charge.pre_chargeback<br/>endpoints e postbackUrl"]]:::evento
    R2[["charge.refunded<br/>se houve estorno"]]:::evento
    L2[["charge.updated<br/>só na postbackUrl"]]:::evento
    E3[["charge.blocked<br/>endpoints e postbackUrl"]]:::evento
    L3[["charge.updated<br/>só na postbackUrl"]]:::evento
    E4["Nenhum evento<br/>consulte a cobrança"]:::neutro
    E5[["charge.updated<br/>status chargeback<br/>só na postbackUrl"]]:::evento
    R5[["charge.refunded<br/>se o valor sai do saldo"]]:::evento
    PAID --> M1 --> E1
    PAID --> M2
    M2 --> E2
    M2 --> R2
    M2 --> L2
    PAID --> M3
    M3 --> E3
    M3 --> L3
    M3 -.->|"bloqueio retirado"| E4
    PAID --> M5
    M5 --> E5
    M5 --> R5
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

O desenho abaixo mostra a ordem dos eventos de assinatura, todos entregues aos endpoints de webhook.

```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
    C(["POST /v1/subscriptions"]):::neutro
    E0[["subscription.created"]]:::evento
    Q{"Primeira<br/>cobrança?"}:::decisao
    E1[["subscription.activated<br/>aprovada ou trial iniciado"]]:::evento
    E2[["subscription.payment_failed<br/>assinatura não ativa"]]:::evento
    E3[["subscription.renewed<br/>a cada ciclo aprovado"]]:::evento
    E4[["subscription.payment_failed<br/>a cada tentativa recusada"]]:::evento
    E5[["subscription.cancelled"]]:::evento
    E6[["subscription.expired<br/>encerrada"]]:::evento
    C --> E0 --> Q
    Q -->|"aprovada, trial ou<br/>análise aprova"| E1
    Q -->|"recusada ou<br/>análise nega"| E2
    E1 --> E3
    E1 --> E4
    E4 -->|"retentativas acabam"| E6
    E1 -->|"cancelamento"| E5
    E3 -->|"plano chega<br/>ao endDate"| E6
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

## Formato por família

| Família | Envelope | Chaves | Exceções |
| - | - | - | - |
| Cobrança (envelope padrão) | `{ id, event, livemode, data }` | snake\_case no primeiro nível de `data` | Objetos aninhados em camelCase (`payment_method`, `shipping_address`, `tracking_info`, `three_ds`, `freight_details`, `payment_details`). `metadata` como foi enviada |
| `charge.updated` | `{ event, data }`, sem `id` e sem `livemode` | camelCase em todos os níveis | `metadata` também em camelCase (veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata)) |
| Assinatura | `{ id, event, livemode, data }` | snake\_case | `trial` em camelCase. `metadata` como foi enviada |
| Saque | `{ id, event, data }`, sem `livemode` | camelCase | O `id` da raiz é o id do saque. Valores em texto decimal com 8 casas |
| Aviso de status de conta | Sem envelope | camelCase | Sem nome de evento e sem id |

A explicação completa, com exemplos, está em [Formato por família](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#formato-por-família).

### Envelope padrão (cobrança e assinatura)

```json theme={null}
{
  "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a",
  "event": "charge.paid",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid",
    "amount": 100,
    "currency": "BRL",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "paid_at": "2024-01-15T10:35:00.000Z",
    "is_test": false
  }
}
```

| Campo | Descrição |
| - | - |
| `id` | Identificador do evento |
| `event` | Nome do evento |
| `livemode` | Nos eventos de cobrança, `false` indica cobrança de teste (`data.is_test: true`). Nas assinaturas, não use para separar teste de produção |
| `data` | O objeto da cobrança ou da assinatura (o exemplo acima mostra só alguns campos) |

### Postback legado (`charge.updated`)

Sem `id` e sem `livemode`. O `data` é a cobrança em camelCase, com `isBlocked`, `blockedAt` e `blockedReason` no bloqueio e, no pré-chargeback, `chargebackAlertRefunded` e `chargebackAlertReason`.

```json theme={null}
{
  "event": "charge.updated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "chargeback",
    "amount": 100,
    "currency": "BRL",
    "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "metadata": { "orderId": "ORD-123" },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia",
    "isTest": false
  }
}
```

### Envelope de saque

Sem `livemode`. O `id` da raiz é o **id da solicitação de saque**. Campos em camelCase, valores em texto decimal.

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "event": "payout.rejected",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "amount": "100.00000000",
    "currency": "BRL",
    "status": "rejected",
    "payoutFee": "1.00000000",
    "netAmount": "99.00000000",
    "rejectionReason": "Documentação incompleta"
  }
}
```

### Aviso de status de conta

Sem envelope: o corpo é o próprio objeto da notificação, em camelCase. `rejectionReason` aparece só em `rejected` e `correcting`. `date` é a data de referência do status.

```json theme={null}
{
  "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "status": "correcting",
  "date": "2024-01-16T09:15:00.000Z",
  "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada."
}
```

## Confirmação, entrega e deduplicação

* **Confirmação de recebimento:** só uma resposta `2xx` em até 10 segundos conta como entregue. Redirecionamentos não são seguidos.
* **Entrega e novas tentativas:** veja [Entrega e retentativas](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#entrega-e-retentativas).
* **Deduplicação:** o mesmo evento pode chegar mais de uma vez. A chave de cada formato está na [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos).
* **Teste e produção:** a mesma lista de endpoints recebe os dois. Separe os eventos de cobrança por `livemode` e `is_test` (`isTest` no `charge.updated`). Saques e avisos de conta não têm marcação de teste.

## Segurança

* Os webhooks não trazem assinatura HMAC: confirme o estado na API antes de uma ação crítica (veja [Regras de negócio dos webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#regras-de-negócio)).
* Use sempre HTTPS no endpoint.
* Aplique limite de requisições no seu endpoint.
* Responda rápido e processe depois: devolva `2xx` antes de executar lógica pesada.

## Como simular eventos

No sandbox, [`POST /v1/charges/{id}/resend-webhook`](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste) gera um evento novo, com `id` novo, para uma cobrança de teste, com o status que você escolher (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` ou `authentication_required`). O evento vai para o `postbackUrl` da cobrança e para os endpoints da própria conta. O payload simulado não é idêntico ao real, então não o use como referência de schema.

## Guias de cada família

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Payload completo de cada evento `charge.*` e do `charge.updated`.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos `subscription.*`, objeto `charge` e tipos de cancelamento.

> [card] [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
>
> `payout.approved` e `payout.rejected` das subcontas.

> [card] [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)
>
> Avisos de aprovação, correção e bloqueio de subcontas.

## Veja também

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

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


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