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

# Transaction Timeline

The API maintains a **public timeline** of relevant lifecycle events
for every transaction. The CorpX dashboard consumes this timeline to
render the step-by-step view of a transaction; you can consume the
same API to power your own dashboards or accelerate end-customer
support.

## Endpoint

```
GET /v1/transactions/{transactionId}/timeline
Authorization: Bearer <jwt>
```

Response:

```json
{
  "transactionId": "pay_01HMABCD...",
  "level": "public",
  "events": [
    {
      "eventId": "8a2c...",
      "transactionId": "pay_01HMABCD...",
      "workflowId": "pixout-acc_X-key_Y",
      "type": "pix_out.requested",
      "source": "workflow",
      "audience": "public",
      "severity": "info",
      "occurredAt": "2026-05-05T22:14:01.045Z",
      "recordedAt": "2026-05-05T22:14:01.231Z",
      "message": "PIX out requested",
      "payload": {
        "paymentId": "pay_01HMABCD...",
        "accountId": "acc_X",
        "amount": "100.00",
        "mode": "KEY"
      }
    },
    {
      "type": "pix_out.confirmed",
      "occurredAt": "2026-05-05T22:14:03.612Z",
      "severity": "info",
      "payload": {
        "status": "COMPLETED",
        "endToEndId": "E18236120202605051914aBcDeF"
      }
    }
  ]
}
```

### Filters (query params)

* `eventType` — filter by exact type (e.g. `pix_out.confirmed`).
* `source` — filter by origin (`workflow`, `partner_webhook`, `client_webhook`, `backoffice`, `system`, `partner_poll`, `api`).
* `since` — ISO 8601 (e.g. `2026-05-05T00:00:00Z`); only events with `occurredAt >= since`.
* `limit` — maximum 1000 (default 500).

### Ordering

Events are returned in ascending chronological order by `occurredAt`,
tie-broken by `recordedAt` (insertion time). Use the last event's
`occurredAt` from the response as a cursor for simple pagination via
`since`.

## Contract guarantees

The event types listed below are part of the public contract and
follow **append-only** evolution rules:

* **Additions** are *minor* SemVer and don't require any change on
  your side — new `event_type` values simply start appearing.
* **Renames or removals** are *major* (breaking) and go through a
  formal deprecation period announced in the [changelog](/baas/changelog).
* **Payload fields** may gain new optional fields without notice;
  existing fields are never removed without a major version.

In short: treat any unknown `event_type` as informational and ignore
gracefully — future versions may add types without breaking your
client.

## Public event catalog

Each event is identified by a dot-separated string
(`<domain>.<verb>`). The `severity`, `source` and `payload` fields
help you render and filter in your UI.

**Verb conventions (mnemonic):**

* `received` — arrived at you without prior action (e.g. `pix_in.received`, `refund.received`).
* `requested` — you requested it via API (e.g. `pix_out.requested`, `boleto_pay.requested`).
* `created` — you created a resource (e.g. `qrcode.created`).
* `confirmed`, `failed`, `timeout`, `refunded` — outcomes.

### PIX out (`pix_out.*`)

#### `pix_out.requested`

CorpX accepted the PIX out request initiated via
`POST /v1/accounts/{accountId}/pix/out` or one of its variants
(`/pix/out/async`, `/pix/out/bank-account`, `/pix/out/qr-code/async`,
`/pix/out/bigpix`, `/pix/out/refund`). There is no BACEN confirmation yet.

* `severity`: `info`
* `source`: `workflow`
* `payload`:

  ```json
  {
    "paymentId": "pay_...",
    "accountId": "acc_...",
    "amount": "100.00",
    "mode": "KEY",
    "keyType": "EVP",
    "identifier": "client-ref-123",
    "idempotencyKey": "..."
  }
  ```

  On a refund (`"mode": "REFUND"`) the payload carries two extra fields:
  `originalAmount` (the amount of the PIX being refunded) and
  `partialRefund` (`true` when `amount` is smaller than the original).

#### `pix_out.confirmed`

