> This page is for BaaS.

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

# Timeline de transações

A API mantém uma **timeline pública** com os eventos relevantes do ciclo
de vida de cada transação. O painel CorpX consome essa timeline para
montar a visualização passo a passo da transação, e você pode
consumi-la pela mesma API para alimentar dashboards próprios ou aceleros
de suporte ao cliente final.

## Endpoint

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

Resposta:

```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 solicitado",
      "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"
      }
    }
  ]
}
```

### Filtros (query params)

* `eventType` — filtra por tipo exato (ex.: `pix_out.confirmed`).
* `source` — filtra por origem (`workflow`, `partner_webhook`, `client_webhook`, `backoffice`, `system`, `partner_poll`, `api`).
* `since` — ISO 8601 (ex.: `2026-05-05T00:00:00Z`); só eventos com `occurredAt >= since`.
* `limit` — máximo 1000 (default 500).

### Ordenação

Eventos são retornados em ordem cronológica crescente por `occurredAt`,
desempatado por `recordedAt` (chegada). Use o último evento da resposta
como cursor para paginação simples por `since`.

## Garantias do contrato

Os tipos de evento listados abaixo são parte do contrato público e
seguem regras de evolução **append-only**:

* **Adições** são *minor* SemVer e não exigem mudança no integrador —
  novos `event_type` simplesmente passam a aparecer na resposta.
* **Renome ou remoção** de tipos é *major* (breaking) e passa por
  período formal de deprecation, anunciado no [changelog](/baas/changelog).
* **Campos do `payload`** podem ganhar novos campos opcionais sem aviso;
  campos existentes nunca são removidos sem versão major.

Resumindo: trate qualquer `event_type` desconhecido como informativo e
ignore com graça — futuras versões podem adicionar tipos sem que isso
quebre seu cliente.

## Catálogo de eventos públicos

Cada evento é identificado por um string dot-separated (`<domínio>.<verbo>`).
Os campos `severity`, `source` e `payload` ajudam a renderizar e filtrar
na sua UI.

**Convenção mnemônica de verbos:**

* `received` — chegou até você sem ação prévia (ex.: `pix_in.received`, `refund.received`).
* `requested` — você pediu via API (ex.: `pix_out.requested`, `boleto_pay.requested`).
* `created` — você criou um recurso (ex.: `qrcode.created`).
* `confirmed`, `failed`, `timeout`, `refunded` — desfechos.

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

#### `pix_out.requested`

A CorpX aceitou o pedido de PIX out (saída) iniciado em
`POST /v1/accounts/{accountId}/pix/out` ou em uma das suas variantes
(`/pix/out/async`, `/pix/out/bank-account`, `/pix/out/qr-code/async`,
`/pix/out/bigpix`, `/pix/out/refund`). Ainda não há confirmação do BACEN.

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

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

  Em uma devolução (`"mode": "REFUND"`) o payload traz dois campos a
  mais: `originalAmount` (valor do PIX que está sendo devolvido) e
  `partialRefund` (`true` quando `amount` é menor que o original).

#### `pix_out.confirmed`

O BACEN confirmou a transferência. Equivalente ao webhook outbound
`pix.out.completed`.

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

#### `pix_out.failed`

A transferência falhou (saldo insuficiente, chave inválida, recusa do
BACEN). O dinheiro **não saiu**.

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

#### `pix_out.timeout`

A chamada para o parceiro foi aceita, mas o status final não foi
confirmado dentro da janela de confirmação (5 minutos, estendidos para 25
quando o parceiro sinaliza que está segurando a ordem — a mensagem do
evento traz o prazo que de fato valeu). **Não retentar** com nova
`Idempotency-Key` sem antes consultar o extrato — o dinheiro pode ter
saído.

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

`hold` aparece quando a ordem está retida no banco liquidante, com
`owner: "partner"` e `reason` (`partner_authorization`,
`partner_risk_analysis` ou `partner_unspecified`) — nesse caso não há
aprovação pendente do seu lado nem do nosso.

Este evento **não é final**: se o liquidante liberar ou recusar a ordem
depois (seguimos consultando por até 7 dias), a timeline recebe o
`pix_out.confirmed` ou `pix_out.failed` correspondente, com `late: true`
no payload.

#### `pix_out.refunded`

Um PIX out enviado por você foi devolvido pelo destinatário (refund).
O `payload` carrega o vínculo com a devolução.

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

#### `pix_out.client_webhook_sent`

Confirmação de que o webhook outbound (`pix.out.*` ou `pix.refund.*`)
foi entregue com sucesso ao seu endpoint configurado. Útil para
auditoria — equivalente ao `delivered_at` do delivery log.

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

---

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

#### `pix_in.received`

Um PIX foi creditado em uma de suas contas — a CorpX persistiu o
crédito no extrato. Aplicações típicas: notificar o sistema interno do
integrador para conciliar com o pedido de compra; disparar fluxos de
pós-pagamento.

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

#### `pix_in.client_webhook_sent`

Confirmação de entrega do webhook outbound `pix.in.completed` ao seu
endpoint.

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

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

