> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Webhooks

Webhooks são notificações enviadas pela nossa API para a URL cadastrada sempre que um evento relevante ocorre (por exemplo, um PIX é recebido ou um pagamento é concluído).

## Configuração de Webhooks

O jeito de criar e manter assinaturas depende do seu produto:

#### BaaS (tenant)

Você tem dois caminhos, equivalentes e sincronizados:

* **API** — `POST /v1/webhooks` e demais rotas descritas nesta página. É o caminho para automatizar a configuração junto com o resto do seu deploy.
* **Portal do Integrador** — além de criar e editar assinaturas, é onde você **gerencia o dia a dia**: reenvia entregas que falharam, depura erros (status HTTP e corpo devolvidos pelo seu endpoint), consulta o **histórico de envios** de cada evento e troca a chave HMAC sem interromper o fluxo.

Use a API para provisionar e o Portal para operar e investigar.

#### Internet Banking (conta)

A configuração é **somente por API**: não há Portal do Integrador para
credenciais de conta. Você cria a assinatura com `POST /v1/webhooks`
informando o `accountId` da sua conta, assina a requisição com JWS como
qualquer outra chamada, e gerencia reenvios e histórico pelas rotas de
entregas (`GET /v1/webhooks/{subscriptionId}/deliveries` e `POST .../deliveries/{deliveryId}/retry`).

O passo a passo, com os eventos disponíveis para a conta e o exemplo
completo de verificação HMAC, está em
[Webhooks da conta (Internet Banking)](/ib/guias/conta/webhooks).

## Listar Eventos Disponíveis

```bash
curl -X GET "https://tenant.api.corpx.com/v1/webhooks/events" \
     -H "Authorization: Bearer YOUR_TOKEN"
```

**Resposta** (array de `{ event, description }`; trecho ilustrativo):

```json
[
  { "event": "pix.in.completed", "description": "PIX recebido com sucesso" },
  { "event": "pix.out.completed", "description": "PIX enviado com sucesso" },
  { "event": "accreditation.pf.created", "description": "Accreditation PF criada (confirmação assíncrona do POST)" },
  { "event": "accreditation.pj.created", "description": "Accreditation PJ criada (confirmação assíncrona do POST)" },
  { "event": "accreditation.biometry.link.created", "description": "Link de captura facial gerado (fluxo Unico; por pessoa)" },
  { "event": "accreditation.acceptance.link.created", "description": "Link de aceite dos termos gerado (por pessoa; somente em fluxos habilitados sob demanda)" },
  { "event": "accreditation.consent.link.created", "description": "Link de autorização gerado — CPF já tem conta (por pessoa)" },
  { "event": "accreditation.updated", "description": "Transição de status da accreditation" },
  { "event": "accreditation.active", "description": "Conta pronta para operar — accountId disponível" },
  { "event": "accreditation.failed", "description": "Accreditation encerrada sem abertura de conta" },
  { "event": "account.shared_access.granted", "description": "Outro tenant passou a operar uma conta que você já operava" },
  { "event": "boleto.charge.batch.completed", "description": "Lote de Boleto Charge concluiu todas as tentativas de emissão" },
  { "event": "pix.batch.completed", "description": "Lote de PIX terminou com estatísticas de sucesso e falha (cada item também emite pix.out.*)" },
  { "event": "identity.verification.completed", "description": "Verificação de identidade standalone concluída" },
  { "event": "policy.violation", "description": "Uma regra de política foi violada — operação recusada (BLOCK), apenas avisada (NOTIFY_ONLY / ALLOW_AND_NOTIFY), PIX devolvido (AUTO_REFUND), valor travado (LOCK_BALANCE) ou saída da conta cortada (BLOCK_ACCOUNT)" },
  { "event": "limit_request.created", "description": "Pedido de aumento de limite aberto (não sai de novo no replay da Idempotency-Key)" },
  { "event": "limit_request.updated", "description": "Pedido de aumento de limite mudou de status (aprovado, recusado ou cancelado)" },
  { "event": "account.limits.updated", "description": "Teto da conta ou de um operador mudou. Não inclui padrão de tenant nem a virada de um afrouxamento já agendado" }
]
```

A lista completa inclui também PIX out/refund/MED, QR Code, boleto, TED, transferências internas e tarifas. Eventos de onboarding estão documentados em [Webhooks de Onboarding](/baas/guias/abertura-de-contas/webhooks).

## Fluxo de Recebimento

1. Um evento ocorre na nossa plataforma.
2. Enviamos uma requisição `POST` para as URLs cadastradas.
3. Sua aplicação deve processar a notificação e retornar um status `2xx`.

### Flexibilidade de Configuração

Nossa infraestrutura de webhooks suporta diversos métodos de entrega:

* **Agrupamento**: Você pode receber múltiplos tipos de evento (por exemplo, `pix.in.completed` e `pix.out.completed`) na mesma URL.
* **Segregação**: Você pode configurar URLs diferentes para cada tipo de evento.
* **Redundância**: Podemos enviar o mesmo evento para múltiplas URLs independentes simultaneamente.
* **Segmentação por conta**: uma assinatura pode receber só os eventos de **uma** conta — ver abaixo.

### Assinatura por conta (`accountId`)

Por padrão uma assinatura é do **tenant**: ela recebe os eventos de todas as suas contas. Informando `accountId` na criação, ela passa a receber **apenas** os eventos daquela conta:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-dominio.com/webhooks/acc-123",
    "events": ["pix.in.completed", "pix.out.completed"],
    "accountId": "acc-123",
    "authType": "HMAC",
    "secret": "..."
  }'
```

O campo volta no `GET /v1/webhooks` (`accountId: null` para as assinaturas do tenant).

Regras que valem a pena conhecer antes de usar:

* **Filtro, não roteamento adicional.** Uma assinatura com `accountId` deixa de receber os eventos das outras contas. Quem quer tudo em um lugar e um recorte em outro precisa de duas assinaturas.
* **Não é editável.** `accountId` só entra na criação. Trocar a conta de uma assinatura viva redirecionaria silenciosamente o fluxo de eventos de uma conta para o endpoint configurado para outra — criar uma assinatura nova é explícito e deixa a antiga auditável.
* **Credencial restrita a contas é obrigada a informar.** Se a credencial só alcança um conjunto de contas (é o caso das credenciais delegadas), omitir `accountId` devolve **422** `account_id_required`, e informar uma conta de fora do conjunto devolve **403** `forbidden`. Sem isso, uma credencial de uma conta criaria uma assinatura para o movimento de outra e leria tudo pelo webhook, contornando o controle que as rotas de leitura aplicam.
* **Conta de outro tenant** devolve **404** `account_not_found`.
* **Eventos sem conta** (por exemplo os de accreditation, antes de a conta existir) só chegam nas assinaturas do tenant.
* **O filtro vale também na entrega.** Uma assinatura com `accountId` não recebe o evento das outras contas, mesmo quando o tenant tem outra assinatura para o mesmo tipo. O `accountId` do envelope é o da conta em que o evento aconteceu.

## Segurança (Autenticação de Destino)

Ao criar ou atualizar uma assinatura de webhook, você pode escolher como nossa infraestrutura de entrega autentica as requisições enviadas ao seu endpoint. O método de autenticação é configurado por assinatura via API ou dashboard.

### Métodos de Autenticação Disponíveis

| Método                   | Valor de `authType` | Descrição                                                                                                                              |
| ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Assinatura HMAC**      | `HMAC`              | Assina o corpo de cada requisição com seu segredo usando HMAC-SHA256. A assinatura é enviada no header `X-Signature`. **Recomendado.** |
| **Padrão da plataforma** | `NONE`              | Sem chave sua. As entregas continuam assinadas, mas com a assinatura padrão da nossa infraestrutura, que você não controla.            |

Você configura o método ao criar ou atualizar uma assinatura, pela API ou pelo **Portal do Integrador** (**Webhooks > Editar Assinatura**).

### Trocar ou remover a chave

O segredo **nunca volta** em nenhuma resposta — a assinatura só informa
`hmacSecretSet: true|false`. Por isso:

* **Omitir `secret`** em um `PUT` mantém a chave atual. É o que permite trocar
  só a URL sem perder a assinatura.
* **Enviar `secret`** substitui a chave (rotação).
* **Enviar `authType: "NONE"`** apaga a chave e para de assinar com ela. Este é
  o único jeito de desligar.

Qualquer outro valor em `authType` é recusado com `400 unsupported_auth_type`.

---

### Verificação de Assinatura HMAC

Quando `authType` está definido como `HMAC`, cada requisição inclui um header **`X-Signature`** contendo o HMAC-SHA256 do corpo bruto em **Base64 padrão, com padding**, calculado com o seu `secret` como chave.

**Fórmula:**

```text
expected = base64(HMAC_SHA256(your_secret, raw_request_body))
```

Compare o valor calculado com o header `X-Signature`. Se forem iguais, a requisição é autêntica.

> **Warning**
>
> Sempre utilize os **bytes brutos do corpo da requisição** para verificação, não uma versão re-parseada/re-serializada. Re-serializar JSON pode alterar a ordem dos campos ou espaços em branco, o que invalidará a assinatura.

#### Exemplos de Verificação

**Node.js:**

```javascript
const crypto = require("crypto");

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("base64");
  return expected === signatureHeader;
}

// In your Express handler:
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-signature"];
  if (!verifySignature(WEBHOOK_SECRET, req.body, signature)) {
    return res.status(403).send("Invalid signature");
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.sendStatus(200);
});
```

**Python:**

```python
import base64, hmac, hashlib

def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode()
    return hmac.compare_digest(expected, signature_header)
```

**Go:**

```go
func verifySignature(secret string, rawBody []byte, signatureHeader string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(rawBody)
    expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}
