> This page is for BaaS.

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

# Webhooks

Webhooks are notifications sent by our API to your registered URL whenever a relevant event occurs (e.g., a PIX is received or a payment is completed).

## Webhook Configuration

How you create and maintain subscriptions depends on your product:

#### BaaS (tenant)

You have two equivalent, always-in-sync paths:

* **API** — `POST /v1/webhooks` and the other routes described on this page. This is how you automate the setup alongside the rest of your deployment.
* **Integrator Portal** — besides creating and editing subscriptions, this is where you **run day-to-day operations**: resend failed deliveries, debug errors (HTTP status and body returned by your endpoint), browse the **delivery history** of every event and rotate the HMAC key without interrupting the flow.

Use the API to provision and the Portal to operate and investigate.

#### Internet Banking (account)

Configuration is **API only**: there is no Integrator Portal for account
credentials. Create the subscription with `POST /v1/webhooks` passing
your account's `accountId`, sign the request with JWS like any other
call, and manage redeliveries and history through the delivery routes
(`GET /v1/webhooks/{subscriptionId}/deliveries` and `POST .../deliveries/{deliveryId}/retry`).

The step-by-step, with the events available to the account and the
complete HMAC verification example, is in
[Account webhooks (Internet Banking)](/ib/guias/conta/webhooks).

## List Available Events

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

**Response** (array of `{ event, description }`; illustrative excerpt):

```json
[
  { "event": "pix.in.completed", "description": "PIX received successfully" },
  { "event": "pix.out.completed", "description": "PIX sent successfully" },
  { "event": "accreditation.pf.created", "description": "PF accreditation created (async confirmation of POST)" },
  { "event": "accreditation.pj.created", "description": "PJ accreditation created (async confirmation of POST)" },
  { "event": "accreditation.biometry.link.created", "description": "Facial capture link issued (Unico flow; per person)" },
  { "event": "accreditation.acceptance.link.created", "description": "Terms acceptance link issued (per person; only in flows enabled on request)" },
  { "event": "accreditation.consent.link.created", "description": "Authorization link issued — CPF already has an account (per person)" },
  { "event": "accreditation.updated", "description": "Accreditation status transition" },
  { "event": "accreditation.active", "description": "Account ready to operate — accountId available" },
  { "event": "accreditation.failed", "description": "Accreditation ended without opening an account" },
  { "event": "account.shared_access.granted", "description": "Another tenant started operating an account you already operated" },
  { "event": "boleto.charge.batch.completed", "description": "Boleto Charge batch finished every issuance attempt" },
  { "event": "pix.batch.completed", "description": "PIX batch finished with success and failure statistics (each item also emits pix.out.*)" },
  { "event": "identity.verification.completed", "description": "Standalone identity verification completed" },
  { "event": "policy.violation", "description": "A policy rule was violated — operation rejected (BLOCK), merely reported (NOTIFY_ONLY / ALLOW_AND_NOTIFY), PIX refunded (AUTO_REFUND), amount locked (LOCK_BALANCE), or cash-out blocked (BLOCK_ACCOUNT)" },
  { "event": "limit_request.created", "description": "A limit-increase request was opened (not sent again on Idempotency-Key replay)" },
  { "event": "limit_request.updated", "description": "A limit-increase request changed status (approved, refused or cancelled)" },
  { "event": "account.limits.updated", "description": "An account or operator ceiling changed. Does not include a tenant default or an already scheduled relaxation taking effect" }
]
```

The full list also includes PIX out/refund/MED, QR Code, boleto, TED, internal transfers, and fees. Onboarding events are documented in [Onboarding Webhooks](/baas/guias/abertura-de-contas/webhooks).

## Receiving Flow

1. An event occurs on our platform.
2. We send a `POST` request to the registered URLs.
3. Your application must process the notification and return a `2xx` status.

### Configuration Flexibility

Our webhook infrastructure supports various delivery methods:

* **Grouping**: You can receive multiple event types (e.g., `pix.in.completed` and `pix.out.completed`) at the same URL.
* **Segregation**: You can configure different URLs for each event type.
* **Redundancy**: We can send the same event to multiple independent URLs simultaneously.
* **Per-account scoping**: a subscription can receive only one account's events — see below.

### Per-account subscriptions (`accountId`)

By default a subscription belongs to the **tenant**: it receives events from all of your accounts. Passing `accountId` at creation time makes it receive **only** that account's events:

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

The field comes back in `GET /v1/webhooks` (`accountId: null` for tenant-wide subscriptions).

Rules worth knowing before you use it:

* **It is a filter, not extra routing.** A subscription with `accountId` stops receiving the other accounts' events. If you want everything in one place and a slice in another, create two subscriptions.
* **It cannot be edited.** `accountId` is only accepted at creation. Changing the account of a live subscription would silently redirect one account's event stream to the endpoint configured for another — creating a new subscription is explicit and leaves the old one auditable.
* **A credential restricted to accounts must provide it.** If the credential only reaches a subset of accounts (the case for delegated credentials), omitting `accountId` returns **422** `account_id_required`, and pointing at an account outside the subset returns **403** `forbidden`. Without this, a single-account credential could create a subscription for another account's movement and read everything over the webhook, bypassing the control the read routes apply.
* **An account from another tenant** returns **404** `account_not_found`.
* **Events with no account** (accreditation events, before the account exists) are only delivered to tenant-wide subscriptions.
* **The filter also applies at delivery time.** A subscription with `accountId` does not receive other accounts' events, even when the tenant has another subscription for the same event type. The envelope `accountId` is the account where the event happened.

## Security (Destination Authentication)

When creating or updating a webhook subscription, you can choose how our delivery infrastructure authenticates requests to your endpoint. The authentication method is configured per subscription via the API or dashboard.

### Available Authentication Methods

| Method               | `authType` value | Description                                                                                                                     |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **HMAC Signature**   | `HMAC`           | Signs each request body with your secret using HMAC-SHA256. The signature is sent in the `X-Signature` header. **Recommended.** |
| **Platform default** | `NONE`           | No key of yours. Deliveries are still signed, but with our infrastructure's own signature, which you do not control.            |

You configure the method when creating or updating a subscription, via the API or the **Integrator Portal** (**Webhooks > Edit Subscription**).

### Rotating or removing the key

The secret is **never returned** in any response — the subscription only tells
you `hmacSecretSet: true|false`. Because of that:

* **Omitting `secret`** on a `PUT` keeps the current key. This is what lets you
  change only the URL without losing the signature.
* **Sending `secret`** replaces the key (rotation).
* **Sending `authType: "NONE"`** deletes the key and stops signing with it. This
  is the only way to turn it off.

Any other `authType` value is rejected with `400 unsupported_auth_type`.

---

### HMAC Signature Verification

When `authType` is set to `HMAC`, each request includes an **`X-Signature`** header containing the HMAC-SHA256 of the raw request body as **standard Base64, with padding**, computed using your `secret` as the key.

**Formula:**

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

Compare the computed value with the `X-Signature` header. If they match, the request is authentic.