BACEN confirmed the transfer. Equivalent to the outbound webhook
`pix.out.completed`.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{paymentId, accountId, status, transactionId, endToEndId, amount}`

#### `pix_out.failed`

The transfer failed (insufficient balance, invalid key, BACEN refusal).
The money **did not leave** the account.

* `severity`: `error`
* `source`: `workflow`
* `payload`: `{paymentId, status: "FAILED" | "REJECTED", errorCode, errorReason, ...}`

#### `pix_out.timeout`

The partner accepted the call but the final status was not confirmed
within the confirmation window (5 minutes, extended to 25 when the
partner signals it is holding the order — the event message states the
deadline that actually applied). **Do not retry** with a new
`Idempotency-Key` without first checking the account statement — the
money may have left.

* `severity`: `warn`
* `source`: `workflow`
* `payload`: `{paymentId, errorCode: "confirmation_timeout", errorReason: "...", hold?, partnerStatus?, partnerStatusId?}`

`hold` appears when the order is held at the settlement bank, with
`owner: "partner"` and `reason` (`partner_authorization`,
`partner_risk_analysis` or `partner_unspecified`) — in that case there is
no approval pending on your side or on ours.

This event is **not final**: if the settlement bank later releases or
rejects the order (we keep polling for up to 7 days), the timeline
receives the matching `pix_out.confirmed` or `pix_out.failed`, with
`late: true` in the payload.

#### `pix_out.refunded`

A PIX out you sent was returned by the recipient (refund). The
`payload` carries the linkage to the refund.

* `severity`: `info`
* `source`: `workflow`
* `payload`:
  ```json
  {
    "originalTransactionId": "pay_...",
    "refundTransactionId": "pay_...",
    "amount": "100.00"
  }
  ```

#### `pix_out.client_webhook_sent`

Confirms that the outbound webhook (`pix.out.*` or `pix.refund.*`)
was successfully delivered to your configured endpoint. Useful for
auditing — equivalent to `delivered_at` in the delivery log.

* `severity`: `info`
* `source`: `client_webhook`
* `payload`: `{eventId, eventType, subscriptionId, statusCode}`

---

### PIX in (`pix_in.*`)

#### `pix_in.received`

A PIX was credited to one of your accounts — CorpX persisted the
credit on the statement. Typical uses: notify the integrator's
internal system to reconcile against an order; trigger post-payment
workflows.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{transactionId, endToEndId, accountId, amount, description, identifier, method, payerName, payerDocument}`

#### `pix_in.client_webhook_sent`

Confirms delivery of the outbound webhook `pix.in.completed` to your
endpoint.

* `severity`: `info`
* `source`: `client_webhook`

### QR Code (`qrcode.*`)

#### `qrcode.created`

A dynamic, static or due-date QR code was created via `POST /v1/accounts/{id}/pix/qr-code/*`, or a Location QR code was confirmed.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{txid, accountId, amount, qrType, identifier, expiresAt}`

#### `qrcode.paid`

The QR code was paid by the end customer (signal received from BACEN
or detected via proactive polling).

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{txid, accountId, paidAmount, transactionId, endToEndId, payerDocument, payerName}`

#### `qrcode.client_webhook_sent`

Confirms delivery of the outbound webhook `qrcode.paid`.

#### `qrcode.location_generated`

A [Pix Location](/baas/guias/receber/pix-location) QR code was generated
blocked via `POST /v1/accounts/{id}/pix/qr-code/location`. It does not
accept payment yet.

* `severity`: `info`
* `source`: `api`
* `payload`: `{identifier, accountId, qrType, status, locationId}`

#### `qrcode.location_confirm_failed`

The settlement bank refused the Location QR confirmation. The QR stays
blocked and can be confirmed again.

* `severity`: `error`
* `source`: `api`
* `payload`: `{identifier, accountId, qrType, status, errorCode}`

### Boleto (`boleto_pay.*`)

#### `boleto_pay.requested`

Boleto payment requested via `POST /v1/accounts/{id}/boleto/pay`. Partner confirmation has not arrived yet.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{boletoId, accountId, line, amount, taxId, scheduled}`

#### `boleto_pay.confirmed`

Stark/partner confirmed the boleto payment.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{boletoId, starkId, accountId, amount, line}`

