按 External ID 查询交易

通过 external_id（您的系统在创建时（cash-in 或 cash-out）定义的标识符）查询交易。

端点

GET /api/external/transactions/ref/:external_id

请求头

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

路径参数

参数	类型	必填	描述
`external_id`	String	是	创建交易时定义的外部标识符

何时使用

此端点用于您的系统与 Owem Pay 之间的对账。无需存储 Owem 的 transaction_id,直接通过您的订单号、发票或内部参考查询。

示例

bash

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

响应结构

响应因交易状态而不同。下面有 4 种可能的结构。

结构 1 -- 已结算交易 (`status: "settled"`)

当交易已结算并持久化到 transactions 表时返回。

json

{
  "worked": true,
  "data": {
    "id": "c7f3a8b1-2d4e-4f6a-9c1b-3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E37839059202603091530abcdef01",
    "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",
    "payer_document": null,
    "recipient_document": "12345678901",
    "payer_ispb": null,
    "payer_bank_name": null,
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": "2026-03-09T15:30:02Z"
  }
}

字段（顶级）	类型	描述
`id`	String	交易内部 UUID
`transaction_id`	String	交易公开标识
`end_to_end_id`	String	BACEN 的 E2E ID
`external_id`	String	您系统中的标识符
`type`	String	`pix`、`ted`、`internal`
`direction`	String	`inbound` 或 `outbound`
`status`	String	交易状态（见 pix-lifecycle）
`amount`	Integer	值,以基础单位（÷ 10.000 得到雷亚尔）
`fee_amount`	Integer	收取的手续费,以基础单位
`net_amount`	Integer	净额,以基础单位
`description`	String	交易描述
`counterparty_name`	String	对手方姓名
`recipient_key`	String	收款方 PIX 密钥（仅 outbound）
`payer_document`	String	付款方 CPF/CNPJ（inbound）。outbound 为 `null`
`recipient_document`	String	收款方 CPF/CNPJ（outbound）。inbound 为 `null`
`payer_ispb`	String	付款机构 ISPB（inbound）。outbound 为 `null`
`payer_bank_name`	String	付款银行名称（inbound）。outbound 为 `null`
`created_at`	String	创建日期（ISO 8601）
`completed_at`	String	完成日期（ISO 8601）

结构 2 -- 处理中交易 (`status: "processing"`)

当交易在 outbound_requests 中等待 BACEN 响应时返回（尚未结算或失败）。

json

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

字段	类型	描述
`transaction_id`	String	公开标识（前缀 `PIXOUT`）
`end_to_end_id`	String	BACEN 的 E2E ID
`external_id`	String	您系统中的标识符
`amount`	Integer	值,以基础单位（÷ 10.000 得到雷亚尔）
`fee_amount`	Integer	手续费,以基础单位
`net_amount`	Integer	`amount + fee_amount`,以基础单位
`status`	String	此结构中始终为 `"processing"`
`payment_status`	String	`status` 的镜像,用于兼容性
`type`	String	`pix`、`ted`、`internal`
`direction`	String	`outbound`（飞行中 PIX OUT 的独占结构）
`pix_key`	String	收款方 PIX 密钥
`description`	String	请求中填写的描述
`started_at`	String	请求进入队列的时刻（ISO 8601）

中间结构

processing 交易在 BACEN 飞行中。不要将此状态视为最终 — 等待 webhook pix.payout.confirmed 或 pix.payout.failed。隔离中的操作（stage=5,无 BACEN 响应 >30min）也返回 "processing" — 见 pix-lifecycle。

结构 3 -- 失败交易

当交易在 failed_transactions 中（被 BACEN 拒绝或内部故障）时返回。

json

{
  "worked": true,
  "data": {
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E37839059202603091530abcdef01",
    "external_id": "order-9876",
    "amount": 300000,
    "status": "failed",
    "type": "pix",
    "direction": "outbound",
    "reason_code": "AC03",
    "reason_description": "Invalid creditor account number",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901"
    },
    "failed_at": "2026-03-09T15:30:02Z"
  }
}

额外字段	类型	描述
`reason_code`	String	BACEN/provider 代码（例：`AC03`、`ED05`、`AM02`）
`reason_description`	String	英文描述
`recipient`	Object	收款方的 `{name, key}`
`failed_at`	String	故障日期（ISO 8601）

结构 4 -- QR 码 (cash-in)

