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

# Transfer Events

> Handle Pix Out webhook events using the live payout envelope Pagou emits today.

Transfer webhooks use a payout-style envelope. The concrete event name is always the top-level `type`, and the transfer resource is in `data.object`.

## Example delivery payload

```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"
    }
  }
}
```

## ACK response

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

## Event names emitted today

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

## Common ingestion error

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

Fix: deduplicate by the top-level event `id`. Keep your own mapping between webhook event names and resource statuses.

## Mapping guidance

* `payout.transferred` means the resource is settled with status `paid`.
* `payout.failed` usually maps to resource status `error`.
* `payout.canceled` maps to resource status `cancelled`.
* Reconcile when operator state and webhook state disagree.