#### `boleto_pay.failed`

Boleto payment failed.

* `severity`: `error`
* `source`: `workflow`
* `payload`: `{boletoId, errorReason}`

#### `boleto_pay.client_webhook_sent`

Confirms delivery of the outbound webhook `boleto.paid` or `boleto.failed`.

### Pix Automático (`pix_automatic.*`)

The timeline of the whole recurrence (request, authorization, schedulings,
settlements and retries) lives under one `transactionId`: the
`recurrenceId` (UUID). Query `GET /v1/transactions/{recurrenceId}/timeline`.
All have `source: workflow`, except the webhook delivery ones.

| Type                                                         | `severity` | When                                                                           |
| ------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------ |
| `pix_automatic.recurrence_requested`                         | `info`     | Authorization request sent to the payer's bank.                                |
| `pix_automatic.qrcode_created`                               | `info`     | Composite QR issued.                                                           |
| `pix_automatic.qrcode_paid`                                  | `info`     | Composite QR paid.                                                             |
| `pix_automatic.recurrence_authorized`                        | `info`     | The payer authorized.                                                          |
| `pix_automatic.recurrence_rejected`                          | `warn`     | The payer or their bank rejected.                                              |
| `pix_automatic.recurrence_expired`                           | `warn`     | Request expired or recurrence canceled.                                        |
| `pix_automatic.recurrence_failed`                            | `error`    | Request failed before reaching the payer.                                      |
| `pix_automatic.scheduling_requested`                         | `info`     | Scheduling or retry sent to the payer's bank.                                  |
| `pix_automatic.scheduling_confirmed`                         | `info`     | The payer's bank confirmed the scheduling.                                     |
| `pix_automatic.scheduling_rejected`                          | `warn`     | The payer's bank rejected the scheduling.                                      |
| `pix_automatic.scheduling_failed`                            | `error`    | Scheduling not confirmed or expired.                                           |
| `pix_automatic.settlement_confirmed`                         | `info`     | Charge settled into the account.                                               |
| `pix_automatic.settlement_failed`                            | `error`    | Charge not settled.                                                            |
| `pix_automatic.client_webhook_sent` / `_failed` / `_skipped` | —          | Delivery of the outbound `pix.automatic.*` webhook (`source: client_webhook`). |

The `payload` repeats the fields of the matching webhook `data`
(`recurrenceId`, `recurrenceIdentifier`, `status`, `schedulingId`,
`endToEndId`, `dueDate`, `amount`, `settlementStatus`).

### Inbound refund (`refund.*`)

These events appear on the timeline of the **refund transaction** that
arrived. The original transaction that was refunded gets a
`pix_out.refunded` event on its own timeline, linking the refund.

#### `refund.received`

A refund arrived for one of your accounts — someone returned a PIX
you had sent.

* `severity`: `info`
* `source`: `workflow`
* `payload`: `{transactionId, refundEndToEndId, originalEndToEndId, accountId, amount}`

#### `refund.confirmed`

The refund was marked as successfully completed (record persisted,
balance credited back to the account).

* `severity`: `info`
* `source`: `workflow`

#### `refund.failed`

Attempt to process the refund failed (rare — usually part of an
operational incident).

* `severity`: `error`
* `source`: `workflow`

### Backoffice actions (`backoffice.user_action`)

CorpX operators occasionally act manually on a transaction (approval,
adjustment, policy override). When that happens, the action is
recorded on the timeline. These events always carry an `actor` (the
operator's e-mail) and `payload.action` (a semantic string describing
what was done).

* `severity`: `info` or `warn` (depending on the action)
* `source`: `backoffice`

## Internal mode

The CorpX dashboard internally exposes a **`?level=full` mode** that
returns, on top of the public events, the full operation history
(internal decisions, retries, signals, timers).
This mode is restricted to operators with the appropriate role and
**is not part of the public contract** — do not program your client
to depend on it.

If you need an additional level of transparency (e.g. SLA reporting,
integration debugging), open a ticket — we can evaluate moving a
relevant internal event into the public taxonomy.