按 ID 查询 Cash-In

通过交易 ID 查询 PIX 交易的状态和详情。

端点

GET /api/external/transactions/:id

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
X-Key-Case	String	否	设为 camelCase 以使用 camelCase 接收响应字段（默认 snake_case）

路径参数

参数	类型	必填	描述
id	String	是	交易 ID（transaction_id）

示例

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

成功响应 (200)

{
  "worked": true,
  "data": {
    "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": "E37839059202603071530000001",
    "external_id": "order-9876",
    "type": "pix",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Pedido #1234",
    "direction": "inbound",
    "counterparty_name": "Maria Santos",
    "payer_document": "12345678901",
    "recipient_document": "37839059000188",
    "recipient_key": "contato@empresa.com.br",
    "payer_ispb": "60701190",
    "payer_bank_name": "ITAU UNIBANCO S.A.",
    "created_at": "2026-03-07T15:30:00Z",
    "completed_at": "2026-03-07T15:30:02Z"
  }
}

字段	类型	描述
worked	Boolean	true 表示操作成功
data.id	String	交易内部 ID。对已结算的交易（上面的标准结构）,格式是32 字符的十六进制小写字符串,无连字符（例：a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d）。在其他结构中（QR 尚未关联、失败）,字段可能不存在或格式不同（直接从 qrcodes.id 派生时为带连字符的 UUID）
data.transaction_id	String	交易公开标识。对于通过此 pipeline 的 PIX IN,格式为 PIXIN + E2E（例：PIXINE37839059202603071530000001） -- 前缀始终是 PIXIN 后接 E2E 本身（E2E 以 E 开头）。作为不透明标识符使用；不要不小心地通过 string-split 提取 E2E,因为连接没有分隔符
data.end_to_end_id	String	BACEN 的点对点 ID（E2E,格式 ^E\d{8}[a-zA-Z0-9]{22,26}$）
data.external_id	String | null	您系统中的标识符。创建时未提供则为 null
data.type	String	对通过正常 pipeline 已结算的交易为 pix。当查询的 id 只解析到 qrcodes（QR 仍为 pending/expired/cancelled,或 QR 已付款但尚未链接到 transactions 中的最终行 -- 结算后的短窗口）时为 pix_qrcode。收到退款时为 pix_return（见 PIX 退款）
data.status	String	当前状态（见下方表格）
data.amount	Integer	金额,以基础单位（÷ 10.000 得到雷亚尔）。300000 = R$ 30,00
data.fee_amount	Integer	手续费值,以基础单位
data.net_amount	Integer	净额,以基础单位（对 PIX IN,通常 amount - fee_amount）
data.description	String | null	交易描述
data.direction	String	inbound 表示收款,outbound 表示发送
data.counterparty_name	String | null	inbound 时为付款方名称；outbound 时为收款方名称
data.payer_document	String | null	付款方的 CPF/CNPJ。在收款中,当发行方银行发送时存在
data.recipient_document	String | null	收款方的 CPF/CNPJ
data.recipient_key	String | null	收款中使用的 PIX 密钥（evp/email/phone/cpf/cnpj）
data.payer_ispb	String | null	付款方银行的 8 位 ISPB
data.payer_bank_name	String | null	付款方银行名称（从 ISPB 解析）
data.created_at	String	创建日期（UTC 的 ISO 8601）
data.completed_at	String | null	完成日期（UTC 的 ISO 8601）,如果尚未完成则为 null

端点也响应出款

尽管本文档的重点是收款,GET /api/external/transactions/:id 是 PIX IN 和 PIX OUT 的同一端点。当 id 解析为处理中的出款或失败时,响应格式如 按 ID 查询 Cash-Out 所述（status: processing / status: failed 带 reason_code/reason_description）。

可能的状态

status 字段返回的可能值：

状态	来源	描述
settled	transactions	最终成功状态。 付款已收到并记入账户。与 webhook pix.charge.paid 的 status: "paid" 相同。
settled	qrcodes（回退）	当 QR 有 paid_at 但 transactions 中的最终行尚未持久化时也会发出 -- BACEN Phase 2 ACCC 与本地持久化之间的短窗口。在这种情况下 type: "pix_qrcode",某些字段（end_to_end_id、counterparty_name、payer_*）可能仅部分填充
pending	qrcodes	QR Code 已生成,等待付款
expired	qrcodes	QR Code 已过期（TTL 可按账户配置,默认 1h）。对 expires_at 已过但尚未被 worker 处理的 QR 也自动应用
cancelled	qrcodes	QR Code 由 merchant 手动取消（通过门户）或在管理操作中取消（例：2026 年 4 月的大规模静态→动态迁移）
failed	failed_transactions	拒绝的贷记尝试（例：超限、账户封锁、重复、BACEN 拒绝）。reason_code 字段指示结构化原因。

何时发出 failed

尽管不如 cash-out 频繁,收款可能在特定场景失败：ACSP 后 BACEN 拒绝（例：AC03、AM02、DUPL）、超过操作限额、目标账户被封锁或不存在。在这些情况下,记录出现在 failed_transactions 中,direction = "inbound",端点返回以下附加格式（failed 路径独有的字段）：

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXINE37839059202603071530000001",
    "end_to_end_id": "E37839059202603071530000001",
    "amount": 300000,
    "fee_amount": 0,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "inbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AC03",
    "reason_code": "AC03",
    "reason_description": "Invalid creditor account number",
    "started_at": "2026-03-07T15:30:00Z",
    "failed_at": "2026-03-07T15:30:02Z",
    "recipient": {
      "name": "Empresa Exemplo LTDA",
      "key": "contato@empresa.com.br"
    }
  }
}

当您按 QR 的 tx_id 查询且 QR 尚未付款时,端点返回 pending/expired/cancelled（从 qrcodes 派生,transactions 中无行）。在这种情况下载荷简化：id、transaction_id（= tx_id）、amount、status、description、recipient_key（QR 的 PIX 密钥）、type: "pix_qrcode"、direction: "credit"、created_at（QR 生成时）和 completed_at（付款时,或 null）。此结构中 counterparty_name 为 null（仅在 transactions 中有实际行时才填充）。

关于批量取消的说明：在 2026 年 4 月静态到动态 QR 迁移期间,一批带固定值的活跃静态 QR 被管理性取消（状态 cancelled）。查询正常返回此状态；无需特殊处理。

错误响应 (404)

{
  "worked": false,
  "detail": "Transação não encontrada"
}

错误响应 (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

轮询 vs Webhook

要跟踪收款状态,请优先使用 Webhooks 而不是轮询。如果需要查询,请使用至少 5 秒的间隔。