> **Warning**
>
> Always use the **raw request body bytes** for verification, not a re-parsed/re-serialized version. Re-serializing JSON may change field order or whitespace, which will invalidate the signature.

#### Verification Examples

**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))
}
```

---

### Informational Headers

In addition to the authentication headers above, our delivery infrastructure adds the following informational headers to every request:

| Header                     | Description                                                    |
| -------------------------- | -------------------------------------------------------------- |
| `x-hookdeck-event-id`      | Delivery event ID (useful for debugging and support requests). |
| `x-hookdeck-request-id`    | Original request ID.                                           |
| `x-hookdeck-attempt-count` | Delivery attempt number (1 for the first attempt).             |

These headers are informational and do not need to be validated.

### IP Whitelist

To increase the security of your integration, we recommend that your destination server validates the source IP address of incoming requests. Only accept notifications from our infrastructure's official IPs:

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

We suggest adding these addresses to a **whitelist** in your firewall or web server.

## Retries

If your application returns an error (status other than 2xx) or a timeout occurs, our system will attempt to resend the notification following an exponential backoff strategy:

* Attempts: Up to 6 times.
* Intervals: Progressively increasing.

After exhausting all attempts, the delivery stays at `status: failed`. You can request a manual retry of that specific delivery.

`GET /v1/webhooks/{subscriptionId}/deliveries` returns the result **at your endpoint**, not the acceptance by our delivery network:

| `status`         | meaning                                                                |
| ---------------- | ---------------------------------------------------------------------- |
| `pending`        | accepted for delivery, no attempt yet                                  |
| `retrying`       | the last attempt failed and another one is scheduled (`nextAttemptAt`) |
| `delivered`      | your endpoint answered 2xx (`responseStatus`)                          |
| `failed`         | attempts are exhausted                                                 |
| `paused`         | the subscription is paused                                             |
| `not_dispatched` | the event was never forwarded                                          |

`dispatchStatus` is the previous step (`success` = forwarded, `exhausted` = it never left). That is what `status` used to mean. The filter `status=success` is still accepted and means `delivered`; `exhausted` means `not_dispatched`.

## Retrying a Delivery

To resend a failed delivery, use the per-delivery retry endpoint, passing the
`subscriptionId` and `deliveryId` (both visible in the subscription's delivery
list):

**Request Example:**

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

The API queues a new delivery attempt for that `deliveryId`. If a burst of retries hits the delivery network's rate limit, the response is **429** `rate_limited` with a `Retry-After` header — wait and try again. That is not a failed delivery.

## Notification Format

All notifications follow a standard envelope format. The specific content of each event resides in the `data` object.

### Standard Envelope

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

> **Amounts are always BRL**
>
> Monetary values (`amount`, `paidAmount`, etc.) are always in **BRL**. Decimals use a point (`150.50`), never a comma. PIX-out events (`pix.out.completed`, `pix.out.failed`, `pix.out.timeout`, and `pix.refund.*` from the same flow) include `data.currency: "BRL"`. Other events may omit the field — the amount is still in reais.

> **HTTP envelope vs. portal JSON**
>
> The POST to your URL is the **envelope** (`id`, `type`, `occurredAt`, `schemaVersion`, `environment`, `tenantId`, `accountId`, `data`). In the integrator portal, the "webhook delivered" JSON shows only the `data` object (sometimes labeled `deliveredData`) — that is not the HTTP body.

### Common fields inside `data`

A handful of fields appear in **every** event type that represents a ledger entry (PIX IN/OUT, refund, QR paid, internal transfer, fee). They are the recommended way to correlate webhooks with other API endpoints:

| Field                     | Description                                                                                                                                                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId`           | Transaction identifier in the format used by our API. Matches what's returned by `GET /v1/accounts/{accountId}/statement` and by the synchronous response of the endpoint that originated the transaction. Use it to fetch the transaction on our APIs. |
| `coreId`                  | UUID of the ledger line at the banking partner's core. Same value exposed in the `coreId` field of the statement; remains stable across webhook and async statement sync. Use it to reconcile with partner exports.                                     |
| `endToEnd` / `endToEndId` | Central Bank PIX E2E ID (PIX events only).                                                                                                                                                                                                              |
| `status`                  | Transaction state. Standardized vocabulary (see table below).                                                                                                                                                                                           |

The first three fields can coexist in the same payload. If only one is present it means the other isn't relevant for that event type (e.g., internal transfers carry `transactionId` + `coreId` but not `endToEnd`).

### `data.status` values

The `status` field uses a **standardized** vocabulary across all events:

| Status      | Meaning                                                                                                                                               | Events                                                                                                                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`   | Operation completed successfully; balance debited/credited.                                                                                           | `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`    | Operation failed. Balance **was not** moved (or was returned). Check `data.error` for details.                                                        | `pix.out.failed`, `pix.refund.failed`, `boleto.failed`                                                                                                                                               |
| `TIMEOUT`   | Partner call was sent successfully but response timed out. Check the statement before retrying with a new idempotency key.                            | `pix.out.timeout`                                                                                                                                                                                    |
| `EXPIRED`   | Dynamic QR Code expired without being paid by the `expirationDate` requested at creation (24 hours when the field was omitted).                       | `qrcode.expired`                                                                                                                                                                                     |
| `CANCELLED` | Dynamic QR Code cancelled by an explicit integrator call (`DELETE /v1/accounts/{accountId}/pix/qr-code?identifier=...`).                              | `qrcode.cancelled`                                                                                                                                                                                   |
| `REVERSED`  | A previously completed PIX IN that has been reversed (e.g., full chargeback). Appears when late reconciliation overrides an already-delivered PIX IN. | `pix.in.completed` (rare, post-reconciliation)                                                                                                                                                       |

For MED (dispute) events, `status` uses its **own** vocabulary:

| Status             | Meaning                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `OPEN`             | Dispute opened by the claimant, within the 48-hour window for your response.                                 |
| `PENDING_DECISION` | Your response deadline has passed — the dispute is still alive, but the decision is no longer in your hands. |
| `ACCEPTED`         | Dispute accepted — funds returned (fully or partially).                                                      |
| `REJECTED`         | Dispute rejected — funds stay with the payee.                                                                |
| `CANCELED`         | Dispute canceled by whoever filed it.                                                                        |

Events: `pix.med.opened`, `pix.med.updated`.

This `status` is the state **at the instant of the event**, and in that it is
reliable: it is the settlement bank's own notification. That is why it does not
exist in `GET /v1/accounts/{id}/pix/med` — there it would be a stored value,
with no lookup to confirm it. If you need to track the state of a dispute,
accumulate these events: they are the only source.

> **\`status\` guarantee**
>
> `status` is **always present** in events that represent a ledger entry. If you receive a webhook missing the field (or with an empty value), it's a purely informational event (e.g., `account.balance_updated`) — in that case use the `type` field itself to determine semantics.

### Date and time format

Date/time fields use **ISO 8601 / RFC 3339 with an explicit offset** — read the offset, don't assume. **Webhooks** (envelope `occurredAt` and fields inside `data` such as `receivedAt`, `completedAt`, `initiatedAt`, `chargedAt`, `openedAt`) are always **UTC (`Z`)**. In **REST** responses, "our-side" fields (`createdAt`, `updatedAt`, `reconciledAt`, `fetchedAt`, balance) are UTC (`Z`) too; the **transaction time** in the statement and lookups — `timestamp` (`/statement`, `/pix/transactions`) and `occurredAt` (`/pix/payments/lookup`, boleto) — is in **São Paulo time (`-03:00`)**.

Examples:

```text
2026-04-29T23:53:55.001Z         ← with milliseconds
2026-04-29T23:53:49.328720Z      ← with microseconds
2026-04-30T18:04:36Z             ← no fractional seconds
```

We **never** emit timestamps in Brazilian local time (BRT) nor "naive" timestamps (without timezone indicator). If you ever receive a date field without the `Z` suffix, treat it as a bug and report it — we will normalize as soon as we identify the source.

---

## Event Types and Contents (`data`)

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

Sent when a PIX is successfully received (inbound) into the account.

**Fields always present in `data`:**

* `transactionId`: Ledger transaction ID (the settlement-bank operation id when available; otherwise `pix-in-{endToEnd}`). Matches `GET /v1/accounts/{accountId}/statement`. The envelope `id` is `pix-in-{endToEnd}`.
* `endToEnd`: Unique transaction ID at the Central Bank.
* `accountId` / `tenantId`: repeated inside `data` (they are also on the envelope).
* `amount`: Transaction amount in reais.
* `status`: `"SUCCESS"`.
* `method`: How the payer started the PIX — `STATIC_QR_CODE`, `DYNAMIC_QR_CODE`, `DICT` (PIX key) or `MANUAL` (bank details).
* `receivedAt`: Timestamp of receipt (RFC 3339 UTC).

**Conditional fields:**

* `identifier`: When the credit came from a QR Code, this is the txid of the QR that was paid — use it to reconcile with the QR you created.
* `description`: Description from the settlement bank (may be an empty string).
* `payer`: Sender. Only keys with a value are included: `name`, `document`, `bankCode`, `bankIspb`, `branch`, `account` / `accountNumber` (same value; `accountNumber` is a compatibility alias).
* `payee`: Receiver (your account). Same keys, plus `pixKey` when available. Omitted if the settlement bank sent no payee data.

This event does **not** send `reconciliationId`.

**Full Example:**

```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": "pix-in-E0000000020251229211433912",
    "endToEnd": "E0000000020251229211433912",
    "accountId": "acc_123456",
    "tenantId": "tenant-acme",
    "amount": 150.50,
    "description": "",
    "identifier": "SEV798c4a1f4b2e4d9c8a1b2c3d4",
    "method": "STATIC_QR_CODE",
    "status": "SUCCESS",
    "receivedAt": "2025-12-29T21:14:33.900Z",
    "payer": {
      "name": "John Smith",
      "document": "12345678900",
      "bankCode": "001",
      "bankIspb": "00000000",
      "branch": "0001",
      "account": "12345-6",
      "accountNumber": "12345-6"
    },
    "payee": {
      "name": "Test Company",
      "document": "12345678000199",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "account": "98765-4",
      "accountNumber": "98765-4"
    }
  }
}
```

### 2. `qrcode.paid`

Sent when a QR Code generated by you is paid. For the same credit you also receive [`pix.in.completed`](#1-pixincompleted) — this event is the QR-specific confirmation (`identifier` / `qrcodeId`).

**Fields always present in `data`:**

* `qrcodeId`: Internal QR Code ID (for a static QR this is the same as `identifier`).
* `identifier`: txid (identifier) of the QR Code you created.
* `accountId` / `tenantId`: Account that owns the charge.
* `type`: today `"static"`, `"dynamic"`, `"due-date"` or `"location"`. The list is extensible and may gain values: do not reject the event on an unknown `type`.
* `amount`: Amount paid. For due-date and Location QR codes this already includes any discount, interest or penalty.
* `endToEnd`: Unique transaction ID at the Central Bank.
* `transactionId`: Settlement-bank transaction ID, when available.
* `status`: `"SUCCESS"`.
* `receivedAt`: Timestamp of receipt (RFC 3339 UTC).

**Conditional fields:**

* `payer`: Payer. Dynamic QR typically carries `name` and `document`; static QR may also include `bankCode`, `bankIspb`, `branch`, `accountNumber`.
* `payee`: Receiver (your account). Present on static QR when the settlement bank sent those fields.

This event does **not** send `reconciliationId`.

**Full Example:**

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

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

Sent when an outbound PIX transfer is completed successfully.

The POST to your URL is the **envelope** (`id`, `type`, `occurredAt`, `schemaVersion`, `environment`, `tenantId`, `accountId`, `data`). In the integrator portal, the "webhook delivered" JSON shows only the `data` object (sometimes labeled `deliveredData`) — that is not the HTTP body.

**Fields always present in `data`:**

* `paymentId`: Order ID (same as the `202` response of the async POST). The envelope `id` is `pix-out-{paymentId}`.
* `tenantId`, `accountId`: repeated inside `data` (they are also on the envelope).
* `status`: `"SUCCESS"`.
* `endToEnd`: BACEN E2E ID (empty string if the settlement bank has not issued one yet).
* `transactionId`: Settlement-bank transaction ID, when available.
* `amount`: Amount in reais.
* `currency`: always `"BRL"`.
* `description`: Description sent on the POST (may be an empty string).
* `identifier`: Your reconciliation key.
* `originalTransactionId`: Original transaction ID on refunds; empty string on a regular PIX out.
* `initiatedAt` / `completedAt`: RFC 3339 UTC (`Z`), with fractional seconds (up to nanoseconds).

**Conditional fields:**

* `key`: `{ "type", "key" }` when the transfer was sent to a PIX key.
* `payee`: Destination. Only keys with a value are included: `name`, `document`, `bankCode`, `bankIspb`, `branch`, `accountNumber`, `pixKey`, `accountType`.
* `payer`: Origin account. Present only when the settlement-bank webhook carried those fields — do not assume it always arrives.
* `late`: `true` only when confirmation arrived **after** a [`pix.out.timeout`](#13-pixouttimeout) for the same `paymentId`. Absent in the normal case. See [Late confirmation](#late-confirmation-late-true).

This event does **not** send `reconciliationId`, `method`, or a `payment` object.

**Full Example:**

```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": "Supplier payment",
    "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`

Sent when an outbound PIX transfer fails **definitively** — the banking partner rejected the operation (insufficient funds, invalid key, anti-fraud, BACEN rejection etc.) and no balance was moved (or it was returned).