```

---

### Headers Informativos

Além dos headers de autenticação acima, nossa infraestrutura de entrega adiciona os seguintes headers informativos em todas as requisições:

| Header                     | Descrição                                                                |
| -------------------------- | ------------------------------------------------------------------------ |
| `x-hookdeck-event-id`      | ID do evento de entrega (útil para depuração e solicitações de suporte). |
| `x-hookdeck-request-id`    | ID da requisição original.                                               |
| `x-hookdeck-attempt-count` | Número da tentativa de entrega (1 para a primeira tentativa).            |

Esses headers são informativos e não precisam ser validados.

### IP Whitelist

Para aumentar a segurança da sua integração, recomendamos que seu servidor de destino valide o endereço IP de origem das requisições. Aceite notificações apenas dos seguintes IPs da nossa infraestrutura:

* `34.138.140.223`
* `34.138.161.100`
* `35.231.250.193`
* `35.196.71.29`
* `34.138.56.192`

Sugerimos adicionar esses endereços a uma **whitelist** no seu firewall ou servidor web.

## Retentativas

Se sua aplicação retornar um erro (status diferente de 2xx) ou ocorrer um timeout, nosso sistema tentará reenviar a notificação seguindo uma estratégia de backoff exponencial:

* Tentativas: Até 6 vezes.
* Intervalos: Progressivamente crescentes.

Após esgotar todas as tentativas, a entrega fica com `status: failed`. Você pode solicitar um reenvio manual daquela entrega específica.

`GET /v1/webhooks/{subscriptionId}/deliveries` devolve o resultado **no seu endpoint**, não o aceite da nossa rede de entrega:

| `status`         | significado                                                    |
| ---------------- | -------------------------------------------------------------- |
| `pending`        | aceito para entrega, ainda sem tentativa                       |
| `retrying`       | a última tentativa falhou e há outra marcada (`nextAttemptAt`) |
| `delivered`      | seu endpoint respondeu 2xx (`responseStatus`)                  |
| `failed`         | as tentativas acabaram                                         |
| `paused`         | a assinatura está pausada                                      |
| `not_dispatched` | o evento não chegou a ser encaminhado                          |

`dispatchStatus` é o passo anterior (`success` = encaminhado, `exhausted` = não saiu). Era o que `status` significava antes. O filtro `status=success` continua aceito e equivale a `delivered`; `exhausted` equivale a `not_dispatched`.

## Reenvio de Entrega (Retry)

Para reenviar uma entrega que falhou, use o endpoint de retry por entrega,
informando a `subscriptionId` e a `deliveryId` (ambas visíveis na listagem de
entregas da assinatura):

**Exemplo de Requisição:**

```bash
curl -X POST "https://tenant.api.corpx.com/v1/webhooks/{subscriptionId}/deliveries/{deliveryId}/retry" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "X-Tenant-Id: your-tenant-id"
```

A API enfileira uma nova tentativa de entrega para aquela `deliveryId`. Se o reenvio em lote estourar o limite da rede de entrega, a resposta é **429** `rate_limited` com header `Retry-After` — espere e tente de novo. Não é falha da entrega.

## Formato das Notificações

Todas as notificações seguem um formato de envelope padrão. O conteúdo específico de cada evento está no objeto `data`.

### Envelope Padrão

```json
{
  "id": "evt_123456789",
  "type": "pix.in.completed",
  "occurredAt": "2025-12-29T21:14:33.912Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": { }
}
```

| Campo do envelope | Descrição                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `id`              | ID determinístico do evento (idempotência: mesmo `id` ⇒ mesmo evento, possivelmente re-entregue).              |
| `type`            | Tipo do evento. Lista completa em `GET /v1/webhooks/events`.                                                   |
| `occurredAt`      | RFC 3339 / ISO 8601 UTC com sufixo `Z`.                                                                        |
| `schemaVersion`   | `"1.0"` atualmente. Será incrementado em mudanças de formato breaking.                                         |
| `environment`     | `"production"` ou `"sandbox"`.                                                                                 |
| `tenantId`        | Tenant alvo do evento. Útil quando o mesmo endpoint serve múltiplos tenants.                                   |
| `accountId`       | Conta CorpX onde o evento ocorreu (vazio para eventos cross-account, ex.: `account.balance_updated` agregado). |
| `data`            | Payload específico do evento.                                                                                  |

> **Valores em BRL**
>
> Todos os valores monetários (`amount`, `paidAmount`, etc.) são sempre em **BRL** (Reais). Decimais usam ponto (`150.50`), nunca vírgula. Os eventos de PIX out (`pix.out.completed`, `pix.out.failed`, `pix.out.timeout` e `pix.refund.*` do mesmo fluxo) incluem `data.currency: "BRL"`. Outros eventos podem omitir o campo — o valor continua em reais.

> **Body HTTP vs painel**
>
> O POST na sua URL é o envelope completo. O JSON de "webhook entregue" no painel mostra só o objeto `data` (às vezes rotulado `deliveredData`).

### Campos comuns dentro de `data`

Alguns campos aparecem em **todos** os tipos de evento que representam um lançamento no extrato (PIX IN/OUT, refund, QR paid, transferência interna, tarifa). Eles são a forma recomendada de amarrar o webhook com outros endpoints da API:

| Campo                     | Descrição                                                                                                                                                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId`           | Identificador da transação no formato usado pela nossa API. Bate com o que aparece no `GET /v1/accounts/{accountId}/statement` e com a resposta síncrona do endpoint que originou a transação. Use para buscar a transação nas nossas APIs. |
| `coreId`                  | Identificador (UUID) da linha no core bancário do parceiro. É o mesmo valor exposto no campo `coreId` do extrato e permanece estável entre o webhook e o sync assíncrono. Use para reconciliar com exports do parceiro.                     |
| `endToEnd` / `endToEndId` | ID E2E do PIX no Banco Central (somente para eventos PIX).                                                                                                                                                                                  |
| `status`                  | Estado da transação. Vocabulário padronizado (ver tabela abaixo).                                                                                                                                                                           |

Os três primeiros campos podem coexistir no mesmo payload. Se só um estiver presente, é porque o outro não existe para aquele tipo de evento (por exemplo: transferências internas têm `transactionId` + `coreId` mas não têm `endToEnd`).

### Valores de `data.status`

O campo `status` usa um vocabulário **padronizado** em todos os eventos:

