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

# Eventos de transferência

> Consuma eventos de Pix Out usando o envelope de payout que a Pagou emite hoje.

Webhooks de transferência usam um envelope no estilo payout. O nome concreto do evento está sempre em `type` no topo, e o recurso de transferência fica em `data.object`.

## Exemplo de payload entregue

```json theme={null}
{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "api_version": "v2",
  "data": {
    "object": {
      "id": "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
      "status": "paid",
      "type": "pix",
      "amount": 1200,
      "fee": 50,
      "net_amount": 1150,
      "transferred_at": "2026-03-16T14:05:00.000Z"
    }
  }
}
```

## Resposta de ACK

```json theme={null}
{
  "received": true
}
```

## Eventos emitidos hoje

* `payout.created`
* `payout.in_analysis`
* `payout.processing`
* `payout.transferred`
* `payout.failed`
* `payout.rejected`
* `payout.canceled`

## Erro comum de ingestão

```json theme={null}
{
  "error": "missing_event_id"
}
```

Como corrigir: faça deduplicação pelo `id` do evento no topo. Mantenha seu próprio mapeamento entre nomes de evento de webhook e status do recurso.

## Guia de mapeamento

* `payout.transferred` significa que o recurso foi liquidado com status `paid`.
* `payout.failed` geralmente mapeia para status do recurso `error`.
* `payout.canceled` mapeia para status do recurso `cancelled`.
* Reconcilie quando o estado operacional e o estado do webhook divergirem.