Pular para o conteúdo principal

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:

{
  "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.
  • 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/payments/*. Ainda não há confirmação do BACEN.

  • severity: info
  • source: workflow
  • payload: 
    {
      "paymentId": "pay_...",
      "accountId": "acc_...",
      "amount": "100.00",
      "mode": "KEY",
      "keyType": "EVP",
      "identifier": "client-ref-123",
      "idempotencyKey": "..."
    }

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 em até 5 minutos. 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: "..."}

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: 
    {
      "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 ou estático criado via POST /v1/accounts/{id}/pix/qr-code/*.

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

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.

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

Modos avançados (backoffice)​

O painel CorpX expõe internamente um modo ?level=full que retorna, além dos eventos públicos, a Temporal History completa do workflow (decisões internas, retries de activity, signals, timers). Esse modo é restrito a operadores com a role apropriada e 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.