| Status      | Significado                                                                                                                                                   | Eventos em que aparece                                                                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`   | Operação concluída com sucesso, saldo debitado/creditado.                                                                                                     | `pix.in.completed`, `pix.out.completed`, `pix.refund.completed`, `pix.refund.received`, `qrcode.paid`, `boleto.paid`, `transfer.internal.in`, `transfer.internal.out`, `fee.charged`, `fee.refunded` |
| `FAILED`    | Operação falhou. Saldo **não** foi alterado (ou foi devolvido). Verifique `data.error` para detalhes.                                                         | `pix.out.failed`, `pix.refund.failed`, `boleto.failed`                                                                                                                                               |
| `TIMEOUT`   | A chamada ao parceiro foi enviada com sucesso mas o tempo de resposta estourou. Verifique o extrato antes de tentar novamente com nova chave de idempotência. | `pix.out.timeout`                                                                                                                                                                                    |
| `EXPIRED`   | QR Code dinâmico expirou sem ser pago até o `expirationDate` pedido (24 horas quando o campo não foi enviado).                                                | `qrcode.expired`                                                                                                                                                                                     |
| `CANCELLED` | QR Code dinâmico cancelado por chamada explícita do integrador (`DELETE /v1/accounts/{accountId}/pix/qr-code?identifier=...`).                                | `qrcode.cancelled`                                                                                                                                                                                   |
| `REVERSED`  | PIX IN que tinha sido concluído mas foi revertido (ex.: devolução total). Aparece se a reconciliação tardia alterar o status de um PIX IN já entregue.        | `pix.in.completed` (raro, pós-reconciliação)                                                                                                                                                         |

Para eventos de MED (disputa), `status` usa um vocabulário **próprio**:

| Status             | Significado                                                                             |
| ------------------ | --------------------------------------------------------------------------------------- |
| `OPEN`             | Disputa aberta pelo reclamante, dentro do prazo de 48h para a sua resposta.             |
| `PENDING_DECISION` | Prazo da sua resposta vencido — a disputa segue viva, mas a decisão saiu das suas mãos. |
| `ACCEPTED`         | Disputa aceita — valor devolvido (total ou parcialmente).                               |
| `REJECTED`         | Disputa rejeitada — valor permanece com o recebedor.                                    |
| `CANCELED`         | Disputa cancelada por quem a abriu.                                                     |

Eventos em que aparece: `pix.med.opened`, `pix.med.updated`.

Esse `status` é o estado **no instante do evento**, e nisso é confiável: é a
própria notificação do liquidante. É por isso que ele não existe no `GET
/v1/accounts/{id}/pix/med` — lá seria um valor guardado, sem consulta que o
confirme. Se você precisa acompanhar o estado de uma disputa, acumule estes
eventos: eles são a única fonte.

> **Garantia do \`status\`**
>
> O `status` é **sempre presente** em eventos que representam lançamento de extrato. Se você recebeu um webhook que não tem o campo (ou está vazio), é porque é um evento puramente informativo (ex.: `account.balance_updated`) — nesses casos use o próprio `type` para determinar a semântica.

### Formato de datas e horários

Os campos de data/hora seguem **ISO 8601 / RFC 3339 com fuso explícito** — leia o offset, não assuma. **Webhooks** (envelope `occurredAt` e campos dentro de `data` como `receivedAt`, `completedAt`, `initiatedAt`, `chargedAt`, `openedAt`) são sempre em **UTC (`Z`)**. Nas respostas **REST**, os campos "do nosso lado" (`createdAt`, `updatedAt`, `reconciledAt`, `fetchedAt`, saldo) também são UTC (`Z`); já o **horário da transação** no extrato e nos lookups — campo `timestamp` (`/statement`, `/pix/transactions`) e `occurredAt` (`/pix/payments/lookup`, boleto) — sai em **horário de Brasília (`-03:00`)**.

Exemplos:

```text
2026-04-29T23:53:55.001Z         ← com milissegundos
2026-04-29T23:53:49.328720Z      ← com microssegundos
2026-04-30T18:04:36Z             ← sem fração de segundo
```

**Nunca emitimos** timestamps no fuso local brasileiro (BRT) nem timestamps "naive" (sem indicador de fuso). Caso você receba um campo de data sem o `Z` no final, considere bug e nos avise — converteremos sempre que detectarmos a fonte.

---

## Tipos de Eventos e Conteúdos (`data`)

### 1. `pix.in.completed`

Enviado quando um PIX é recebido com sucesso (entrada) na conta. O `id` do envelope é `pix-in-{endToEnd}`.

**Campos sempre presentes em `data`:**

* `transactionId`: ID da transação no nosso sistema.
* `endToEnd`: ID E2E do BACEN.
* `accountId` / `tenantId`
* `amount`: valor em reais.
* `description`: descrição (pode ser vazia).
* `method`: `STATIC_QR_CODE`, `DYNAMIC_QR_CODE` ou `DICT`.
* `receivedAt`: RFC 3339 UTC (`Z`).
* `status`: `"SUCCESS"`.

**Campos condicionais:**

* `identifier`: txid do QR quando o crédito veio de um QR Code.
* `payer` / `payee`: só entram chaves com valor (`name`, `document`, `bankCode`, `bankIspb`, `branch`, `account`, `accountNumber`, `pixKey`). Quando a conta existe, `account` e `accountNumber` repetem o mesmo valor.

Este evento **não** envia `reconciliationId` nem `currency`.

**Exemplo Completo:**

```json
{
  "id": "pix-in-E0000000020251229211433912",
  "type": "pix.in.completed",
  "occurredAt": "2025-12-29T21:14:33.912Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "transactionId": "2ee948cb-4e03-43d1-b202-b7fb31d5b016",
    "endToEnd": "E0000000020251229211433912",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 150.50,
    "description": "PIX Recebido",
    "identifier": "SEV798c4a1f4b2e4d9c8a1b2c3d4",
    "method": "STATIC_QR_CODE",
    "status": "SUCCESS",
    "receivedAt": "2025-12-29T21:14:33.912Z",
    "payer": {
      "name": "JOAO SILVA",
      "document": "12345678900",
      "bankCode": "001",
      "bankIspb": "00000000",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    },
    "payee": {
      "name": "ACME LTDA",
      "document": "12345678000199",
      "bankCode": "208",
      "bankIspb": "50871921",
      "branch": "1",
      "account": "3811084",
      "accountNumber": "3811084"
    }
  }
}
```

### 2. `qrcode.paid`

Enviado quando um QR Code gerado por você é pago. No mesmo crédito também sai [`pix.in.completed`](#1-pixincompleted).

**Campos sempre presentes em `data`:** `qrcodeId`, `identifier`, `accountId`, `tenantId`, `type` (hoje `static`, `dynamic`, `due-date` ou `location`; a lista é extensível e pode ganhar valores, então não recuse o evento por um `type` desconhecido), `amount`, `endToEnd`, `transactionId`, `status` (`"SUCCESS"`), `receivedAt`.

No QR **com vencimento** e no **Location**, `amount` é o valor efetivamente pago, já com desconto, juros ou multa. No QR **dinâmico**, `payer` traz só `name` e `document`. No **estático** podem vir dados bancários e `payee`. Este evento **não** envia `reconciliationId`.

**Exemplo Completo (QR dinâmico):**

```json
{
  "id": "qrcode-paid-txid-qr-123",
  "type": "qrcode.paid",
  "occurredAt": "2025-12-29T21:15:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "qrcodeId": "txid-qr-123",
    "identifier": "order-12345",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "type": "dynamic",
    "amount": 250.00,
    "endToEnd": "E0000000020251229211500000",
    "transactionId": "162982-pix",
    "status": "SUCCESS",
    "receivedAt": "2025-12-29T21:15:00.000Z",
    "payer": {
      "name": "MARIA OLIVEIRA",
      "document": "98765432100"
    }
  }
}
```

### 3. `pix.out.completed`

Enviado quando uma transferência PIX de saída é concluída com sucesso.

O POST na sua URL é o **envelope** (`id`, `type`, `occurredAt`, `schemaVersion`, `environment`, `tenantId`, `accountId`, `data`). No painel do integrador, o JSON de "webhook entregue" mostra só o conteúdo de `data` (às vezes rotulado `deliveredData`) — não é o body HTTP.

**Campos sempre presentes em `data`:**

* `paymentId`: ID da ordem (o mesmo da resposta `202` do POST async). O `id` do envelope é `pix-out-{paymentId}`.
* `tenantId`, `accountId`: repetidos dentro de `data` (também estão no envelope).
* `status`: `"SUCCESS"`.
* `endToEnd`: ID E2E do BACEN (string vazia se o liquidante ainda não emitiu).
* `transactionId`: ID da transação no liquidante, quando houver.
* `amount`: valor em reais.
* `currency`: sempre `"BRL"`.
* `description`: descrição enviada no POST (pode ser string vazia).
* `identifier`: sua chave de conciliação.
* `originalTransactionId`: ID da transação original em devoluções; string vazia no PIX out comum.
* `initiatedAt` / `completedAt`: RFC 3339 UTC (`Z`), com fração de segundo (até nanossegundos).

**Campos condicionais:**

* `key`: `{ "type", "key" }` quando o envio foi por chave PIX.
* `payee`: destinatário. Só entram chaves com valor: `name`, `document`, `bankCode`, `bankIspb`, `branch`, `accountNumber`, `pixKey`, `accountType`.
* `payer`: conta origem. Só entra quando o webhook do banco liquidante trouxe esses dados — não presuma que sempre vem.
* `late`: `true` apenas quando a confirmação chegou **depois** de um [`pix.out.timeout`](#13-pixouttimeout) para o mesmo `paymentId`. Ausente no caso normal. Ver [Confirmação tardia](#confirmação-tardia-late-true).

Este evento **não** envia `reconciliationId`, `method` nem um objeto `payment`.

**Exemplo Completo:**

```json
{
  "id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.out.completed",
  "occurredAt": "2026-09-16T20:58:46.258668746Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "status": "SUCCESS",
    "endToEnd": "E508719212026091620583702716219",
    "transactionId": "162982-pix",
    "amount": 50.00,
    "currency": "BRL",
    "description": "Pagamento fornecedor",
    "identifier": "transfer-001",
    "originalTransactionId": "",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z",
    "key": {
      "type": "EMAIL",
      "key": "destinatario@exemplo.com"
    },
    "payer": {
      "name": "ACME LTDA",
      "document": "12345678000199",
      "bankCode": "208",
      "bankIspb": "50871921",
      "branch": "1",
      "accountNumber": "3811084"
    },
    "payee": {
      "name": "JOAO SILVA",
      "document": "12345678900",
      "bankCode": "077",
      "bankIspb": "00416968",
      "branch": "1",
      "accountNumber": "0013887580"
    }
  }
}
```

### 4. `pix.out.failed`

Enviado quando uma transferência PIX de saída falha **de forma definitiva** — o parceiro bancário recusou a operação (saldo insuficiente, chave inválida, antifraude, recusa do BACEN etc.) e o saldo não foi alterado (ou foi devolvido).

> **Evento terminal**
>
> `pix.out.failed` é terminal: uma vez recebido, não haverá `pix.out.completed` posterior para a mesma ordem. Cenários de **incerteza** (ex.: timeout de comunicação com o parceiro, sem confirmação do desfecho) emitem [`pix.out.timeout`](#13-pixouttimeout) — nunca `pix.out.failed`.

O `data` usa os **mesmos campos** de [`pix.out.completed`](#3-pixoutcompleted), com:

* `status`: `"FAILED"`.
* `error` / `errorCode` / `errorReason`: motivo da recusa (`error` é o alias amigável).
* `partner`: erro cru do liquidante, quando houver.
* `late`: `true` apenas quando a recusa chegou **depois** de um [`pix.out.timeout`](#13-pixouttimeout) para o mesmo `paymentId`. Ver [Confirmação tardia](#confirmação-tardia-late-true).

Este evento **não** envia `reconciliationId`.

**Exemplo Completo:**

```json
{
  "id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.out.failed",
  "occurredAt": "2026-09-16T20:58:46.258668746Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "status": "FAILED",
    "endToEnd": "E508719212026091620583702716219",
    "transactionId": "162982-pix",
    "amount": 1000.00,
    "currency": "BRL",
    "description": "Pagamento fornecedor",
    "identifier": "transfer-002",
    "originalTransactionId": "",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z",
    "error": "saldo insuficiente",
    "errorCode": "insufficient_balance",
    "errorReason": "saldo insuficiente",
    "key": {
      "type": "EMAIL",
      "key": "destinatario@exemplo.com"
    },
    "payee": {
      "name": "JOAO SILVA",
      "document": "12345678900",
      "bankCode": "077",
      "bankIspb": "00416968",
      "branch": "1",
      "accountNumber": "0013887580"
    }
  }
}
```

### 5. `payment.sent` *(removido)*

> **Removido em v1.28.0 (2026-04-17)**
>
> Este evento foi marcado como deprecated na v1.15.0 (2026-02-20) e foi **permanentemente desativado** na v1.28.0 (2026-04-17). Use `pix.out.completed` com o campo `method` (`PAYMENT`) e o objeto `payment` no payload.

### 6. `payment.refunded` *(removido)*

> **Removido em v1.28.0 (2026-04-17)**
>
> Este evento foi marcado como deprecated na v1.15.0 (2026-02-20) e foi **permanentemente desativado** na v1.28.0 (2026-04-17). Use `pix.refund.completed`. O payload é o mesmo de `pix.out.completed` (`endToEnd` desta devolução, `originalTransactionId` da transação original). Não envia `originalEndToEnd` nem `refundEndToEnd`.

### 7. `pix.refund.completed`

Enviado quando uma devolução PIX **que nós disparamos** é concluída. O payload é o **mesmo** de [`pix.out.completed`](#3-pixoutcompleted). O `id` do envelope é `pix-refund-{paymentId}`.

* `endToEnd`: E2E **desta** devolução.
* `originalTransactionId`: ID da transação original (não vem vazio).

Este evento **não** envia `originalEndToEnd`, `refundEndToEnd` nem `reconciliationId`. Esses E2Es existem em [`pix.refund.received`](#14-pixrefundreceived).

**Exemplo Completo:**

```json
{
  "id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.refund.completed",
  "occurredAt": "2026-09-16T20:58:46.258668746Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "status": "SUCCESS",
    "endToEnd": "D508719212026091620583702716219",
    "transactionId": "162982-pix",
    "amount": 150.50,
    "currency": "BRL",
    "description": "Devolução PIX",
    "identifier": "refund-999",
    "originalTransactionId": "2ee948cb-4e03-43d1-b202-b7fb31d5b016",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z"
  }
}
```

### 8. `pix.refund.failed`

Enviado quando a devolução que nós disparamos falha. Mesmo shape de [`pix.out.failed`](#4-pixoutfailed), com `type: "pix.refund.failed"` e `id` `pix-refund-{paymentId}`.

**Exemplo Completo:**

```json
{
  "id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.refund.failed",
  "occurredAt": "2026-09-16T20:58:46.258668746Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "status": "FAILED",
    "endToEnd": "",
    "amount": 150.50,
    "currency": "BRL",
    "description": "Devolução PIX",
    "identifier": "refund-998",
    "originalTransactionId": "2ee948cb-4e03-43d1-b202-b7fb31d5b016",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z",
    "error": "transação original já devolvida",
    "errorCode": "already_refunded",
    "errorReason": "transação original já devolvida"
  }
}
```

### 9. `fee.charged`

Enviado quando uma tarifa bancária é cobrada na conta (por exemplo, tarifa por transação PIX).

**Estrutura do `data`:**

* `transactionId`: ID determinístico da row de tarifa no nosso ledger (`fee-{coreId}`).
* `accountId` / `tenantId`: Conta cobrada e tenant.
* `amount`: Valor da tarifa, **sempre positivo** em reais.
* `description`: Descrição da tarifa.
* `feeServiceType`: Tipo de serviço que originou a tarifa (`PIX`, `BOLETO`, `P2P_CRYPTO`, etc.) quando o banco informa.
* `originalRef` / `transactionRef`: Referência cruzada com a movimentação que gerou a tarifa, quando disponível.
* `occurredAt`: Timestamp da cobrança no banco.
* `status`: Sempre `"SUCCESS"`.
* `kind`: `"CHARGED"`.

**Exemplo Completo:**

```json
{
  "id": "evt_fee_123",
  "type": "fee.charged",
  "occurredAt": "2026-02-14T20:30:43.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "transactionId": "fee-9c1f...e2",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 2.99,
    "description": "TARIFA",
    "feeServiceType": "PIX",
    "originalRef": "tx_38a1b2",
    "transactionRef": "tx_38a1b2",
    "occurredAt": "2026-02-14T20:30:43.000Z",
    "status": "SUCCESS",
    "kind": "CHARGED"
  }
}
```

### 9.1. `fee.refunded`

Enviado quando o banco **estorna** uma tarifa que havia sido cobrada (ex.: cashback, ajuste). Mesmo formato de `fee.charged`, com `kind="REFUNDED"`. O sinal é informacional — o crédito já foi aplicado na conta. A `description` pública de qualquer crédito vindo das contas de tarifa é `LANÇAMENTO DE CRÉDITO` (o tipo do evento não muda).

**Exemplo Completo:**

```json
{
  "id": "evt_fee_456",
  "type": "fee.refunded",
  "occurredAt": "2026-02-15T13:42:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "transactionId": "fee-7c2a...11",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 2.99,
    "description": "LANÇAMENTO DE CRÉDITO",
    "feeServiceType": "PIX",
    "originalRef": "fee-9c1f...e2",
    "occurredAt": "2026-02-15T13:42:11.000Z",
    "status": "SUCCESS",
    "kind": "REFUNDED"
  }
}
```

### 10. `pix.med.opened`

Enviado quando uma nova disputa MED (Mecanismo Especial de Devolução) é aberta contra uma transação **creditada em uma das suas contas**. A partir dele começa a correr o prazo de **48h** para a sua resposta — ver [Guia de Disputas](/baas/guias/pagar/med).

**Estrutura do `data`:**

* `medId`: Identificador da disputa (infraction report). É o `{medId}` das rotas REST.
* `originalEndToEnd`: `endToEndId` da transação PIX em disputa.
* `amount`: Valor disputado.
* `reasonCode`: Motivo reportado pelo arranjo, cru (ex.: `scam-or-fraud`, `unauthorized-transaction`).
* `claimMessage`: Detalhes textuais informados pelo reclamante (quando presente).
* `openedAtIso`: Data de abertura do MED (ISO 8601).
* `clientAnswerDeadlineIso`: Prazo da sua resposta — `openedAtIso` + 48h.
* `status`: `OPEN` na abertura.

**Exemplo Completo:**

```json
{
  "id": "evt_med_123",
  "type": "pix.med.opened",
  "occurredAt": "2026-07-21T17:55:59.601Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
    "originalEndToEnd": "E0000000020251229211433912",
    "amount": 150.50,
    "reasonCode": "scam-or-fraud",
    "claimMessage": "Vide contatos informados na FundsRecovery",
    "openedAtIso": "2026-07-21T17:55:59.601Z",
    "clientAnswerDeadlineIso": "2026-07-23T17:55:59.601Z",
    "status": "OPEN"
  }
}
```

### 11. `pix.med.updated`

Enviado quando o status de uma disputa MED muda. É por aqui que você fica sabendo do desfecho, e é a **única** fonte de estado: o `POST .../answer` só registra a sua defesa (que segue para análise fora da API), e a disputa também se move por ação do BACEN e do banco do reclamante.

Reentrega do mesmo status não gera evento novo, e evento atrasado (carimbo do liquidante anterior ao que já registramos) é descartado — o status nunca regride.

**Estrutura do `data`:**

* `medId`: Identificador da disputa (mesmo do `pix.med.opened`).
* `originalEndToEnd`: `endToEndId` da transação PIX em disputa.
* `amount`: Valor disputado.
* `reasonCode`: Motivo reportado.
* `clientAnswerDeadlineIso`: Prazo da sua resposta (o mesmo da abertura).
* `status`: Status atual do MED — vocabulário próprio (`OPEN`, `PENDING_DECISION`, `ACCEPTED`, `REJECTED`, `CANCELED`; ver tabela de status acima).

**Mapeamento do status do liquidante** — o valor cru nunca sai no evento:

| Status do liquidante                          | `data.status`      |
| --------------------------------------------- | ------------------ |
| `under-client-analysis`, `received`           | `OPEN`             |
| `client-analysis-delay`                       | `PENDING_DECISION` |
| `closed-full-refund`, `closed-partial-refund` | `ACCEPTED`         |
| `closed-no-refund`                            | `REJECTED`         |
| `canceled`                                    | `CANCELED`         |

Status desconhecido vira `OPEN`, não desfecho: perder a abertura de uma disputa custa o seu prazo de resposta, receber uma a mais só custa uma consulta.

**Exemplo Completo:**

```json
{
  "id": "evt_med_456",
  "type": "pix.med.updated",
  "occurredAt": "2026-07-24T01:15:03.410Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
    "originalEndToEnd": "E0000000020251229211433912",
    "amount": 150.50,
    "reasonCode": "scam-or-fraud",
    "status": "CANCELED"
  }
}
```

### 12. `pix.med.review.updated`

Enviado a cada passo da **análise da CorpX** sobre uma disputa: defesa recebida, esclarecimento pedido, decisão, retenção e liberação de saldo, bloqueio e liberação da conta, devoluções e encerramento. É o evento que acompanha o `reviewStatus` do [guia de MED](/baas/guias/pagar/med); o `pix.med.updated` segue cobrindo o status do liquidante.

`data` é sempre o **retrato atual** da disputa; `reason` diz o que acabou de acontecer. Não é preciso acumular eventos para saber onde ela está.

**Estrutura do `data`:**

* `medId`, `accountId`: Identificadores da disputa e da conta.
* `reason`: `submitted`, `info_requested`, `decided`, `balance_locked`, `account_blocked`, `balance_unlocked`, `refund_sent`, `refund_completed`, `refund_failed`, `remainder_locked`, `account_unblocked`, `closed`.
* `reviewStatus`: `awaiting_defense`, `pending_review`, `info_requested`, `in_execution`, `awaiting_funds`, `refunded`, `refused`.
* `round`: Rodada de devolução a que o passo pertence (vazio fora da execução).
* `decision`, `decisionMessage`: `accept` ou `refuse` e a justificativa, a partir de `decided`.
* `infoRequest.message`, `infoDueAt`: Pergunta da análise e prazo, em `info_requested`.
* `lockStatus`, `lockedAmount`: Retenção de saldo vigente.
* `refund.amount`, `refund.endToEndId`: A devolução deste evento, em `refund_*`.
* `refundedTotal`, `remaining`, `refundPartial`: Totais da devolução.

**Exemplo Completo:**

```json
{
  "id": "pix-med-review-c40a8974-4b4c-47c5-9d4b-81376e9071c6-refund_completed-1771598551000",
  "type": "pix.med.review.updated",
  "occurredAt": "2026-07-24T01:15:03.410Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
    "accountId": "acc_123456",
    "reason": "refund_completed",
    "reviewStatus": "in_execution",
    "round": 1,
    "decision": "accept",
    "decisionMessage": "Pagador comprovou que não autorizou a transação.",
    "infoRequest": null,
    "infoDueAt": null,
    "lockStatus": "unlocked",
    "lockedAmount": 0,
    "refund": { "amount": 150.50, "endToEndId": "D0000000020260724011503000000001" },
    "refundedTotal": 150.50,
    "remaining": 0,
    "refundPartial": false
  }
}
```

### 13. `transfer.internal.in`

Enviado à conta que **recebe** uma transferência interna entre contas do mesmo ecossistema bancário. Transferências internas são instantâneas e liquidadas no mesmo banco — não trafegam pelo SPI do PIX, portanto não possuem `endToEndId`.

**Estrutura do `data`:**

* `transactionId`: ID da transação no nosso sistema (formato `internal-{uuid}`). Use no `GET /v1/accounts/{accountId}/statement`.
* `amount`: Valor recebido.
* `status`: Sempre `SUCCESS` (transferências internas são atômicas).
* `completedAt`: Data/hora da liquidação.
* `identifier`: Identificador fornecido pelo pagador no `POST /transfers/internal*` (se informado). O mesmo valor chega nas duas pernas (`transfer.internal.out` e `transfer.internal.in`).
* `payerDescription` / `description`: Descrição informada pelo pagador.
* `source`: Dados do pagador — `name`, `taxId`, `providerAccountId` e, quando a conta é gerenciada por nós, `accountId` e `tenantId`.
* `destination`: Dados do recebedor, nos mesmos campos.
* `payer` / `receiver`: as mesmas duas pontas, com `document` no lugar de `taxId`. Só aparecem quando a transferência foi iniciada **fora da API** (app ou console do liquidante). Mantidos por compatibilidade — prefira `source`/`destination`, que chegam nas duas origens.

> **Destino fora da CorpX**
>
> Quando o recebedor é conta de outro banco, `destination` traz `name` e `taxId` (os que você informou na requisição) sem `accountId`/`tenantId`. Nesse caso só existe o `transfer.internal.out`.

> **Transferências de ordem P2P**
>
> Quando o `identifier` é de uma ordem [P2P Cripto](/baas/guias/p2p/webhooks) (`p2p-{orderId}`, `fee-p2p-{orderId}` ou `fee-p2p-{orderId}-r`), o payload ganha `p2pOrderId` e `p2pKind` (`payment`, `fee` ou `fee_refund`), a `description` vira a do extrato (`COMPRA P2P CRIPTO`, `VENDA P2P CRIPTO`, `TAXA INTERMEDIAÇÃO KYC P2P CRIPTO`, …) e a contraparte (`source` no crédito, `destination` no débito, e `payer`/`receiver` quando vierem) fica só com `{ "name": "ORDEM P2P CRIPTO" }`. O mesmo vale para `fee.charged` e `fee.refunded`.

**Exemplo Completo:**

```json
{
  "id": "evt_int_in_001",
  "type": "transfer.internal.in",
  "occurredAt": "2026-04-23T14:21:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "773107de-139e-48d1-9462-f4e88f251891",
  "data": {
    "transactionId": "internal-9d4a5b7c-1234-4abc-9876-abc123456789",
    "amount": 500.00,
    "status": "SUCCESS",
    "completedAt": "2026-04-23T14:21:05.000Z",
    "payerDescription": "Pagamento salário",
    "source": {
      "providerAccountId": "a1b2c3d4-...",
      "tenantId": "tenant-acme",
      "accountId": "e5f6g7h8-...",
      "name": "EMPRESA ORIGEM LTDA",
      "taxId": "12345678000199"
    },
    "destination": {
      "providerAccountId": "b2c3d4e5-...",
      "tenantId": "tenant-acme",
      "accountId": "773107de-139e-48d1-9462-f4e88f251891",
      "name": "MARIA SILVA",
      "taxId": "12345678900"
    }
  }
}
```

### 14. `transfer.internal.out`

Enviado à conta que **envia** uma transferência interna. Mesmo formato do `transfer.internal.in`, com duas diferenças:

* O campo `identifier` **é preenchido** nas duas pernas quando o integrador passou `identifier` no corpo da requisição original (`POST /v1/accounts/{accountId}/transfers/internal*`). Use-o para reconciliar a transferência no seu lado.
* `description` — se o integrador passou `description` na requisição, esse mesmo texto volta aqui (e não o texto padrão `Transferência Interna`).

**Exemplo:**

```json
{
  "id": "evt_int_out_001",
  "type": "transfer.internal.out",
  "occurredAt": "2026-04-23T14:21:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
  "data": {
    "transactionId": "internal-9d4a5b7c-1234-4abc-9876-abc123456789",
    "amount": 500.00,
    "status": "SUCCESS",
    "completedAt": "2026-04-23T14:21:05.000Z",
    "identifier": "int-transfer-12345",
    "description": "Pagamento salário",
    "source": {
      "providerAccountId": "a1b2c3d4-...",
      "tenantId": "tenant-acme",
      "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
      "name": "EMPRESA ORIGEM LTDA",
      "taxId": "12345678000199"
    },
    "destination": {
      "providerAccountId": "b2c3d4e5-...",
      "tenantId": "tenant-acme",
      "accountId": "773107de-139e-48d1-9462-f4e88f251891",
      "name": "MARIA SILVA",
      "taxId": "12345678900"
    }
  }
}
```

> **Como reconciliar a transferência interna**
>
> Ao chamar `POST /v1/accounts/{accountId}/transfers/internal` (ou as variantes `by-document` / `by-bank-account`), envie um `identifier` único seu. A resposta da API traz esse `identifier` junto com o `transactionId`. O webhook `transfer.internal.out` chega depois trazendo o mesmo `identifier` + `transactionId`, permitindo que você feche a transação no seu sistema sem consultar o extrato.

### 15. `pix.out.timeout`

Enviado quando o desfecho da ordem é **indeterminado** ao fim da janela de confirmação: a chamada ao parceiro foi enviada mas a resposta/confirmação final não chegou a tempo (inclui timeout de comunicação na própria chamada de envio). Não é uma falha definitiva — um `pix.out.completed` ou `pix.out.failed` tardio ainda pode chegar depois. Recomendamos verificar o extrato antes de tentar novamente com nova chave de idempotência (re-tentativa com a mesma chave é segura).

**Estrutura do `data`:**

* `paymentId`, `transactionId`, `accountId`, `tenantId`: Identificação da operação.
* `endToEnd`: BACEN E2E quando o partner já tinha emitido.
* `amount` / `currency`: Valor enviado (`BRL`).
* `status`: Sempre `"TIMEOUT"`.
* `errorCode` / `errorReason` / `warning` / `error`: Orientação do que fazer (`confirmation_timeout`).
* `identifier`, `description`, `key`, `payer` / `payee`: quando disponíveis.
* `hold`: Presente quando a ordem ficou retida **no banco liquidante**. Traz `owner: "partner"` e `reason` (`partner_authorization` = fila de autorização interna do liquidante; `partner_risk_analysis` = análise de risco; `partner_unspecified` = retido, sem detalhe da fila). Quando este objeto vem, **não há nada a aprovar do seu lado nem do nosso** — a decisão é do liquidante.
* `partnerStatus` / `partnerStatusId`: Retrato bruto do estado no liquidante, para você anexar em ticket. São valores do liquidante, não do nosso vocabulário canônico: não use em comparação de status.

**Exemplo:**

```json
{
  "id": "evt_pix_out_timeout_001",
  "type": "pix.out.timeout",
  "occurredAt": "2026-05-04T10:42:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "pay_9ccd1869-7593-4feb-9602-e525e818ab8e",
    "transactionId": "162982-pix",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "endToEnd": "E0000000020260504104211",
    "amount": 250.00,
    "currency": "BRL",
    "status": "TIMEOUT",
    "errorCode": "confirmation_timeout",
    "errorReason": "tempo de resposta do parceiro estourou. A chamada para enviar o dinheiro foi enviada com sucesso, mas a confirmação final do status ainda não chegou.",
    "error": "tempo de resposta do parceiro estourou. A chamada para enviar o dinheiro foi enviada com sucesso, mas a confirmação final do status ainda não chegou.",
    "warning": "tempo de resposta do parceiro estourou. A chamada para enviar o dinheiro foi enviada com sucesso, mas a confirmação final do status ainda não chegou.",
    "identifier": "order-12345",
    "partnerStatus": "awaiting-authorization",
    "partnerStatusId": 7,
    "hold": {
      "owner": "partner",
      "reason": "partner_authorization"
    }
  }
}
```

#### Confirmação tardia (`late: true`)

`TIMEOUT` é estado **indeterminado**, não final. Quando a ordem fica retida no liquidante, seguimos consultando por até **7 dias** e, se ele liquidar (ou recusar) nesse período, você recebe o evento terminal correspondente:

* `pix.out.completed` com `late: true` — o dinheiro saiu.
* `pix.out.failed` com `late: true` — o liquidante recusou.

O evento tardio traz o **mesmo `paymentId`** do `pix.out.timeout` que você já recebeu: é a correção daquele desfecho, não um segundo pagamento. Trate-o como o desfecho definitivo da ordem.

Passados os 7 dias sem notícia, nenhum evento novo é enviado e a ordem permanece `TIMEOUT` — o que significa, literalmente, "não sabemos". Confira o extrato (`GET /v1/accounts/{accountId}/statement`) antes de reemitir. Reemissão com a **mesma** `Idempotency-Key` é segura; com chave nova pode gerar pagamento em duplicidade.

### 16. `pix.refund.received`

Enviado quando o **recebedor** de um PIX out devolve o valor por iniciativa própria (sem que tenhamos pedido). Difere de `pix.refund.completed`, que confirma um refund que **nós** disparamos.

**Estrutura do `data`:**

* `transactionId`: ID determinístico da row do refund recebido (`pix-refund-received-{refundEndToEnd}`).
* `refundEndToEnd`: D-code do refund (BACEN).
* `originalEndToEnd`: E-code do PIX out original que está sendo revertido.
* `originalIdentifier`: Identifier do PIX out original (eco do que foi enviado na criação do pagamento), quando disponível.
* `accountId` / `tenantId`: A conta que recebeu o refund.
* `amount`: Valor revertido.
* `description`: Descrição vinda do partner.
* `receivedAt`: Timestamp do refund.
* `payer`: Quem devolveu o valor (contraparte / recebedor original do PIX out): nome, documento, banco, agência, conta.
* `payee`: Quem recebeu o crédito (nossa conta / pagador original do PIX out): nome, documento, banco, agência, conta.
* `status`: Sempre `"SUCCESS"`.

**Exemplo:**

```json
{
  "id": "evt_pix_refund_recv_001",
  "type": "pix.refund.received",
  "occurredAt": "2026-05-04T11:11:43.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "transactionId": "pix-refund-received-D2026050420260504...",
    "refundEndToEnd": "D2026050420260504000000001",
    "originalEndToEnd": "E0000000020260503100000001",
    "originalIdentifier": "client-refund-key-001",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 320.00,
    "description": "Devolução PIX",
    "receivedAt": "2026-05-04T11:11:43.000Z",
    "payer": {
      "name": "João Silva",
      "document": "12345678901",
      "bankCode": "341",
      "bankIspb": "60701190",
      "branch": "0001",
      "accountNumber": "12345-6"
    },
    "payee": {
      "name": "Empresa Acme LTDA",
      "document": "12345678000199",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "accountNumber": "98765-4"
    },
    "status": "SUCCESS"
  }
}
```

### 17. `qrcode.expired`

Enviado quando um QR Code dinâmico expira sem ter sido pago, na hora do `expirationDate` pedido na criação (24 horas depois, quando o campo não foi enviado). No QR com vencimento e no Location confirmado, expira ao fim do dia `dueDate + daysAfterDueDate` (Brasília). O `id` do envelope é `qrcode-expired-{txid}`.

**Campos em `data`:** `qrcodeId`, `identifier`, `accountId`, `tenantId`, `type` (hoje `"dynamic"`, `"due-date"` ou `"location"`; lista extensível, como em `qrcode.paid`), `amount`, `status` (`"EXPIRED"`). Não enviamos `txid` nem `expiredAt`.

```json
{
  "id": "qrcode-expired-txid-qr-123",
  "type": "qrcode.expired",
  "occurredAt": "2026-05-04T12:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "qrcodeId": "txid-qr-123",
    "identifier": "order-12345",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "type": "dynamic",
    "amount": 99.90,
    "status": "EXPIRED"
  }
}
```

### 18. `qrcode.cancelled`

Enviado quando o integrador cancela um QR Code dinâmico via `DELETE /v1/accounts/{accountId}/pix/qr-code?identifier={txid}` antes do pagamento. O `id` do envelope é `qrcode-cancelled-{txid}`.

**Campos em `data`:** `qrcodeId`, `identifier`, `accountId`, `tenantId`, `type` (lista extensível, como em `qrcode.paid`), `status` (`"CANCELLED"`), `reason`, `cancelledBy`. Não enviamos `txid`, `amount` nem `cancelledAt`.

```json
{
  "id": "qrcode-cancelled-txid-qr-123",
  "type": "qrcode.cancelled",
  "occurredAt": "2026-05-04T11:45:30.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "qrcodeId": "txid-qr-123",
    "identifier": "order-12345",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "type": "dynamic",
    "status": "CANCELLED",
    "reason": "user_cancelled",
    "cancelledBy": "integrator"
  }
}
```

### 19. `boleto.paid`

Enviado quando um boleto pago via `POST /v1/accounts/{accountId}/boleto/pay` é confirmado pelo banco emissor.

**Estrutura do `data`:**

* `paymentId`: id canônico do boleto (`bol_{uuid}`) — **mesmo valor** que o `POST /boleto/pay` devolveu. Use este para correlacionar.
* `boletoId`: o mesmo valor de `paymentId`. **Não** enviamos `transactionId`.
* `partnerId`: referência no parceiro (`operationReferenceId`), para suporte/reconciliação.
* `accountId` / `tenantId`: Conta pagadora.
* `amount`: Valor pago.
* `line`: linha digitável / código de barras.
* `status`: Sempre `"SUCCESS"`.

```json
{
  "id": "evt_boleto_paid_001",
  "type": "boleto.paid",
  "occurredAt": "2026-05-04T15:00:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "bol_aabbccdd",
    "boletoId": "bol_aabbccdd",
    "partnerId": "op-ref-99887766",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 1234.50,
    "line": "00190.00009 03450.000004 47018.500003 1 88880000123450",
    "status": "SUCCESS"
  }
}
```

### 20. `boleto.failed`

Enviado quando o banco rejeita o pagamento. `data.error` e `data.errorReason` são a **mesma string** (não um objeto).

```json
{
  "id": "evt_boleto_failed_001",
  "type": "boleto.failed",
  "occurredAt": "2026-05-04T15:00:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "paymentId": "bol_eeffgghh",
    "boletoId": "bol_eeffgghh",
    "partnerId": "op-ref-99887766",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 1234.50,
    "line": "00190.00009 03450.000004 47018.500003 1 88880000123450",
    "status": "FAILED",
    "error": "Boleto vencido — emitir nova cobrança",
    "errorReason": "Boleto vencido — emitir nova cobrança",
    "errorCode": "boleto_expired"
  }
}
```

### 21. `ted.out.requested`

Enviado **imediatamente** após o POST `/v1/accounts/{id}/ted/out` ser aceito. Status `PROCESSING` — TED registrada no liquidante, aguardando janela BACEN para liquidar. Ver [Guia TED](/baas/guias/pagar/ted).

```json
{
  "id": "evt_ted_out_requested_001",
  "type": "ted.out.requested",
  "occurredAt": "2026-05-23T09:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "tedId": "ted-fornecedor-acme-001",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "partnerId": "",
    "amount": 5000.00,
    "destination": {
      "bankCode": "001",
      "branch": "1234",
      "account": "56789",
      "accountType": "CHECKING",
      "taxNumber": "12345678900",
      "holderName": "JOAO DA SILVA"
    },
    "description": "Pagamento de fornecedor NF 12345"
  }
}
```

### 22. `ted.out.confirmed`

Liquidação confirmada pelo liquidante (terminal — sucesso).

```json
{
  "id": "evt_ted_out_confirmed_001",
  "type": "ted.out.confirmed",
  "occurredAt": "2026-05-23T09:32:15.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "tedId": "ted-fornecedor-acme-001",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "partnerId": "fornecedor-acme-001",
    "amount": 5000.00,
    "destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Pagamento de fornecedor NF 12345"
  }
}
```

> **Alias deprecado**: o evento `ted.payment` é disparado em paralelo com `ted.out.confirmed` com o mesmo payload, apenas para compatibilidade com assinaturas legadas. Novos integradores devem assinar **somente** `ted.out.confirmed`. `ted.payment` será removido na v3.0.

### 23. `ted.out.failed`

Liquidação rejeitada/expirada (terminal — falha). `data.errorReason` traz o motivo canônico.

```json
{
  "id": "evt_ted_out_failed_001",
  "type": "ted.out.failed",
  "occurredAt": "2026-05-23T09:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "tedId": "ted-fornecedor-acme-001",
    "tenantId": "tenant-acme",
    "accountId": "acc_123456",
    "partnerId": "fornecedor-acme-001",
    "amount": 5000.00,
    "destination": { "bankCode": "999", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Pagamento de fornecedor NF 12345",
    "errorReason": "invalid_bank_code",
    "error": "invalid_bank_code"
  }
}
```

Possíveis valores de `errorReason`: `invalid_bank_code`, `insufficient_funds`, `outside_banking_hours`, `bank_unreachable`, `limit_exceeded`, ou `timeout aguardando confirmação do parceiro (>48h)` (polling defensivo esgotou).

### 24. `ted.in.received`

Uma TED foi **recebida** na sua conta (originada por terceiro). Inclui `data.payer` com nome, documento, banco (`bankCode`, `bankIspb`, `bankName`), agência e conta do originador — use para conciliar com sua contabilidade. Os dados bancários do originador vêm do extrato do liquidante; na rara hipótese de a linha ainda não constar no momento do aviso, o evento sai só com nome e documento. `data.payee` é a conta que recebeu, como o liquidante a identifica: banco `681` / ISPB `50871921`, agência, conta e titular. Em holder compartilhado por mais de um tenant, cada um recebe o próprio evento com o mesmo `payee`.

```json
{
  "id": "evt_ted_in_received_001",
  "type": "ted.in.received",
  "occurredAt": "2026-05-23T14:15:22.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "transactionId": "abc123def",
    "identifier": "TED-9876",
    "partnerTxId": "abc123def",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 1200.00,
    "description": "Pagamento recebido",
    "receivedAt": "2026-05-23T14:15:22Z",
    "payer": {
      "name": "EMPRESA XYZ LTDA",
      "document": "98765432000110",
      "bankCode": "237",
      "bankIspb": "60746948",
      "bankName": "BANCO BRADESCO S.A.",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    },
    "payee": {
      "name": "SUA EMPRESA LTDA",
      "document": "12345678000195",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "account": "6371893",
      "accountNumber": "6371893"
    }
  }
}
```

> Lembre-se: para que terceiros enviem TED para a sua conta, eles devem usar **banco 681** (liquidante) — ver [Guia TED](/baas/guias/pagar/ted#banco-liquidante-para-receber-ted).

### 25. `policy.violation`

Uma regra de política configurada para a sua conta ou tenant foi violada. O evento cobre todas as seções de política — PIX out, recebimento, QR Code, chaves e estorno — e é enviado tanto quando a operação é **recusada** (`action: "BLOCK"`) quanto quando ela apenas **gera aviso** ou uma ação depois do crédito (`NOTIFY_ONLY`, `ALLOW_AND_NOTIFY`, `AUTO_REFUND`, `LOCK_BALANCE`, `BLOCK_ACCOUNT`). Use `blocked` para saber se a operação foi recusada. Num recebimento `blocked` é sempre `false`.

```json
{
  "id": "evt_policy_violation_001",
  "type": "policy.violation",
  "occurredAt": "2026-05-23T22:41:10.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "phase": "counterparty",
    "action": "BLOCK",
    "blocked": true,
    "paymentId": "pay_9f2c...",
    "accountId": "acc_123456",
    "identifier": "PEDIDO-1234",
    "mode": "KEY",
    "amount": 5000.00,
    "violations": [
      { "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted by policy" }
    ],
    "counterparty": { "document": "12345678900", "name": "FULANO DE TAL" }
  }
}
```

| Campo               | Descrição                                                                                                                                                                                                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phase`             | `edge` (recusa na resposta da requisição, HTTP 422), `counterparty` (após resolver o destinatário, dentro do processamento), `pix_in`, `ted_in`, `internal_in`, `boleto_in` (após o crédito), `med` (disputa recebida levou a taxa de MED acima do teto) ou `dict_lookup` (consulta de chave recusada por limite)                                 |
| `action`            | `BLOCK`, `NOTIFY_ONLY`, `ALLOW_AND_NOTIFY`, `AUTO_REFUND`, `LOCK_BALANCE` ou `BLOCK_ACCOUNT`, conforme a configuração da política                                                                                                                                                                                                                 |
| `blocked`           | `true` quando a operação foi de fato recusada. Sempre `false` num recebimento                                                                                                                                                                                                                                                                     |
| `balanceLocked`     | No recebimento, `true` quando o valor daquele crédito foi travado no liquidante. `false` se a ação foi pedida e não concluiu                                                                                                                                                                                                                      |
| `accountBlocked`    | No recebimento, `true` quando a conta passou a `blocked` por esta violação. `false` se a ação foi pedida e não concluiu                                                                                                                                                                                                                           |
| `mode`              | `KEY`, `BANK_ACCOUNT`, `QRCODE` ou `REFUND` em PIX out; o tipo da operação nas outras seções (`static`/`dynamic` no QR, tipo da chave, método do PIX recebido)                                                                                                                                                                                    |
| `violations[].rule` | Regras de PIX out sem prefixo (`pixOutDisabled`, `cpfCnpjBlacklist`, `sameOwnershipOnly`, `operatingHours`, `allowedPersonTypes`); as demais seções prefixadas (`pixIn.*`, `qrCode.*`, `keys.*`, `refund.*`) ou `dictLookup.*`. `maxAmount` e `nightMaxAmount` de PIX out não são mais emitidos — recusa por valor é `limit_exceeded_transaction` |
| `counterparty`      | O destinatário (PIX out) ou o pagador (PIX in), quando conhecido                                                                                                                                                                                                                                                                                  |

