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

> Consuma webhooks de transação de Pix, voucher e cartão usando o payload público que a Pagou entrega hoje.

Webhooks de pagamento sempre usam o envelope de transaction. O `event` de topo permanece `transaction`; o nome concreto do evento fica em `data.event_type`.

## Exemplo de payload entregue

```json theme={null}
{
  "id": "evt_pay_1001",
  "event": "transaction",
  "api_version": "v1",
  "data": {
    "id": "018f1f2e-7b44-7c9a-8d3e-1a2b3c4d5e71",
    "event_type": "transaction.pending",
    "correlation_id": "order_3001",
    "method": "voucher",
    "status": "pending",
    "amount": 125000,
    "currency": "MXN",
    "voucher": {
      "barcode": "646180123456789012",
      "digitable_line": "646180123456789012",
      "url": "https://payments.example/pay/order_3001",
      "expiration_date": "2026-05-12T23:59:59.000Z",
      "instructions": "Pague usando a referência bancária antes do vencimento.",
      "receipt_url": null
    },
    "informations": [
      { "key": "order_id", "value": "order_3001" },
      { "key": "channel", "value": "app" }
    ]
  }
}
```

`data.informations` devolve o array `informations` que você enviou ao criar a transação via API — use-o para reconciliar o evento com os seus próprios registros. Só aparece quando você enviou entradas customizadas na criação; transações sem elas (ou criadas por checkout links) omitem o campo.

## Resposta de ACK

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

## Eventos emitidos hoje

* `transaction.created`
* `transaction.pending`
* `transaction.paid`
* `transaction.cancelled`
* `transaction.refunded`
* `transaction.partially_refunded`
* `transaction.chargedback`
* `transaction.three_ds_required`

## Erro comum de ingestão

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

Como corrigir: faça deduplicação pelo `id` do evento no topo, não pelo ID da transaction, porque a mesma transaction pode emitir mais de um evento ao longo do tempo.

## Guia de mapeamento

* Use `transaction.paid` para liberar bens ou serviços.
* Mantenha o pedido aberto em `transaction.pending`.
* Para `method: "voucher"`, `transaction.pending` também pode carregar instruções de pagamento em `data.voucher`. Exiba `url`, `digitable_line`, `barcode` ou `instructions` e continue aguardando `transaction.paid`.
* Use eventos de reembolso e chargeback para fluxos de financeiro e suporte.
* Encaminhe `transaction.three_ds_required` de volta para o seu fluxo de challenge de cartão.