> **Terminal event**
>
> `pix.out.failed` is terminal: once received, no later `pix.out.completed` will arrive for the same order. **Uncertainty** scenarios (e.g. communication timeout with the partner, outcome unconfirmed) emit [`pix.out.timeout`](#13-pixouttimeout) — never `pix.out.failed`.

`data` uses the **same fields** as [`pix.out.completed`](#3-pixoutcompleted), plus:

* `status`: `"FAILED"`.
* `error` / `errorCode` / `errorReason`: rejection reason (`error` is the friendly alias).
* `partner`: raw settlement-bank error, when available.
* `late`: `true` only when the rejection arrived **after** a [`pix.out.timeout`](#13-pixouttimeout) for the same `paymentId`. See [Late confirmation](#late-confirmation-late-true).

This event does **not** send `reconciliationId`.

**Full Example:**

```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": "Supplier payment",
    "identifier": "transfer-002",
    "originalTransactionId": "",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z",
    "error": "insufficient balance",
    "errorCode": "insufficient_balance",
    "errorReason": "insufficient balance",
    "key": {
      "type": "EMAIL",
      "key": "destinatario@exemplo.com"
    },
    "payee": {
      "name": "JOAO SILVA",
      "document": "12345678900",
      "bankCode": "077",
      "bankIspb": "00416968",
      "branch": "1",
      "accountNumber": "0013887580"
    }
  }
}
```

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

> **Removed in v1.28.0 (2026-04-17)**
>
> This event was deprecated in v1.15.0 (2026-02-20) and has been **permanently disabled** in v1.28.0 (2026-04-17). Use `pix.out.completed` with `method: PAYMENT` and the `payment` object in the payload instead.

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

> **Removed in v1.28.0 (2026-04-17)**
>
> This event was deprecated in v1.15.0 (2026-02-20) and has been **permanently disabled** in v1.28.0 (2026-04-17). Use [`pix.refund.completed`](#7-pixrefundcompleted) instead. That event does **not** include `originalEndToEnd` or `refundEndToEnd` — the refund E2E is `endToEnd`, and the original transaction is `originalTransactionId`.

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

Sent when a PIX refund **we initiated** is completed. Different from [`pix.refund.received`](#14-pixrefundreceived), which is a return started by the original payee without us asking.

`data` uses the **same fields** as [`pix.out.completed`](#3-pixoutcompleted), with:

* Envelope `id`: `pix-refund-{paymentId}`.
* `status`: `"SUCCESS"`.
* `originalTransactionId`: ID of the original PIX IN being refunded (not empty, unlike a regular PIX out).

This event does **not** send `originalEndToEnd`, `refundEndToEnd`, or `reconciliationId`. To correlate with the original credit, use `originalTransactionId` / `identifier` and the statement.

**Full Example:**

```json
{
  "id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.refund.completed",
  "occurredAt": "2025-12-29T21:14:53.900Z",
  "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": "D0000000020251229211453900",
    "transactionId": "162982-pix",
    "amount": 150.50,
    "currency": "BRL",
    "description": "",
    "identifier": "refund-999",
    "originalTransactionId": "pix-in-E0000000020251229211433912",
    "initiatedAt": "2025-12-29T21:14:33.900Z",
    "completedAt": "2025-12-29T21:14:53.900Z",
    "payer": {
      "name": "Your Company",
      "document": "12345678000199",
      "bankCode": "999",
      "branch": "0001",
      "accountNumber": "98765-4"
    },
    "payee": {
      "name": "John Smith",
      "document": "12345678900",
      "bankCode": "001",
      "branch": "0001",
      "accountNumber": "12345-6"
    }
  }
}
```

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

Sent when a refund **we initiated** fails **definitively**.

`data` uses the **same fields** as [`pix.refund.completed`](#7-pixrefundcompleted) / [`pix.out.failed`](#4-pixoutfailed), with:

* `status`: `"FAILED"`.
* `error` / `errorCode` / `errorReason`: rejection reason (`error` is the friendly alias).
* `partner`: raw settlement-bank error, when available.

This event does **not** send `originalEndToEnd`, `refundEndToEnd`, or `reconciliationId`.

**Full Example:**

```json
{
  "id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.refund.failed",
  "occurredAt": "2025-12-29T21:14:35.000Z",
  "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": "E0000000020251229211433912",
    "transactionId": "162982-pix",
    "amount": 150.50,
    "currency": "BRL",
    "description": "",
    "identifier": "refund-998",
    "originalTransactionId": "pix-in-E0000000020251229211433912",
    "initiatedAt": "2025-12-29T21:14:33.900Z",
    "completedAt": "2025-12-29T21:14:35.000Z",
    "error": "Original transaction has already been refunded",
    "errorCode": "already_refunded",
    "errorReason": "Original transaction has already been refunded",
    "payer": {
      "name": "Your Company",
      "document": "12345678000199",
      "bankCode": "999",
      "branch": "0001",
      "accountNumber": "98765-4"
    },
    "payee": {
      "name": "John Smith",
      "document": "12345678900",
      "bankCode": "001",
      "branch": "0001",
      "accountNumber": "12345-6"
    }
  }
}
```

### 9. `fee.charged`

Sent when a banking fee is charged to the account (e.g., per-transaction PIX fee).

**`data` structure:**

* `transactionId`: Deterministic ledger row id (`fee-{coreId}`).
* `accountId` / `tenantId`: Charged account and tenant.
* `amount`: Fee amount, **always positive** in the account currency.
* `description`: Fee description.
* `feeServiceType`: Underlying service that triggered the fee (`PIX`, `BOLETO`, `P2P_CRYPTO`, ...) when the bank reports it.
* `originalRef` / `transactionRef`: Cross reference to the originating movement when available.
* `occurredAt`: Timestamp at which the bank booked the fee.
* `status`: Always `"SUCCESS"`.
* `kind`: `"CHARGED"`.

**Full Example:**

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

Sent when the bank **reverses** a previously charged fee (cashback, adjustment). Same shape as `fee.charged`, with `kind="REFUNDED"`. Funds are already credited to the account. The public `description` of any credit coming from the fee accounts is `LANÇAMENTO DE CRÉDITO` (the event type does not change).

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

Sent when a new MED (Special Return Mechanism) dispute is opened against a transaction **credited to one of your accounts**. It starts the **48-hour** clock for your response — see the [Disputes guide](/baas/guias/pagar/med).

**`data` Structure:**

* `medId`: Dispute identifier (infraction report). It is the `{medId}` used by the REST routes.
* `originalEndToEnd`: `endToEndId` of the disputed PIX transaction.
* `amount`: Disputed amount.
* `reasonCode`: Reason reported by the scheme, raw (e.g. `scam-or-fraud`, `unauthorized-transaction`).
* `claimMessage`: Free-text details provided by the claimant (when present).
* `openedAtIso`: MED opening date (ISO 8601).
* `clientAnswerDeadlineIso`: Your response deadline — `openedAtIso` + 48h.
* `status`: `OPEN` on filing.

**Full Example:**

```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": "See contacts provided in FundsRecovery",
    "openedAtIso": "2026-07-21T17:55:59.601Z",
    "clientAnswerDeadlineIso": "2026-07-23T17:55:59.601Z",
    "status": "OPEN"
  }
}
```

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

Sent when the status of a MED dispute changes. This is how you learn the outcome, and it is the **only** source of state: `POST .../answer` merely records your defense (which goes on for analysis outside the API), and the dispute also moves through action by BACEN and by the claimant's bank.

A redelivery of the same status produces no new event, and a late event (settlement-bank timestamp older than what we already stored) is dropped — the status never moves backwards.

**`data` Structure:**

* `medId`: Dispute identifier (same as `pix.med.opened`).
* `originalEndToEnd`: `endToEndId` of the disputed PIX transaction.
* `amount`: Disputed amount.
* `reasonCode`: Reported reason.
* `clientAnswerDeadlineIso`: Your response deadline (the same as on filing).
* `status`: Current MED status — dedicated vocabulary (`OPEN`, `PENDING_DECISION`, `ACCEPTED`, `REJECTED`, `CANCELED`; see the status table above).

**Settlement bank status mapping** — the raw value never leaves in the event:

| Settlement bank status                        | `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`         |

An unknown status becomes `OPEN`, not a closure: missing the filing of a dispute costs you your response window, while receiving one extra only costs a lookup.

**Full Example:**

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

Sent at each step of **CorpX's review** of a dispute: defense received, clarification requested, decision, balance hold and release, account block and release, returns, and closure. It is the event that tracks the `reviewStatus` from the [MED guide](/baas/guias/pagar/med); `pix.med.updated` keeps covering the settlement bank's status.

`data` is always the **current snapshot** of the dispute; `reason` says what just happened. You do not need to accumulate events to know where it stands.

**`data` structure:**

* `medId`, `accountId`: Dispute and account identifiers.
* `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`: Return round the step belongs to (empty outside execution).
* `decision`, `decisionMessage`: `accept` or `refuse` and the justification, from `decided` on.
* `infoRequest.message`, `infoDueAt`: The review's question and deadline, in `info_requested`.
* `lockStatus`, `lockedAmount`: Current balance hold.
* `refund.amount`, `refund.endToEndId`: The return of this event, in `refund_*`.
* `refundedTotal`, `remaining`, `refundPartial`: Return totals.

**Full example:**

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

Sent to the account that **receives** an internal transfer between accounts of the same banking ecosystem. Internal transfers are instant and settled at the same bank — they do not travel through the PIX SPI, so they have no `endToEndId`.

**`data` structure:**

* `transactionId`: Transaction ID in our system (format `internal-{uuid}`). Use it on `GET /v1/accounts/{accountId}/statement`.
* `amount`: Amount received.
* `status`: Always `SUCCESS` (internal transfers are atomic).
* `completedAt`: Settlement timestamp.
* `identifier`: Identifier the sender supplied on `POST /transfers/internal*` (when given). The same value arrives on both legs (`transfer.internal.out` and `transfer.internal.in`).
* `payerDescription` / `description`: Description supplied by the sender.
* `source`: The payer — `name`, `taxId`, `providerAccountId` and, when the account is managed by us, `accountId` and `tenantId`.
* `destination`: The receiver, with the same fields.
* `payer` / `receiver`: The same two parties, with `document` in place of `taxId`. They appear only when the transfer was initiated **outside the API** (the liquidator's app or console). Kept for compatibility — prefer `source`/`destination`, which arrive from both origins.

> **Destination outside CorpX**
>
> When the receiver is an account at another bank, `destination` carries `name` and `taxId` (the ones you supplied in the request) without `accountId`/`tenantId`. In that case only `transfer.internal.out` exists.

> **P2P order transfers**
>
> When the `identifier` belongs to a [P2P Crypto](/baas/guias/p2p/webhooks) order (`p2p-{orderId}`, `fee-p2p-{orderId}` or `fee-p2p-{orderId}-r`), the payload gains `p2pOrderId` and `p2pKind` (`payment`, `fee` or `fee_refund`), the `description` becomes the statement one (`COMPRA P2P CRIPTO`, `VENDA P2P CRIPTO`, `TAXA INTERMEDIAÇÃO KYC P2P CRIPTO`, …) and the counterparty (`source` on a credit, `destination` on a debit, and `payer`/`receiver` when present) is reduced to `{ "name": "ORDEM P2P CRIPTO" }`. The same applies to `fee.charged` and `fee.refunded`.

**Full Example:**

```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",
    "identifier": "int-transfer-12345",
    "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`

Sent to the account that **sends** an internal transfer. Same shape as `transfer.internal.in`, with two differences:

* `identifier` **is populated** on both legs when you passed `identifier` in the original request (`POST /v1/accounts/{accountId}/transfers/internal*`). Use it to reconcile the transfer on your side.
* `description` — if you passed `description` in the request, that same text comes back here (instead of the default `Transferência Interna`).

**Example:**

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

> **How to reconcile an internal transfer**
>
> When calling `POST /v1/accounts/{accountId}/transfers/internal` (or the `by-document` / `by-bank-account` variants), send your own unique `identifier`. The API response returns that `identifier` together with `transactionId`. The `transfer.internal.out` webhook arrives afterwards with the same `identifier` + `transactionId`, so you can close the transaction on your side without querying the statement.

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

Sent when the order outcome is **indeterminate** at the end of the confirmation window: the partner call was dispatched but the response/final confirmation did not arrive in time (this includes communication timeouts on the submit call itself). Not a definitive failure — a late `pix.out.completed` or `pix.out.failed` may still arrive afterwards. Check the statement before retrying with a new idempotency key; retrying with the **same** key is safe.

**`data` structure (fields specific to this event):**

* `status`: Always `"TIMEOUT"`.
* `errorCode` / `errorReason` / `warning` / `error`: What to do next (`confirmation_timeout`).
* `hold`: Present when the order is being held **at the settlement bank**. Carries `owner: "partner"` and `reason` (`partner_authorization` = the settlement bank's internal authorisation queue; `partner_risk_analysis` = risk review; `partner_unspecified` = held, queue unknown). When this object is present, **there is nothing to approve on your side or on ours** — the decision belongs to the settlement bank.
* `partnerStatus` / `partnerStatusId`: Raw snapshot of the state at the settlement bank, useful to attach to a support ticket. These are the settlement bank's values, not our canonical vocabulary: do not use them in status comparisons.

```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": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
    "error": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
    "warning": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
    "identifier": "order-12345",
    "partnerStatus": "awaiting-authorization",
    "partnerStatusId": 7,
    "hold": {
      "owner": "partner",
      "reason": "partner_authorization"
    }
  }
}
```

#### Late confirmation (`late: true`)

`TIMEOUT` is an **indeterminate** state, not a final one. When the order is held at the settlement bank, we keep polling it for up to **7 days**, and if it settles (or rejects) within that window you receive the matching terminal event:

* `pix.out.completed` with `late: true` — the money left the account.
* `pix.out.failed` with `late: true` — the settlement bank rejected it.

The late event carries the **same `paymentId`** as the `pix.out.timeout` you already received: it corrects that outcome, it is not a second payment. Treat it as the order's definitive outcome.

After 7 days without news no further event is sent and the order stays `TIMEOUT` — which literally means "we do not know". Check the statement (`GET /v1/accounts/{accountId}/statement`) before reissuing. Reissuing with the **same** `Idempotency-Key` is safe; a new key may result in a duplicate payment.

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

Sent when the **receiver** of a PIX out returns the funds on their own initiative (without us asking). Different from `pix.refund.completed`, which confirms a refund **we** triggered.

**`data` structure:**

* `transactionId`: Deterministic ID of the received refund row (`pix-refund-received-{refundEndToEnd}`).
* `refundEndToEnd`: Refund D-code (BACEN).
* `originalEndToEnd`: E-code of the original PIX out being reversed.
* `originalIdentifier`: Identifier of the original PIX out (echo of the value sent at payment creation), when available.
* `accountId` / `tenantId`: Account that received the refund.
* `amount`: Reversed amount.
* `description`: Description from the partner.
* `receivedAt`: Refund timestamp.
* `payer`: Party that returned the funds (counterparty / original PIX out recipient): name, document, bank, branch, account.
* `payee`: Party that received the credit (our account / original PIX out payer): name, document, bank, branch, account.
* `status`: Always `"SUCCESS"`.

```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": "PIX refund",
    "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": "Acme Corp LTDA",
      "document": "12345678000199",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "accountNumber": "98765-4"
    },
    "status": "SUCCESS"
  }
}
```

### 17. `qrcode.expired`

Sent when a dynamic QR Code expires without being paid, at the `expirationDate` requested at creation (24 hours later when the field was omitted). Due-date QR codes and confirmed Location QR codes expire at the end of `dueDate + daysAfterDueDate` (Brasília time).

**`data` structure:**

* `qrcodeId`: Internal QR Code ID.
* `identifier`: txid of the QR Code you created.
* `accountId` / `tenantId`: Account that owns the charge.
* `type`: today `"dynamic"`, `"due-date"` or `"location"` (static QR Codes do not expire). Extensible list, as in `qrcode.paid`.
* `amount`: Amount that was awaiting payment.
* `status`: Always `"EXPIRED"`.

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

### 18. `qrcode.cancelled`

Sent when the integrator explicitly cancels a dynamic QR Code via `DELETE /v1/accounts/{accountId}/pix/qr-code?identifier={txid}` before payment.

**`data` structure:**

* `qrcodeId`: Internal QR Code ID.
* `identifier`: txid of the QR Code you created.
* `accountId` / `tenantId`: Account that owns the charge.
* `type`: QR Code type. Extensible list, as in `qrcode.paid`.
* `status`: Always `"CANCELLED"`.
* `reason` / `cancelledBy`: Present when the cancellation carries a reason and who cancelled it.

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

### 19. `boleto.paid`

Sent when a boleto paid via `POST /v1/accounts/{accountId}/boleto/pay` is confirmed by the issuing bank.

**`data` structure:**

* `paymentId`: Canonical boleto id (`bol_{uuid}`) — **same value** returned by `POST /boleto/pay`. Use this to correlate. The envelope `id` is `boleto-{paymentId}`.
* `boletoId`: Alias of `paymentId` (same value).
* `partnerId`: Settlement-bank reference (`operationReferenceId`), for support/reconciliation.
* `accountId` / `tenantId`: Payer account.
* `amount`: Amount paid.
* `line`: Digitable line / barcode.
* `status`: Always `"SUCCESS"`.

This event does **not** send `transactionId`.

```json
{
  "id": "boleto-bol_aabbccdd",
  "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`

Sent when the issuer rejects the payment. `data.error` is a **string** with the reason (not an object). The same text is also in `data.errorReason`; `data.errorCode` is present when the settlement bank sent a code.

```json
{
  "id": "boleto-bol_eeffgghh",
  "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"
  }
}
```

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

Sent **immediately** after `POST /v1/accounts/{id}/ted/out` is accepted. Status `PROCESSING` — TED registered at the settlement bank, waiting for the BACEN window to settle. See the [TED guide](/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",
    "identifier": "ted-fornecedor-acme-001",
    "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`

Settlement confirmed by the settlement bank (terminal — success).

```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",
    "identifier": "ted-fornecedor-acme-001",
    "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"
  }
}
```

> **Deprecated alias**: the `ted.payment` event is dispatched in parallel with `ted.out.confirmed` with the same payload, kept only for compatibility with legacy subscriptions. New integrators should subscribe to **`ted.out.confirmed` only**. `ted.payment` will be removed in v3.0.

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

Settlement rejected/expired (terminal — failure). `data.errorReason` carries the canonical reason.

```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",
    "identifier": "ted-fornecedor-acme-001",
    "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"
  }
}
```

Possible `errorReason` values: `invalid_bank_code`, `insufficient_funds`, `outside_banking_hours`, `bank_unreachable`, `limit_exceeded`, or `timeout aguardando confirmação do parceiro (>48h)` (defensive polling exhausted).

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

A TED was **received** in your account (originated by a third party). Includes `data.payer` with the originator's name, document, bank (`bankCode`, `bankIspb`, `bankName`), branch and account — use them to reconcile with your books. The originator's bank details come from the settlement bank's statement; in the rare case the line is not there yet when we notify, the event carries only name and document. `data.payee` is the receiving account as the settlement bank identifies it: bank `681` / ISPB `50871921`, branch, account and holder. When a holder is shared by more than one tenant, each receives its own event with the same `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": "YOUR COMPANY LTDA",
      "document": "12345678000195",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "account": "6371893",
      "accountNumber": "6371893"
    }
  }
}
```

> Remember: for third parties to send a TED to your account, they must use **bank 681** (the settlement bank) — see the [TED guide](/baas/guias/pagar/ted#banco-liquidante-para-receber-ted).

### 25. `policy.violation`

A policy rule configured for your account or tenant was violated. The event covers every policy section — PIX out, cash-in, QR Code, keys, and refunds — and is sent both when the operation is **rejected** (`action: "BLOCK"`) and when it only **produces a warning** or a post-credit action (`NOTIFY_ONLY`, `ALLOW_AND_NOTIFY`, `AUTO_REFUND`, `LOCK_BALANCE`, `BLOCK_ACCOUNT`). Use `blocked` to tell whether the operation was rejected. On a cash-in, `blocked` is always `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": "ORDER-1234",
    "mode": "KEY",
    "amount": 5000.00,
    "violations": [
      { "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted by policy" }
    ],
    "counterparty": { "document": "12345678900", "name": "JOHN DOE" }
  }
}
```

| Field               | Description                                                                                                                                                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `phase`             | `edge` (rejected in the response, HTTP 422), `counterparty` (after resolving the recipient, during processing), `pix_in`, `ted_in`, `internal_in`, `boleto_in` (after the credit), `med` (a received dispute pushed the MED rate above the ceiling), or `dict_lookup` (key lookup rejected by limit)                                                   |
| `action`            | `BLOCK`, `NOTIFY_ONLY`, `ALLOW_AND_NOTIFY`, `AUTO_REFUND`, `LOCK_BALANCE`, or `BLOCK_ACCOUNT`, as configured in the policy                                                                                                                                                                                                                             |
| `blocked`           | `true` when the operation was actually rejected. Always `false` on a cash-in                                                                                                                                                                                                                                                                           |
| `balanceLocked`     | On a cash-in, `true` when that credit's amount was locked at the settlement bank. `false` if the action was requested and did not complete                                                                                                                                                                                                             |
| `accountBlocked`    | On a cash-in, `true` when this violation set the account to `blocked`. `false` if the action was requested and did not complete                                                                                                                                                                                                                        |
| `mode`              | `KEY`, `BANK_ACCOUNT`, `QRCODE`, or `REFUND` on PIX out; the operation subtype in the other sections (`static`/`dynamic` for QR, the key type, the incoming PIX method)                                                                                                                                                                                |
| `violations[].rule` | PIX out rules carry no prefix (`pixOutDisabled`, `cpfCnpjBlacklist`, `sameOwnershipOnly`, `operatingHours`, `allowedPersonTypes`); the other sections are prefixed (`pixIn.*`, `qrCode.*`, `keys.*`, `refund.*`) or `dictLookup.*`. PIX out `maxAmount` and `nightMaxAmount` are no longer emitted — an amount refusal is `limit_exceeded_transaction` |
| `counterparty`      | The recipient (PIX out) or the payer (PIX in), when known                                                                                                                                                                                                                                                                                              |

When `blocked` is `true` on a PIX out, you also receive the matching `pix.out.failed`, with `errorCode: policy_denied`. They are two events with distinct ids: this one is the rule warning, that one is the payment outcome.

In monitor mode (`NOTIFY_ONLY`) the payment goes through normally and will have its own outcome (`pix.out.completed`, for example) — this event is only a heads-up that the transaction would have been rejected had the rule been set to `BLOCK`.

#### Violation on a cash-in (`phase: "pix_in"`, `"ted_in"`, `"internal_in"`, or `"boleto_in"`)

A cash-in cannot be refused: the settlement bank credits the account and only then tells us. The violation always comes after the credit. The payload swaps `paymentId` for `transactionId` and the credit reference, and adds `refunded`, `balanceLocked`, and `accountBlocked`. `refunded` is `true` only for a PIX refund. `AUTO_REFUND` on TED, internal transfer, and boleto only notifies, and the money stays.

```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": "JOHN DOE", "bankCode": "260" }
}
```

The credit webhook (`pix.in.completed`, `ted.in.received`, `transfer.internal.in`, or `boleto.charge.settled`) is delivered before this event. With `refunded: true`, the PIX refund then produces the usual PIX out events (`pix.out.completed` or `pix.out.failed`). `LOCK_BALANCE` reduces the available balance at the settlement bank. `BLOCK_ACCOUNT` only cuts cash-out on our API. Neither one undoes the credit, and acknowledging the case does not unlock the balance or reopen the account.

#### Violation by MED rate (`phase: "med"`)

Fired when a new dispute received against the account pushes the MED rate of the window above the ceiling of the `med` section. The only action is `BLOCK_ACCOUNT`. The reference is the dispute's `medId`; the window numbers come in the payload so the integrator can rebuild the math. The `pix.med.opened` for that same dispute goes out with `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%" }
  ]
}
```

Rule and configuration details are in the [Policies and Rules](/baas/guias/autenticacao/politicas) guide.

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

The issued slip was registered at the central base. `chargeId` is the same id returned by `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`

Registration of the slip was rejected. `statusReason` carries the reason when the bank provides one.

```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": "invalid payer",
    "nominalAmount": 150.0,
    "updatedAmount": 150.0,
    "barcode": "",
    "digitableLine": "",
    "dueDate": "2026-10-15"
  }
}
```

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

The slip was paid. The credit also shows on the statement as `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`

The due date passed and the slip is still open. This is not a terminal state.

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

The slip was written off.

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

The slip was cancelled.

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

The payment window ended.

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

Reserved in the catalog. This version does not send the event: a registration rejection is `boleto.charge.registration_failed`, and a beneficiary registration failure is the **502** on the `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`

Sent when every issuance attempt in a batch has finished. `status` is
`COMPLETED`, `PARTIAL_FAILED`, or `FAILED`. This ends batch processing, not the
individual lifecycle: registration, payment, overdue, and expiration continue
for generated boletos.

`statistics` carries `total`, `issued`, and `failed`, the terminal snapshot of
issuance attempts. Payment continues afterwards: read the batch for
`statistics.payment` and current conversion (`paid / issued × 100`).

Subscribe with `authType: HMAC`. The delivery carries `X-Signature`; verify
the HMAC-SHA256 over the raw body bytes and deduplicate on `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`

The settlement bank confirmed the account's boleto beneficiary registration (or reactivated a closed relationship, with `reactivated: true`). The account can issue. `operationId` is the one returned by the registration 202. The four beneficiary events share `accountId`, `beneficiaryId`, `operation` (`INCLUSION`, `UPDATE`, `STATUS_UPDATE` or `TERMINATION`), `result` (`CONFIRMED` or `REJECTED`), `operationId` and `occurredAt`. See the [boleto issuance guide](/baas/guias/cobranca/boleto-charge#tracking-the-beneficiary-by-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`