Quando `blocked` é `true` em um PIX out, você também recebe o `pix.out.failed` correspondente, com `errorCode: policy_denied`. São dois eventos com ids distintos: este é o aviso da regra, aquele é o desfecho do pagamento.

Em modo monitor (`NOTIFY_ONLY`) o pagamento segue normalmente e terá o desfecho dele (`pix.out.completed`, por exemplo) — este evento é apenas um aviso de que a transação teria sido recusada se a regra estivesse em `BLOCK`.

#### Violação num recebimento (`phase: "pix_in"`, `"ted_in"`, `"internal_in"` ou `"boleto_in"`)

Um recebimento não pode ser recusado: o liquidante credita a conta e só depois nos avisa. A violação é sempre posterior ao crédito. O payload troca `paymentId` por `transactionId` e a referência do crédito, e acrescenta `refunded`, `balanceLocked` e `accountBlocked`. `refunded` só é `true` na devolução de PIX. `AUTO_REFUND` em TED, transferência interna e boleto avisa e o dinheiro fica.

```json
{
  "phase": "pix_in",
  "action": "AUTO_REFUND",
  "blocked": false,
  "refunded": true,
  "transactionId": "tx_8a1b...",
  "accountId": "acc_123456",
  "endToEnd": "E18236120202607291230abcdef1234",
  "amount": 5000.00,
  "mode": "DICT",
  "violations": [
    { "rule": "pixIn.cpfCnpjBlacklist", "message": "payer document is blacklisted by policy" }
  ],
  "counterparty": { "document": "12345678900", "name": "FULANO DE TAL", "bankCode": "260" }
}
```