当 external_id 在收款 QR 码中注册时返回（已付款或未付款）。用作 transactions 和 outbound_requests 中无行时的回退。

json

{
  "worked": true,
  "data": {
    "id": "e9f3df72-031f-49bf-abc3-a9ce1d540726",
    "tx_id": "smyoka2zd5xowvqq2hea",
    "pix_key": "evp-xxxx-xxxx-xxxx",
    "amount": 100000,
    "fee_amount": 0,
    "status": "paid",
    "external_id": "order-9876",
    "description": "Pedido #1234",
    "end_to_end_id": "E37839059202604101607b2fc9d8b4c6b",
    "direction": "inbound",
    "type": "pix_qrcode",
    "created_at": "2026-04-10T16:00:00Z",
    "paid_at": "2026-04-10T16:07:08Z"
  }
}

字段	类型	描述
`id`	String	QR 码 UUID
`tx_id`	String	BACEN `txId`（SPI 中 QR 的标识符）
`pix_key`	String	QR 中收款方的 PIX 密钥
`amount`	Integer	QR 值,以基础单位（QR 无定义值时为 `0`）
`fee_amount`	Integer	QR 码中始终为 `0`（手续费在结算时收取）
`status`	String	`paid`、`pending`、`expired`、`cancelled`
`external_id`	String	您系统中的标识符
`description`	String	QR 创建时填写的描述
`end_to_end_id`	String	结算 QR 的 PIX 的 E2E（仅在 `status=paid` 时）。否则 `null`。
`direction`	String	QR 码始终为 `"inbound"`
`type`	String	始终为 `"pix_qrcode"`
`created_at`	String	QR 创建时刻（ISO 8601）
`paid_at`	String	付款时刻（ISO 8601）。未付款则为 `null`。

所有货币值都以基础单位（÷ 10.000 得到雷亚尔）。

搜索优先级

后端按以下顺序搜索 external_id：(1) transactions → 结构 1、(2) 飞行中的 outbound_requests → 结构 2、(3) failed_transactions → 结构 3、(4) qrcodes → 结构 4。第一个包含 ID 的表获胜。

结构之间的差异（对客户端 parser 很重要）

4 种结构共享某些字段（例：transaction_id、end_to_end_id、external_id、amount、status、type、direction）但没有相同的字段集：

结构 1（settled）：18 个字段,包括 fee_amount、net_amount、payer_document、payer_ispb、payer_bank_name、recipient_document、recipient_key、counterparty_name
结构 2（processing）：13 个字段 — 不携带对手方数据（缺少 payer_document、payer_ispb、recipient_document）,仅 outbound_requests 中的内容
结构 3（failed）：携带 reason_code + reason_description + 嵌套的 recipient.{name, key} 对象（注意：不是平铺的 recipient_document）
结构 4（QR 码）：不同的 schema — 有 tx_id、paid_at、pix_key,始终 direction="inbound" 和 type="pix_qrcode"

建议：先检查 data.status；使用 switch/case 分发到 4 个不同的 parser。不要假设跨结构的字段存在。

官方凭证

要生成格式化的凭证（PDF 就绪,包含机构数据和格式化的 BRL 值）,请在结算后使用 GET /api/external/transactions/:id/receipt — /transactions/ref/:external_id 端点提供用于程序化对账的原始数据,不是视觉格式。

错误响应 -- 404

json

{
  "worked": false,
  "errors": {
    "not_found": "Transação não encontrada para o external_id informado"
  }
}

错误响应 -- 401

json

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

唯一性

external_id 在账户内不唯一。如果多笔交易具有相同的 external_id,端点返回最新的一笔。我们建议使用唯一值以便于对账。

按 External ID 查询交易 ​

端点 ​

请求头 ​

路径参数 ​

示例 ​

响应结构 ​

结构 1 -- 已结算交易 (status: "settled") ​

结构 2 -- 处理中交易 (status: "processing") ​

结构 3 -- 失败交易 ​

结构 4 -- QR 码 (cash-in) ​

错误响应 -- 404 ​

错误响应 -- 401 ​

按 External ID 查询交易

端点

请求头

路径参数

示例

响应结构

结构 1 -- 已结算交易 (`status: "settled"`)

结构 2 -- 处理中交易 (`status: "processing"`)

结构 3 -- 失败交易

结构 4 -- QR 码 (cash-in)

错误响应 -- 404

错误响应 -- 401