The settlement bank rejected a beneficiary operation. `operation` says which one; `rejectionCode` and `rejectionReason` come from the bank. After a rejected registration (`INCLUSION`), issuance returns **502** `boleto_charge_beneficiary_registration_failed` for 24 hours without registering again; `POST .../boleto/charge/beneficiary` registers again right away.

```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": "Beneficiary data does not match the provider's records."
  }
}
```

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

An update was applied. `UPDATE` (registration data) carries `updatedAt`. `STATUS_UPDATE` (eligibility) also carries `previousStatus` and `currentStatus`, with the same values as `status` in `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`

The beneficiary relationship was closed. The account cannot issue new boletos until it is registered again. `closedAgreementsCount` is how many agreements were closed and `issuanceBlocked` confirms issuance is blocked.

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

Sent when a standalone identity verification reaches a terminal state:
`APPROVED`, `FAILED`, or `EXPIRED`. `PENDING` never produces this event. The
verification belongs to the tenant rather than a bank account, so the envelope
has no `accountId`.

Every delivery includes `X-Signature`. Verify it against the **raw request body
bytes** before parsing JSON, and deduplicate on the envelope `id`.

**Fields in `data`:**

* `verificationId`: ID returned by `POST /v1/identity-verifications`;
* `status`: `APPROVED`, `FAILED`, or `EXPIRED`;
* `purpose` and `referenceId`: exact binding supplied at creation;
* `document`: 11-digit CPF;
* `failureReason`: normalized failure/expiry reason; `null` on approval;
* `completedAt`: terminal instant in UTC;
* `consumableUntil`: approval consumption deadline; omitted for other states;
* `method`: `link` (hosted page) or `facetec_sdk` (SDK embedded in the app);
* `referenceMatch` and `checks`: only for `facetec_sdk`. `checks.liveness` is
  the liveness result and `checks.faceMatch.result` the 1:1 face match result
  (`not_performed` when `referenceMatch` is `none` — the approval only proves
  a live person was present, not who they are).

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