O webhook do crédito (`pix.in.completed`, `ted.in.received`, `transfer.internal.in` ou `boleto.charge.settled`) sai antes deste evento. Com `refunded: true`, a devolução de PIX gera em seguida os eventos normais de PIX out (`pix.out.completed` ou `pix.out.failed`). `LOCK_BALANCE` reduz o disponível no liquidante. `BLOCK_ACCOUNT` só corta saída na nossa API. Nenhum dos dois desfaz o crédito, e marcar o caso como ciente não desbloqueia saldo nem reabre a conta.

#### Violação pela taxa de MED (`phase: "med"`)

Disparada quando uma disputa nova recebida contra a conta leva a taxa de MED da janela acima do teto da seção `med`. A única ação é `BLOCK_ACCOUNT`. A referência é o `medId` da disputa; os números da janela vêm no payload para o integrador reconstruir a conta. O `pix.med.opened` dessa mesma disputa sai com `accountBlocked: true`.

```json
{
  "phase": "med",
  "action": "BLOCK_ACCOUNT",
  "blocked": false,
  "accountBlocked": true,
  "balanceLocked": false,
  "refunded": false,
  "accountId": "acc_123456",
  "medId": "med_7f3a...",
  "identifier": "med_7f3a...",
  "windowDays": 30,
  "medCount": 12,
  "criticalMedCount": 4,
  "pixInCount": 800,
  "ratePercent": 1.5,
  "criticalRatePercent": 0.5,
  "violations": [
    { "rule": "med.critical.maxRatePercent", "message": "critical MED rate 0.50% (4 of 800 PIX in) reached the policy limit of 0.30%" }
  ]
}
```

