按 ID 查询 Cash-Out

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

端点

GET /api/external/transactions/:id

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}

路径参数

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

示例

curl -X GET https://api.minhakonta.com/api/external/transactions/PIXOUT20260309a1b2c3d4e5f6 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

响应根据交易状态而不同。此端点返回 Minha Konta 对所提供标识符已知的最新状态。如果未找到该标识符,返回 404。

按 transaction_id 查询不会返回被拒绝的交易

部分异步拒绝可能无法立即通过 transaction_id 定位。请使用替代端点：

• GET /transactions/e2e/:e2e_id 通过 End-to-End ID 查询
• GET /transactions/ref/:external_id 通过您的外部标识符查询
• Webhook pix.payout.rejected / pix.payout.failed 用于实时通知和完整载荷

输入验证拒绝（立即 400/422）不经过此流程,因为它们已在 POST 中返回同步错误。

---

响应 -- 已结算交易 (200)

{
  "worked": true,
  "data": {
    "id": "c7f3a8b12d4e4f6a9c1b3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "description": "Pagamento fornecedor",
    "counterparty_name": "Joao Silva",
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": "2026-03-09T15:30:02Z"
  }
}

字段	类型	描述
data.id	String	内部交易 ID,可用时为带连字符的规范 UUID 格式
data.transaction_id	String	交易唯一标识。始终读取返回字段,不要从前缀推导规则
data.end_to_end_id	String	SPI/BACEN 的 End-to-End 标识
data.external_id	String	您系统中的标识符。未提供时为 null
data.type	String	交易类型。常见值：pix、pix_return
data.direction	String	资金方向：outbound（cash-out）、inbound（cash-in）、credit 或 debit
data.status	String	归一化状态（见下表）
data.amount	Integer	值,以基础单位（÷ 10.000 得到雷亚尔）。300000 = R$ 30,00
data.fee_amount	Integer	收取的手续费,以基础单位
data.net_amount	Integer	净额,以基础单位
data.description	String	创建时填写的描述
data.counterparty_name	String	对手方姓名（付款方或收款方）
data.recipient_key	String	收款方 PIX 密钥（仅出款）
data.created_at	String	创建日期（ISO 8601）
data.completed_at	String	完成日期（ISO 8601）,待处理时为 null

---

响应 -- 进行中的 PIX OUT (200)

当交易仍在处理时（BACEN 确认之前）返回。

{
  "worked": true,
  "data": {
    "status": "processing",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "external_id": "order-9876",
    "pix_key": "12345678901",
    "description": "Pagamento fornecedor",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "processing",
    "started_at": "2026-03-09T15:30:00Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901",
      "key_type": "cpf"
    }
  }
}

附加字段	类型	描述
data.recipient	Object	通过 DICT 解析的收款方数据
data.recipient.name	String	密钥持有人姓名
data.recipient.key	String	使用的 PIX 密钥
data.recipient.key_type	String	密钥类型（cpf、cnpj、email、phone、evp）
data.started_at	String	处理开始日期（ISO 8601）

---

响应 -- 被拒绝的交易 (200)

由端点 /transactions/e2e/:e2e_id 和 GET /transactions/ref/:external_id 在 PIX 被 SPI 拒绝或处理期间失败时返回。

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AB03",
    "reason_code": "AB03",
    "reason_description": "Aborted by PSP of creditor",
    "started_at": "2026-03-09T15:30:00Z",
    "failed_at": "2026-03-09T15:30:05Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901"
    }
  }
}

附加字段	类型	描述
data.failure_reason	String	拒绝的原始原因（格式：BACEN 代码为 "rejected: {CODE}",或集成描述如 "dict_key_not_found"、"ambiguous key"、"insufficient balance"）
data.reason_code	String	从 failure_reason 提取的结构化代码。对于 BACEN 拒绝,遵循 ISO 20022（AC03、AB03、ED05、DUPL 等）。当 failure_reason 不包含结构化代码时为 null
data.reason_description	String	reason_code 的人类描述,英文。示例："Invalid creditor account number"（AC03）、"Aborted by PSP of creditor"（AB03）、"Settlement failed"（ED05）。代码未识别时为 null
data.recipient	Object	收款方数据（可用时）。在非常早期的故障中可能省略
data.failed_at	String	拒绝日期/时间（ISO 8601）

拒绝代码的结构

使用 reason_code 和 reason_description 进行程序化错误路由。仅将 failure_reason 用于日志和诊断。完整代码表见 PIX Cash-Out 按密钥 -- 错误代码。

---

响应 -- 未付款 QR Code (200)

当 ID 对应于尚未付款的 QR Code 时返回。

{
  "worked": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": null,
    "external_id": "order-9876",
    "type": "pix_qrcode",
    "status": "pending",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Cobrança PIX",
    "direction": "credit",
    "counterparty_name": null,
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": null
  }
}

QR 状态	描述
pending	QR Code 激活,等待付款
settled	QR Code 已付款,但最终交易仍在整合中。不要当作错误处理；几秒钟后重新查询
expired	QR Code 已过期
cancelled	QR Code 已手动取消

注：当 QR 已付款且最终交易已经整合时,响应会变为上面的 "已结算交易" 结构。

---

status 字段的值

GET 状态

GET /transactions/:id 返回用于运营跟踪的归一化状态。

状态	含义
processing	PIX OUT 已接受但尚未完成。可能正在等待 BACEN 确认,或因 DICT 限制等待自动重处理
settled	BACEN 已确认结算,余额已移动。最终成功状态
pending	完成前的罕见中间状态
failed	最终失败状态。被 BACEN 拒绝、自动重处理过期（DICT_QUEUE_TIMEOUT）或运营失败

兼容性说明：遗留记录（在词汇统一之前）可能显示 status: "completed" 或 status: "accepted"。将它们视为等同于 "settled"。

与 webhook 的对应

• pix.payout.queued 在交易等待自动重处理时对应于 GET 中的 status: "processing"
• pix.payout.confirmed 始终对应于 GET 中的 status: "settled"
• pix.payout.failed 和 pix.payout.rejected 始终对应于 GET 中的 status: "failed"

对于 QR Code（cash-in,超出 PIX OUT 范围）,可能的值为 pending、settled、expired 和 cancelled,如上面的 "未付款 QR Code" 部分所述。

错误响应 -- 404

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