The webhook notifies; it does not consume the proof. After validating the
event, call `POST /v1/identity-verifications/{verificationId}/consume` with the
same `purpose` and `referenceId`. See the complete flow in
[Identity verification](/baas/guias/apis-adicionais/verificacao-de-identidade).

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

Sent when every item of a [PIX batch](/baas/guias/pagar/pix-em-lote) reached
an outcome. `status` is `COMPLETED`, `PARTIAL_FAILED`, or `FAILED`. Each item
is a regular PIX out and has already emitted its own `pix.out.completed`,
`pix.out.failed`, or `pix.out.timeout`; this event closes the batch and does
not replace the per-item events.

`statistics` carries counts (`total`, `completed`, `failed`) and BRL sums as
decimal strings (`totalAmount`, `completedAmount`, `failedAmount`). For the
item list, `GET .../pix/batches/{batchId}`; for the correction CSV of failed
rows, `GET .../items/export?status=failed`; for the receipts ZIP,
`POST .../receipts`.

Subscribe with `authType: HMAC`. The delivery carries `X-Signature`; verify
the HMAC-SHA256 over the raw body bytes and deduplicate on `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`

A limit-increase request changed status. Sent on approval (the ceiling is already applied), refusal and cancellation. It is not sent when the request opens: that is `limit_request.created`. Approval also sends `account.limits.updated`, with no guaranteed order between the two. `actingDocument` is the CPF or CNPJ of the person who asked — use it to notify the right person. `approvedLimitBrl` may be lower than the request when the reviewer adjusts the amount, never higher. A null `effectiveAt` means the new ceiling is already in force. For a multi-operation request, `bundleId` identifies the bundle and `items` carries each operation's status and amounts.