Detalhes das regras e da configuração no guia de [Políticas e Regras](/baas/guias/autenticacao/politicas).

### 26. `boleto.charge.registered`

O boleto emitido foi registrado na base centralizada. `chargeId` é o mesmo id do `POST /v1/accounts/{accountId}/boleto/charge`.

```json
{
  "id": "bankslip-slip-1-registered",
  "type": "boleto.charge.registered",
  "occurredAt": "2026-09-23T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "open",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15"
  }
}
```

### 27. `boleto.charge.registration_failed`

O registro do boleto foi recusado. `statusReason` traz o motivo quando o banco informa.

```json
{
  "id": "bankslip-slip-1-registration_failed",
  "type": "boleto.charge.registration_failed",
  "occurredAt": "2026-09-23T18:06:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "open",
    "registrationCondition": "rejected",
    "statusReason": "pagador inválido",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "",
    "digitableLine": "",
    "dueDate": "2026-10-15"
  }
}
```

### 28. `boleto.charge.settled`

O boleto foi pago. O crédito também aparece no extrato como `BOLETO`.

```json
{
  "id": "bankslip-slip-1-settled",
  "type": "boleto.charge.settled",
  "occurredAt": "2026-10-10T14:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "settled",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15",
    "payment": { "amount": 150.0, "settledAt": "2026-10-10T14:00:00Z" }
  }
}
```

### 29. `boleto.charge.overdue`

Passou do vencimento e o boleto continua em aberto. Não é estado terminal.

```json
{
  "id": "bankslip-slip-1-overdue",
  "type": "boleto.charge.overdue",
  "occurredAt": "2026-10-16T03:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "overdue",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 152.5,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15"
  }
}
```

### 30. `boleto.charge.written_off`

O boleto foi baixado.

```json
{
  "id": "bankslip-slip-1-written_off",
  "type": "boleto.charge.written_off",
  "occurredAt": "2026-10-20T12:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "writtenOff",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15"
  }
}
```

### 31. `boleto.charge.cancelled`

O boleto foi cancelado.

```json
{
  "id": "bankslip-slip-1-cancelled",
  "type": "boleto.charge.cancelled",
  "occurredAt": "2026-10-12T12:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "cancelled",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15"
  }
}
```

### 32. `boleto.charge.expired`

O prazo de pagamento acabou.

```json
{
  "id": "bankslip-slip-1-expired",
  "type": "boleto.charge.expired",
  "occurredAt": "2026-10-20T03:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "expired",
    "registrationCondition": "registered",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "digitableLine": "23793381286000000000300000000400184340000015000",
    "dueDate": "2026-10-15"
  }
}
```

### 33. `boleto.charge.failed`

Reservado no catálogo. Esta versão não envia o evento: falha de registro sai como `boleto.charge.registration_failed`, e falha no cadastro do beneficiário é a resposta **502** do `POST`.

