交易时间线

API 为每笔交易维护一个公共时间线，记录交易生命周期中的关键事件。 CorpX 控制台基于该时间线渲染交易的逐步视图；您也可以通过同样的 API 将其用于自有仪表板或加速终端客户支持流程。

端点

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

响应：

{
  "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 转出已发起",
      "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"
      }
    }
  ]
}

过滤参数（query params）

eventType — 按精确类型过滤（例如 pix_out.confirmed）。
source — 按来源过滤（workflow、partner_webhook、client_webhook、backoffice、system、partner_poll、api）。
since — ISO 8601（例如 2026-05-05T00:00:00Z）；仅返回 occurredAt >= since 的事件。
limit — 最多 1000（默认 500）。

排序

事件按 occurredAt 升序返回，相同时按 recordedAt（写入时间）排序。您可以使用响应中最后一个事件的 occurredAt 作为分页游标，配合 since 实现简单分页。

契约保证

下方列出的事件类型是公共契约的一部分，遵循仅追加（append-only） 的演进规则：

新增属于 minor 版本（SemVer），无需您修改任何代码；新的 event_type 会自然出现在响应中。
改名或删除属于 major（破坏性）变更，会经过正式的弃用期，并在更新日志中提前公告。
payload 字段可能在不通知的情况下新增可选字段；已有字段不会在小版本中删除。

简言之：将任何未知的 event_type 视为信息性事件并优雅忽略 —— 未来版本可能新增类型，但绝不会破坏您的客户端。

公共事件目录

每个事件由形如 <域>.<动词> 的点分字符串标识。severity、source 与 payload 字段可帮助您在自己的 UI 中渲染与过滤。

动词命名约定（助记）：

received —— 在您未发起请求的情况下到达（如 pix_in.received、refund.received）。
requested —— 您通过 API 主动请求（如 pix_out.requested、boleto_pay.requested）。
created —— 您创建了一个资源（如 qrcode.created）。
confirmed、failed、timeout、refunded —— 终态结果。

PIX 转出（`pix_out.*`）

`pix_out.requested`

CorpX 已接收通过 POST /v1/payments/* 发起的 PIX 转出请求。此时尚未收到 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`

BACEN 已确认转账成功。等同于 outbound webhook 中的 pix.out.completed 事件。

severity：info
source：workflow
payload：{paymentId, accountId, status, transactionId, endToEndId, amount}

`pix_out.failed`

转账失败（余额不足、密钥无效、BACEN 拒绝等）。资金未离开账户。

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

`pix_out.timeout`

合作方已接受调用，但 5 分钟内未确认最终状态。不要使用新的 Idempotency-Key 重试 —— 在确认对账单之前可能会重复扣款。

severity：warn
source：workflow
payload：{paymentId, errorCode: "confirmation_timeout", errorReason: "..."}

`pix_out.refunded`

您发起的 PIX 转出被收款方退款（refund）。payload 中包含与退款的关联信息。

severity：info
source：workflow

payload：

{
  "originalTransactionId": "pay_...",
  "refundTransactionId": "pay_...",
  "amount": "100.00"
}

`pix_out.client_webhook_sent`

确认 outbound webhook（pix.out.* 或 pix.refund.*）已成功投递至您配置的端点。适用于审计，等价于投递日志中的 delivered_at。

severity：info
source：client_webhook
payload：{eventId, eventType, subscriptionId, statusCode}

PIX 入账（`pix_in.*`）

`pix_in.received`

您的某个账户收到了一笔 PIX —— CorpX 已将该入账写入账单。典型用途：通知集成方的内部系统与订单进行对账；触发支付后续流程。

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

`pix_in.client_webhook_sent`

确认 outbound webhook pix.in.completed 已成功投递至您的端点。

severity：info
source：client_webhook

QR Code（`qrcode.*`）

`qrcode.created`

通过 POST /v1/accounts/{id}/pix/qr-code/* 创建了动态或静态 QR 码。

severity：info
source：workflow
payload：{txid, accountId, amount, qrType, identifier, expiresAt}

`qrcode.paid`

QR 码已被终端客户支付（接收到 BACEN 信号或通过主动轮询检测到）。

severity：info
source：workflow
payload：{txid, accountId, paidAmount, transactionId, endToEndId, payerDocument, payerName}

`qrcode.client_webhook_sent`

确认 outbound webhook qrcode.paid 已成功投递。

Boleto（`boleto_pay.*`）

`boleto_pay.requested`

通过 POST /v1/accounts/{id}/boleto/pay 发起的 boleto 支付请求已被接收。合作方尚未确认。

severity：info
source：workflow
payload：{boletoId, accountId, line, amount, taxId, scheduled}

`boleto_pay.confirmed`

Stark / 合作方确认 boleto 支付成功。

severity：info
source：workflow
payload：{boletoId, starkId, accountId, amount, line}

`boleto_pay.failed`

Boleto 支付失败。

severity：error
source：workflow
payload：{boletoId, errorReason}

`boleto_pay.client_webhook_sent`

确认 outbound webhook boleto.paid 或 boleto.failed 已投递。

入账退款（`refund.*`）

这些事件出现在退款交易本身的时间线上。被退款的原始交易则在其自有时间线上产生一条 pix_out.refunded 事件，关联退款。

`refund.received`

您的某个账户收到了一笔退款 —— 某方退回了您之前发出的 PIX。

severity：info
source：workflow
payload：{transactionId, refundEndToEndId, originalEndToEndId, accountId, amount}

`refund.confirmed`

退款被标记为成功完成（记录已持久化，余额已退回账户）。

severity：info
source：workflow

`refund.failed`

处理退款的尝试失败（罕见 —— 通常属于运营事故）。

severity：error
source：workflow

后台操作（`backoffice.user_action`）

CorpX 运营人员有时会对某笔交易进行人工干预（审批、调整、策略覆盖等）。此类操作会被记录到时间线。事件始终包含 actor（运营人员邮箱）与 payload.action（语义化的动作字符串）。

severity：info 或 warn（取决于动作类型）
source：backoffice

高级模式（后台）

CorpX 控制台内部提供 ?level=full 模式，返回除公共事件之外的完整 Temporal History（内部决策、活动重试、信号、定时器等）。该模式仅限拥有相应权限的运营人员，不属于公共契约，请勿在客户端代码中依赖该接口。

如果您需要更深层的可观测性（例如 SLA 报表、集成调试），请提交工单 —— 我们可以评估将相关内部事件提升到公共分类。

端点​

过滤参数（query params）​

排序​

契约保证​

公共事件目录​

PIX 转出（pix_out.*）​

pix_out.requested​

pix_out.confirmed​

pix_out.failed​

pix_out.timeout​

pix_out.refunded​

pix_out.client_webhook_sent​

PIX 入账（pix_in.*）​

pix_in.received​

pix_in.client_webhook_sent​

QR Code（qrcode.*）​

qrcode.created​

qrcode.paid​

qrcode.client_webhook_sent​

Boleto（boleto_pay.*）​

boleto_pay.requested​

boleto_pay.confirmed​

boleto_pay.failed​

boleto_pay.client_webhook_sent​

入账退款（refund.*）​

refund.received​

refund.confirmed​

refund.failed​

后台操作（backoffice.user_action）​

高级模式（后台）​

端点