```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": "Approved in part.",
    "effectiveAt": null,
    "actingDocument": "39053344705",
    "identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21"
  }
}
```

### 38. `limit_request.created`

A limit increase was opened. Sent on INSERT, whether it came from the API (`channel: api`, integrator token) or the backoffice (`channel: backoffice`, panel user token). It is not sent again on a replay of the same `Idempotency-Key`. The envelope `id` is `lr-{id}-pending_review`.

`data` has the same shape as `limit_request.updated`, plus `currentLimitBrl` (the effective ceiling at open, including the previous register; `0` only if the window was open), `justification` and `channel`. For a bundle, `bundleId` and `items` include every operation opened together.

A subscription with an empty event list receives the event. An explicit list receives it only if `limit_request.created` is on the list. Deduplicate by `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": "Monthly payroll.",
    "channel": "api"
  }
}
```

| Field             | Meaning                                                  |
| ----------------- | -------------------------------------------------------- |
| `currentLimitBrl` | Effective ceiling of the window when the request opened. |
| `justification`   | Text from the requester, up to 500 characters.           |
| `channel`         | `api` or `backoffice`.                                   |

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

An account or operator ceiling actually changed. Sent after a staff PATCH, an internal-credential PATCH, approval of a request (including windows materialized from the previous register) and operator ceiling PUT/DELETE.