```json
{
  "id": "bankslip-slip-1-failed",
  "type": "boleto.charge.failed",
  "occurredAt": "2026-09-23T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "chargeId": "slip-1",
    "identifier": "pedido-1001",
    "accountId": "acc_123456",
    "status": "open",
    "registrationCondition": "pendingRegistration",
    "nominalAmount": 150.0,
    "updatedAmount": 0,
    "barcode": "",
    "digitableLine": "",
    "dueDate": "2026-10-15"
  }
}
```

### 34. `boleto.charge.batch.completed`

Enviado quando todas as tentativas de emissão de um lote terminam. `status` é
`COMPLETED`, `PARTIAL_FAILED` ou `FAILED`. Isso encerra o processamento do
lote, não o ciclo individual: registro, pagamento, vencimento e expiração dos
boletos emitidos continuam depois.

`statistics` traz `total`, `issued` e `failed`, o retrato terminal das
tentativas de emissão. Pagamento continua depois: consulte o lote para
`statistics.payment` e a conversão atualizada (`paid / issued × 100`).

Assine este evento com `authType: HMAC`. A entrega traz `X-Signature`; valide
o HMAC-SHA256 sobre os bytes brutos do corpo e deduplique pelo `id`.

```json
{
  "id": "bchg-batch-bcb_01J8Y7C8D9E0F1G2H3J4-completed",
  "type": "boleto.charge.batch.completed",
  "occurredAt": "2026-09-24T14:12:40.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "batchId": "bcb_01J8Y7C8D9E0F1G2H3J4",
    "accountId": "acc_123456",
    "status": "PARTIAL_FAILED",
    "statistics": {
      "total": 100,
      "issued": 97,
      "failed": 3
    }
  }
}
```

### 34.1. `boleto.charge.beneficiary.approved`

O liquidante confirmou o cadastro do beneficiário de boleto da conta (ou a reativação de um relacionamento encerrado, com `reactivated: true`). A conta já pode emitir. `operationId` é o da resposta 202 do credenciamento. Os campos comuns aos quatro eventos de beneficiário são `accountId`, `beneficiaryId`, `operation` (`INCLUSION`, `UPDATE`, `STATUS_UPDATE` ou `TERMINATION`), `result` (`CONFIRMED` ou `REJECTED`), `operationId` e `occurredAt`. Veja o [guia de emissão de boleto](/baas/guias/cobranca/boleto-charge#acompanhando-o-beneficiário-por-webhook).

```json
{
  "id": "bchg-beneficiary-d4a1f2b3-6c9e-4a11-9f0d-7e5c1a2b3c4d",
  "type": "boleto.charge.beneficiary.approved",
  "occurredAt": "2026-11-01T15:32:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "accountId": "acc_123456",
    "beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "operation": "INCLUSION",
    "result": "CONFIRMED",
    "operationId": "b3f1a2d4-6c9e-4a11-9f0d-7e5c1a2b3c4d",
    "occurredAt": "2026-11-01T15:32:00Z",
    "identifier": "0000123456",
    "reactivated": false
  }
}
```

### 34.2. `boleto.charge.beneficiary.rejected`

O liquidante recusou uma operação do beneficiário. `operation` diz qual foi recusada; `rejectionCode` e `rejectionReason` vêm do liquidante. Depois de um cadastro (`INCLUSION`) recusado, a emissão responde **502** `boleto_charge_beneficiary_registration_failed` por 24 horas, sem recadastrar; o `POST .../boleto/charge/beneficiary` recadastra na hora.

```json
{
  "id": "bchg-beneficiary-5e2b3c4d-7d0f-4b22-8a1e-8f6d2b3c4d5e",
  "type": "boleto.charge.beneficiary.rejected",
  "occurredAt": "2026-11-01T15:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "accountId": "acc_123456",
    "beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "operation": "INCLUSION",
    "result": "REJECTED",
    "operationId": "b3f1a2d4-6c9e-4a11-9f0d-7e5c1a2b3c4d",
    "occurredAt": "2026-11-01T15:40:00Z",
    "rejectionCode": "BENEFICIARY_DATA_MISMATCH",
    "rejectionReason": "Dados do beneficiário divergentes da base do provedor."
  }
}
```

### 34.3. `boleto.charge.beneficiary.updated`

Atualização aplicada. Em `UPDATE` (dados cadastrais) vem `updatedAt`. Em `STATUS_UPDATE` (elegibilidade) vêm também `previousStatus` e `currentStatus`, com os mesmos valores de `status` do `GET .../beneficiary`.

```json
{
  "id": "bchg-beneficiary-6f3c4d5e-8e1a-4c33-9b2f-9a7e3c4d5e6f",
  "type": "boleto.charge.beneficiary.updated",
  "occurredAt": "2026-11-02T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "accountId": "acc_123456",
    "beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "operation": "STATUS_UPDATE",
    "result": "CONFIRMED",
    "operationId": "c4a2b3e5-7d0f-4b22-8a1e-8f6d2b3c4d5e",
    "occurredAt": "2026-11-02T10:00:00Z",
    "previousStatus": "ELIGIBLE",
    "currentStatus": "UNDER_REVIEW",
    "updatedAt": "2026-11-02T10:00:00Z"
  }
}
```

### 34.4. `boleto.charge.beneficiary.closed`

O relacionamento do beneficiário foi encerrado. A conta não emite novos boletos até ser credenciada de novo. `closedAgreementsCount` é quantos convênios foram fechados e `issuanceBlocked` confirma o bloqueio da emissão.

```json
{
  "id": "bchg-beneficiary-7a4d5e6f-9f2b-4d44-8c3a-0b8f4d5e6f7a",
  "type": "boleto.charge.beneficiary.closed",
  "occurredAt": "2026-11-03T12:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "accountId": "acc_123456",
    "beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "operation": "TERMINATION",
    "result": "CONFIRMED",
    "operationId": "d5b3c4f6-8e1a-4c33-9b2f-9a7e3c4d5e6f",
    "occurredAt": "2026-11-03T12:00:00Z",
    "relationshipStatus": "CLOSED",
    "closedAgreementsCount": 2,
    "issuanceBlocked": true,
    "closedAt": "2026-11-03T12:00:00Z"
  }
}
```

### 35. `identity.verification.completed`

Enviado quando uma verificação de identidade standalone chega a um estado
terminal: `APPROVED`, `FAILED` ou `EXPIRED`. `PENDING` nunca gera este evento.
Como a verificação pertence ao tenant e não a uma conta, o envelope não traz
`accountId`.

Cada entrega inclui `X-Signature`. Valide a assinatura contra os **bytes
brutos** do corpo antes de interpretar o JSON e deduplique pelo `id` do
envelope.

**Campos em `data`:**

* `verificationId`: id retornado por `POST /v1/identity-verifications`;
* `status`: `APPROVED`, `FAILED` ou `EXPIRED`;
* `purpose` e `referenceId`: vínculo exato definido na criação;
* `document`: CPF de 11 dígitos;
* `failureReason`: motivo normalizado em falha/expiração; `null` na aprovação;
* `completedAt`: instante terminal em UTC;
* `consumableUntil`: limite para consumir uma aprovação; omitido nos demais
  estados;
* `method`: `link` (página hospedada) ou `facetec_sdk` (SDK no app);
* `referenceMatch` e `checks`: só em `facetec_sdk`. `checks.liveness` é o
  resultado da prova de vida e `checks.faceMatch.result` o da comparação 1:1
  (`not_performed` quando `referenceMatch` é `none` — a aprovação prova só
  que havia uma pessoa viva, não quem ela é).

```json
{
  "id": "idv-idv_01J8Y7C8D9E0F1G2H3J4-completed",
  "type": "identity.verification.completed",
  "occurredAt": "2026-09-24T14:08:12.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
    "status": "APPROVED",
    "purpose": "password_reset",
    "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
    "document": "12345678909",
    "failureReason": null,
    "completedAt": "2026-09-24T14:08:12.000Z",
    "consumableUntil": "2026-09-24T14:18:12.000Z",
    "method": "facetec_sdk",
    "referenceMatch": "dracma",
    "checks": {
      "liveness": "passed",
      "faceMatch": { "result": "passed", "reference": "dracma" }
    }
  }
}
```

O webhook avisa; ele não consome a prova. Depois de validar o evento, chame
`POST /v1/identity-verifications/{verificationId}/consume` com os mesmos
`purpose` e `referenceId`. O fluxo completo está em
[Verificação de identidade](/baas/guias/apis-adicionais/verificacao-de-identidade).

### 36. `pix.batch.completed`

Enviado quando todos os itens de um [lote de PIX](/baas/guias/pagar/pix-em-lote)
chegaram a um desfecho. `status` é `COMPLETED`, `PARTIAL_FAILED` ou `FAILED`.
Cada item do lote é um PIX out comum e já emitiu o seu próprio
`pix.out.completed`, `pix.out.failed` ou `pix.out.timeout`; este evento é o
fechamento do lote, não substitui os eventos por item.

`statistics` traz contagens (`total`, `completed`, `failed`) e somas em BRL como
string decimal (`totalAmount`, `completedAmount`, `failedAmount`). Para a lista
de itens, `GET .../pix/batches/{batchId}`; para o CSV de correção dos que
falharam, `GET .../items/export?status=failed`; para os comprovantes em ZIP,
`POST .../receipts`.

Assine este evento com `authType: HMAC`. A entrega traz `X-Signature`; valide
o HMAC-SHA256 sobre os bytes brutos do corpo e deduplique pelo `id`.

```json
{
  "id": "pix-batch-pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8-completed",
  "type": "pix.batch.completed",
  "occurredAt": "2026-09-30T13:12:40.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
    "accountId": "acc_123456",
    "status": "PARTIAL_FAILED",
    "statistics": {
      "total": 100,
      "completed": 97,
      "failed": 3,
      "totalAmount": "143685.00",
      "completedAmount": "139380.50",
      "failedAmount": "4304.50"
    }
  }
}
```

### 37. `limit_request.updated`

Pedido de aumento de limite mudou de status. Sai na aprovação (o teto já foi aplicado), na recusa e no cancelamento. Não sai na abertura: isso é `limit_request.created`. Na aprovação também sai `account.limits.updated`, sem ordem garantida entre os dois. `actingDocument` é o CPF ou CNPJ de quem pediu — use-o para avisar a pessoa certa. `approvedLimitBrl` pode ser menor que o pedido quando o analista ajusta o valor, nunca maior. `effectiveAt` null significa que o teto novo já vale. Em pedido com várias operações, `bundleId` identifica o lote e `items` traz o estado e os valores de cada operação.

```json
{
  "id": "lr-lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V-approved",
  "type": "limit_request.updated",
  "occurredAt": "2026-10-02T19:10:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
    "accountId": "acc_123456",
    "status": "approved",
    "operation": "pix_out",
    "window": "daytime",
    "requestedLimitBrl": 50000,
    "approvedLimitBrl": 40000,
    "decisionMessage": "Aprovado parcialmente.",
    "effectiveAt": null,
    "actingDocument": "39053344705",
    "identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21"
  }
}
```

### 38. `limit_request.created`

Pedido de aumento aberto. Sai no INSERT, venha ele da API (`channel: api`, token de integrador) ou do backoffice (`channel: backoffice`, token de usuário do painel). Não sai no replay da mesma `Idempotency-Key`. O `id` do envelope é `lr-{id}-pending_review`.

`data` tem o mesmo shape de `limit_request.updated`, mais `currentLimitBrl` (teto efetivo na abertura, inclusive o cadastro anterior; `0` só se a janela estava aberta), `justification` e `channel`. Em lote, `bundleId` e `items` trazem todas as operações abertas juntas.

Assinatura com lista vazia recebe o evento. Lista explícita só recebe se `limit_request.created` estiver nela. Deduplique pelo `id`.

```json
{
  "id": "lr-lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V-pending_review",
  "type": "limit_request.created",
  "occurredAt": "2026-10-02T18:00:01.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
    "accountId": "acc_123456",
    "status": "pending_review",
    "operation": "pix_out",
    "window": "daytime",
    "requestedLimitBrl": 50000,
    "approvedLimitBrl": null,
    "decisionMessage": null,
    "effectiveAt": null,
    "actingDocument": "39053344705",
    "identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
    "currentLimitBrl": 20000,
    "justification": "Folha de pagamento do mês.",
    "channel": "api"
  }
}
```

| Campo             | Significado                                   |
| ----------------- | --------------------------------------------- |
| `currentLimitBrl` | Teto efetivo da janela quando o pedido abriu. |
| `justification`   | Texto de quem pediu, até 500 caracteres.      |
| `channel`         | `api` ou `backoffice`.                        |

### 39. `account.limits.updated`

Teto da conta ou de um operador mudou de verdade. Sai depois de PATCH de staff, PATCH da credencial interna, aprovação de pedido (com as janelas materializadas do cadastro anterior) e PUT/DELETE de teto de operador.

Não sai quando muda o padrão do tenant ou o global, nem quando um afrouxamento de operador já agendado (6 h) passa a valer: o evento do agendamento já trouxe `effectiveAt`.

O `id` do envelope é o id do evento de auditoria. O retry não abre outra entrega. Na aprovação ele convive com `limit_request.updated`, sem ordem. Deduplique pelo `id` e, se o valor importar, releia `GET /limits/available`.

```json
{
  "id": "alev_01J9XQ9LIMITAUDIT0001",
  "type": "account.limits.updated",
  "occurredAt": "2026-10-02T19:10:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "accountId": "acc_123456",
    "subject": { "type": "account" },
    "source": "limit_request",
    "limitRequestId": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
    "changes": [
      {
        "operation": "pix_out",
        "window": "daytime",
        "beforeBrl": 20000,
        "afterBrl": 40000,
        "effectiveAt": null,
        "materializedFromLegacy": false
      },
      {
        "operation": "pix_out",
        "window": "nighttime",
        "beforeBrl": 0,
        "afterBrl": 5000,
        "effectiveAt": null,
        "materializedFromLegacy": true
      }
    ]
  }
}
```

| Campo                    | Significado                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `subject.type`           | `account` ou `operator`. No operador, `subject.document` é o CPF.         |
| `source`                 | `staff`, `internal`, `limit_request` ou `owner`.                          |
| `limitRequestId`         | Só quando a mudança veio de um pedido.                                    |
| `changes[].window`       | `single_transfer`, `daytime`, `nighttime` ou `monthly`.                   |
| `beforeBrl` / `afterBrl` | Teto próprio antes e depois. `0` no antes é célula que não existia.       |
| `effectiveAt`            | `null` quando já vale. Preenchido quando a subida de operador espera 6 h. |
| `materializedFromLegacy` | `true` quando a janela foi copiada do cadastro anterior na mesma escrita. |

### Eventos de Pix Automático

Os eventos `pix.automatic.*` saem da conta recebedora da recorrência. `recurrenceId` é o UUID devolvido no `POST /v1/accounts/{accountId}/pix/automatic/recurrences` (ou na emissão do QR composto); `recurrenceIdentifier` é o identificador `RR…`/`RN…` atribuído no arranjo Pix e aparece assim que é conhecido. O `id` do envelope é determinístico por recorrência, evento e status: deduplique por ele. Guia completo em [Pix Automático](/baas/guias/pix-automatico/visao-geral).

| `data.status`                                                                                                                                 | Onde aparece                          |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `awaiting_authorization`, `authorization_received`, `authorized`, `rejected`, `request_failed`, `authorization_failed`, `canceled`, `expired` | Recorrência                           |
| `created`, `received`, `awaiting_confirmation`, `confirmed`, `rejected`, `confirmation_failed`, `settled`, `canceled`, `expired`              | Agendamento                           |
| `balance_reserved`, `insufficient_balance`, `settled`, `settled_with_error`, `not_settled`, `not_settled_with_error`                          | `data.settlementStatus` da liquidação |

### 40. `pix.automatic.recurrence.authorized`

O pagador autorizou a recorrência no app do banco dele. A partir daqui você pode agendar cobranças.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.authorized-authorized",
  "type": "pix.automatic.recurrence.authorized",
  "occurredAt": "2026-11-03T14:02:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "status": "authorized",
    "frequency": "monthly",
    "occurredAt": "2026-11-03T14:02:11Z"
  }
}
```

### 41. `pix.automatic.recurrence.rejected`

O pagador ou o banco dele recusou a recorrência. `rejectionReason` vem quando o banco informa o motivo.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.rejected-rejected",
  "type": "pix.automatic.recurrence.rejected",
  "occurredAt": "2026-11-03T14:02:11.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "status": "rejected",
    "frequency": "monthly",
    "rejectionReason": "payer_rejected",
    "occurredAt": "2026-11-03T14:02:11Z"
  }
}
```