#### `qrcode.created`

QR code dinâmico, estático ou com vencimento criado via `POST /v1/accounts/{id}/pix/qr-code/*`, ou QR Location confirmado.

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

#### `qrcode.paid`

O QR code foi pago pelo cliente final (signal recebido do BACEN ou
detectado via polling proativo).

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

#### `qrcode.client_webhook_sent`

Confirmação de entrega do webhook outbound `qrcode.paid`.

#### `qrcode.location_generated`

QR [Pix Location](/baas/guias/receber/pix-location) gerado bloqueado via
`POST /v1/accounts/{id}/pix/qr-code/location`. Ainda não aceita pagamento.

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

#### `qrcode.location_confirm_failed`

O liquidante recusou a confirmação do QR Location. O QR continua bloqueado
e pode ser confirmado de novo.

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

### Boleto (`boleto_pay.*`)

#### `boleto_pay.requested`

Pagamento de boleto solicitado em `POST /v1/accounts/{id}/boleto/pay`. Ainda não há confirmação do parceiro.

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

#### `boleto_pay.confirmed`

Stark/parceiro confirmou o pagamento do boleto.

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

#### `boleto_pay.failed`

Pagamento de boleto falhou.

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

#### `boleto_pay.client_webhook_sent`

Confirmação de entrega do webhook outbound `boleto.paid` ou `boleto.failed`.

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

A timeline da recorrência inteira (pedido, autorização, agendamentos,
liquidações e retentativas) fica em um só `transactionId`: o
`recurrenceId` (UUID). Consulte `GET /v1/transactions/{recurrenceId}/timeline`.
Todos têm `source: workflow`, exceto os de entrega de webhook.

| Tipo                                                         | `severity` | Quando                                                                    |
| ------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------- |
| `pix_automatic.recurrence_requested`                         | `info`     | Pedido de autorização enviado ao banco do pagador.                        |
| `pix_automatic.qrcode_created`                               | `info`     | QR composto emitido.                                                      |
| `pix_automatic.qrcode_paid`                                  | `info`     | QR composto pago.                                                         |
| `pix_automatic.recurrence_authorized`                        | `info`     | O pagador autorizou.                                                      |
| `pix_automatic.recurrence_rejected`                          | `warn`     | O pagador ou o banco dele recusou.                                        |
| `pix_automatic.recurrence_expired`                           | `warn`     | Pedido expirou ou recorrência cancelada.                                  |
| `pix_automatic.recurrence_failed`                            | `error`    | Pedido falhou antes de chegar ao pagador.                                 |
| `pix_automatic.scheduling_requested`                         | `info`     | Agendamento ou retentativa enviado ao banco do pagador.                   |
| `pix_automatic.scheduling_confirmed`                         | `info`     | Banco do pagador confirmou o agendamento.                                 |
| `pix_automatic.scheduling_rejected`                          | `warn`     | Banco do pagador recusou o agendamento.                                   |
| `pix_automatic.scheduling_failed`                            | `error`    | Agendamento não confirmado ou expirado.                                   |
| `pix_automatic.settlement_confirmed`                         | `info`     | Cobrança liquidada na conta.                                              |
| `pix_automatic.settlement_failed`                            | `error`    | Cobrança não liquidada.                                                   |
| `pix_automatic.client_webhook_sent` / `_failed` / `_skipped` | —          | Entrega do webhook outbound `pix.automatic.*` (`source: client_webhook`). |

O `payload` repete os campos do `data` do webhook correspondente
(`recurrenceId`, `recurrenceIdentifier`, `status`, `schedulingId`,
`endToEndId`, `dueDate`, `amount`, `settlementStatus`).

### Refund recebido (`refund.*`)

Esses eventos aparecem na timeline da transação **de refund** que
chegou. A própria transação original que foi devolvida ganha um evento
`pix_out.refunded` na sua timeline (linkando o refund).

#### `refund.received`

Um refund chegou para uma das suas contas — alguém devolveu um PIX que
você havia enviado.

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

#### `refund.confirmed`

O refund foi marcado como concluído com sucesso (registro persistido,
saldo creditado de volta na conta).

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

#### `refund.failed`

Tentativa de processar o refund falhou (raro — usualmente parte de um
incidente operacional).

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

### Ações de backoffice (`backoffice.user_action`)

Operadores CorpX ocasionalmente atuam manualmente em uma transação
(aprovação, ajuste, override de policy). Quando isso acontece, a ação
fica registrada na timeline. Esses eventos têm sempre os campos
`actor` (e-mail do operador) e `payload.action` (string semântica
descrevendo o que foi feito).

* `severity`: `info` ou `warn` (dependendo da ação)
* `source`: `backoffice`

## Modo interno

Existe um modo interno `?level=full` que devolve, além dos eventos
públicos, o histórico completo da operação. Ele **não faz parte do
contrato público** — não programe seu cliente para depender dele.

Se você precisa de um nível adicional de transparência (ex.: relatório
de SLA, debugging de integração), abra um ticket — podemos avaliar
mover algum evento interno relevante para a taxonomia pública.