It is not sent when a tenant or global default changes, nor when an already scheduled operator relaxation (6 h) takes effect: the scheduling event already carried `effectiveAt`.

The envelope `id` is the limit-audit event id. A dispatch retry does not open another delivery. On approval it sits next to `limit_request.updated`, with no order. Deduplicate by `id` and, when the amount matters, read `GET /limits/available` again.

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

| Field                    | Meaning                                                                         |
| ------------------------ | ------------------------------------------------------------------------------- |
| `subject.type`           | `account` or `operator`. For an operator, `subject.document` is the CPF.        |
| `source`                 | `staff`, `internal`, `limit_request` or `owner`.                                |
| `limitRequestId`         | Present only when the change came from a request.                               |
| `changes[].window`       | `single_transfer`, `daytime`, `nighttime` or `monthly`.                         |
| `beforeBrl` / `afterBrl` | Own ceiling before and after. `0` before means the cell did not exist.          |
| `effectiveAt`            | `null` when it already applies. Set when an operator increase waits 6 h.        |
| `materializedFromLegacy` | `true` when the window was copied from the previous register in the same write. |

### Pix Automático events

`pix.automatic.*` events are sent for the receiving account of the recurrence. `recurrenceId` is the UUID returned by `POST /v1/accounts/{accountId}/pix/automatic/recurrences` (or by the composite QR issuance); `recurrenceIdentifier` is the `RR…`/`RN…` identifier assigned in the Pix scheme and appears as soon as it is known. The envelope `id` is deterministic per recurrence, event and status: deduplicate by it. Full guide in [Pix Automático](/baas/guias/pix-automatico/visao-geral).

| `data.status`                                                                                                                                 | Where it appears                   |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `awaiting_authorization`, `authorization_received`, `authorized`, `rejected`, `request_failed`, `authorization_failed`, `canceled`, `expired` | Recurrence                         |
| `created`, `received`, `awaiting_confirmation`, `confirmed`, `rejected`, `confirmation_failed`, `settled`, `canceled`, `expired`              | Scheduling                         |
| `balance_reserved`, `insufficient_balance`, `settled`, `settled_with_error`, `not_settled`, `not_settled_with_error`                          | Settlement `data.settlementStatus` |

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

The payer authorized the recurrence in their bank app. From now on you can schedule charges.

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

The payer or their bank rejected the recurrence. `rejectionReason` is present when the bank provides a reason.

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

The authorization request expired without an answer from the payer, or the recurrence was canceled. `data.status` tells which (`expired` or `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`

The authorization request failed before reaching the payer (`request_failed`) or when the authorization was confirmed (`authorization_failed`). Review the payer data and create a new recurrence.

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

The payer's bank confirmed the charge scheduling. `schedulingId` is the id returned by `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`

The payer's bank rejected the scheduling. `errorCode` and `errorMessage` are present when provided.

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

The scheduling was not confirmed: the payer's bank did not answer in time (`expired`) or the confirmation failed (`confirmation_failed`). The payload is the same as `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`

The scheduled charge was settled into your account. `settlementStatus` is `settled` or `settled_with_error`. The account credit also emits `pix.in.completed` with the same `endToEndId`; do not add both up. `purpose` is `retry` when the settlement came from a retry.

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

The charge was not settled. `settlementStatus` is `insufficient_balance`, `not_settled` or `not_settled_with_error`. Use `settlementId` to query the retry dates (`GET .../settlements/{settlementId}/retry-dates`) and request a retry. The payload is the same as `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`

The composite QR (immediate or due-date charge + recurrence authorization) was paid. The payment also emits `pix.in.completed`; this event exists so you can link the payment to the recurrence, which then goes to authorization and later emits `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"
  }
}
```

## Best Practices

* **Idempotency**: Your application should be prepared to receive the same webhook more than once. Use the envelope `id` to avoid duplicate processing.
* **Quick Response**: Return a `200 OK` status as soon as you receive the webhook and process the business logic asynchronously to avoid timeouts.
* **Timestamp Validation**: Check that the `occurredAt` is not too old (we recommend a 5-minute tolerance) to prevent replay attacks.