### 42. `pix.automatic.recurrence.expired`

O pedido de autorização expirou sem resposta do pagador, ou a recorrência foi cancelada. `data.status` diz qual dos dois (`expired` ou `canceled`).

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.expired-expired",
  "type": "pix.automatic.recurrence.expired",
  "occurredAt": "2026-11-10T03:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "accountId": "acc_123456",
    "status": "expired",
    "frequency": "monthly",
    "occurredAt": "2026-11-10T03:00:00Z"
  }
}
```

### 43. `pix.automatic.recurrence.failed`

O pedido de autorização falhou antes de chegar ao pagador (`request_failed`) ou na confirmação da autorização (`authorization_failed`). Revise os dados do pagador e crie uma nova recorrência.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.failed-request_failed",
  "type": "pix.automatic.recurrence.failed",
  "occurredAt": "2026-11-03T14:00:40.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "accountId": "acc_123456",
    "status": "request_failed",
    "frequency": "monthly",
    "occurredAt": "2026-11-03T14:00:40Z"
  }
}
```

### 44. `pix.automatic.scheduling.confirmed`

O banco do pagador confirmou o agendamento da cobrança. `schedulingId` é o id do `POST .../recurrences/{recurrenceId}/schedulings`.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.confirmed-E5087192120261123100000000000001-confirmed",
  "type": "pix.automatic.scheduling.confirmed",
  "occurredAt": "2026-11-21T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
    "endToEndId": "E5087192120261123100000000000001",
    "dueDate": "2026-11-25",
    "amount": 149.9,
    "status": "confirmed",
    "purpose": "scheduling",
    "occurredAt": "2026-11-21T10:00:00Z"
  }
}
```

### 45. `pix.automatic.scheduling.rejected`

O banco do pagador recusou o agendamento. `errorCode` e `errorMessage` vêm quando informados.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.rejected-E5087192120261123100000000000001-rejected",
  "type": "pix.automatic.scheduling.rejected",
  "occurredAt": "2026-11-21T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "accountId": "acc_123456",
    "schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
    "endToEndId": "E5087192120261123100000000000001",
    "dueDate": "2026-11-25",
    "amount": 149.9,
    "status": "rejected",
    "errorCode": "AM05",
    "errorMessage": "Cobrança duplicada no ciclo",
    "occurredAt": "2026-11-21T10:00:00Z"
  }
}
```

### 46. `pix.automatic.scheduling.failed`

O agendamento não foi confirmado: o banco do pagador não respondeu no prazo (`expired`) ou a confirmação falhou (`confirmation_failed`). O payload é o mesmo de `pix.automatic.scheduling.rejected`.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.failed-E5087192120261123100000000000001-expired",
  "type": "pix.automatic.scheduling.failed",
  "occurredAt": "2026-11-24T03:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
    "endToEndId": "E5087192120261123100000000000001",
    "dueDate": "2026-11-25",
    "amount": 149.9,
    "status": "expired",
    "purpose": "scheduling",
    "occurredAt": "2026-11-24T03:00:00Z"
  }
}
```

### 47. `pix.automatic.settlement.completed`

A cobrança agendada foi liquidada na sua conta. `settlementStatus` é `settled` ou `settled_with_error`. O crédito em conta também gera `pix.in.completed` com o mesmo `endToEndId`; não some os dois. `purpose` é `retry` quando a liquidação veio de uma retentativa.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-settlement.completed-E5087192120261123100000000000001-settled",
  "type": "pix.automatic.settlement.completed",
  "occurredAt": "2026-11-25T09:12:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
    "settlementId": "5a2c9e10-8b7d-4f0e-a1c3-6d2b9f4e7a01",
    "endToEndId": "E5087192120261123100000000000001",
    "dueDate": "2026-11-25",
    "amount": 149.9,
    "status": "settled",
    "settlementStatus": "settled",
    "purpose": "scheduling",
    "occurredAt": "2026-11-25T09:12:00Z"
  }
}
```

### 48. `pix.automatic.settlement.failed`

A cobrança não foi liquidada. `settlementStatus` é `insufficient_balance`, `not_settled` ou `not_settled_with_error`. Use `settlementId` para consultar as datas de retentativa (`GET .../settlements/{settlementId}/retry-dates`) e solicitar a retentativa. O payload é o mesmo de `pix.automatic.settlement.completed`.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-settlement.failed-E5087192120261123100000000000001-insufficient_balance",
  "type": "pix.automatic.settlement.failed",
  "occurredAt": "2026-11-25T09:12:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
    "settlementId": "5a2c9e10-8b7d-4f0e-a1c3-6d2b9f4e7a01",
    "endToEndId": "E5087192120261123100000000000001",
    "dueDate": "2026-11-25",
    "amount": 149.9,
    "status": "confirmed",
    "settlementStatus": "insufficient_balance",
    "purpose": "scheduling",
    "occurredAt": "2026-11-25T09:12:00Z"
  }
}
```

### 49. `pix.automatic.qrcode.paid`

O QR composto (cobrança imediata ou com vencimento + autorização da recorrência) foi pago. O pagamento também gera `pix.in.completed`; este evento existe para você ligar o pagamento à recorrência, que segue para autorização e depois emite `pix.automatic.recurrence.*`.

```json
{
  "id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-qrcode.paid-E0000000020261103140000000000001",
  "type": "pix.automatic.qrcode.paid",
  "occurredAt": "2026-11-03T14:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "acc_123456",
  "data": {
    "recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
    "recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
    "accountId": "acc_123456",
    "status": "awaiting_authorization",
    "qrIdentifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "endToEndId": "E0000000020261103140000000000001",
    "amount": 49.9,
    "paidAt": "2026-11-03T14:00:00Z"
  }
}
```

## Boas Práticas

* **Idempotência**: Sua aplicação deve estar preparada para receber o mesmo webhook mais de uma vez. Utilize o `id` do envelope para evitar processamento duplicado.
* **Resposta Rápida**: Retorne um status `200 OK` assim que receber o webhook e processe a lógica de negócio de forma assíncrona para evitar timeouts.
* **Validação de Timestamp**: Verifique se o `occurredAt` não é muito antigo (recomendamos uma tolerância de 5 minutos) para prevenir ataques de replay.