> ## Documentation Index > Fetch the complete documentation index at: https://docs.brazilpix.com/llms.txt > Use this file to discover all available pages before exploring further. # 查询交易 > 根据 ID 返回指定交易的详情。 **所需权限：** `TRANSACTION:READ` 或 `FULL_ACCESS` ## OpenAPI ````yaml openapi.cn.json GET /transactions/{id} openapi: 3.0.0 info: title: Brazil Pix API description: Brazil Pix Payment API documentation version: '1.0' contact: {} servers: - url: https://api.brazilpix.com/v2 security: [] paths: /transactions/{id}: get: tags: - External API - Transactions summary: 按 ID 查询交易 description: |- 根据 ID 返回指定交易的详情。 **所需权限：** `TRANSACTION:READ` 或 `FULL_ACCESS` operationId: ExternalTransactionsController_getTransaction parameters: - name: id required: true in: path description: >- 交易 ID（UUID）、您的 external_reference，或创建时使用的 Idempotency-Key。按此顺序解析。仍在处理中的提现（尚未生成交易）同样可以通过其中任意一项查询。 schema: type: string - $ref: '#/components/parameters/SubAccount' responses: '200': description: 交易详情 content: application/json: schema: $ref: '#/components/schemas/GetTransactionOutput' '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: Not Found - Resource not found content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - bearerAuth: [] components: parameters: SubAccount: name: X-Sub-Account in: header required: false description: >- 执行操作的子账户的 reference。省略时，操作在主账户上执行；保留值 `principal` 同样解析为主账户，等同于省略该请求头。除 `POST /auth` 和 `/sub-accounts` 自身的端点（始终在主账户上操作）外，所有端点均接受该请求头。 可能的错误：`404 SUB_ACCOUNT_NOT_FOUND`、`403 SUB_ACCOUNT_FORBIDDEN`、`403 SUB_ACCOUNT_SUSPENDED`。 要求凭证已启用**子账户访问**（设置 → 集成 → API 凭证）。该项默认关闭，任何权限都无法替代，`FULL_ACCESS` 也不例外：未启用时响应为 `403 SUB_ACCOUNT_FORBIDDEN`。 schema: type: string pattern: ^[a-z0-9][a-z0-9_-]{1,31}$ example: loja-centro schemas: GetTransactionOutput: type: object properties: id: type: string description: 交易 ID format: uuid status: type: string description: 交易状态 enum: - pending - completed - failed - cancelled type: type: string description: 交易类型。`internal_transfer` 是同一持有人名下账户之间的资金划转——内部转账或分账明细——不经过 PIX 网络。 enum: - payment - fee - refund - chargeback - withdrawal - adjustment - referral_commission - internal_transfer paymentMethod: type: string description: 使用的支付方式 enum: - pix - credit_card - boleto amount: type: number description: 金额（BRL） example: 150.75 currency: type: string description: 货币代码 example: BRL description: type: string description: 交易描述 externalReference: type: string description: 您的外部参考 ID example: pedido-12345 customerId: type: string description: 客户 ID format: uuid projectId: type: string description: 项目 ID format: uuid metadata: type: object description: 自定义元数据（键值对） additionalProperties: true example: orderId: '12345' source: website pixCopyPaste: type: string description: PIX 复制粘贴码（仅适用于待支付的 PIX 交易） example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 expiresAt: type: string description: 过期时间（仅适用于待支付的交易） format: date-time paidAt: type: string description: 交易支付时间 format: date-time e2eId: type: string description: PIX 网络的端到端 ID（PSP 确认后才存在） example: E18189547202603160145ZYFfVx3jP8D counterpartName: type: string description: PSP 返回的交易对手名称（收款时为付款人，提现时为收款人） example: Maria Silva counterpartDocument: type: string description: 交易对手的 CPF/CNPJ，不带格式符号 example: '12345678900' failureReason: type: string description: 失败原因（仅当 status = failed 时） example: 'Bloqueio de depósito: pagador CNPJ não permitido' blockedDeposit: type: object nullable: true description: >- 当一笔已收到的入账因账户策略被拦截时存在（例如：不允许 CNPJ 付款人）。该金额未入账；`refund` 说明资金是否已退回付款人（状态 pending/confirmed/failed）、退回的 E2E 以及结算时间。 properties: reason: type: string example: cnpj_payer_not_allowed refund: type: object nullable: true properties: status: type: string enum: - pending - confirmed - failed e2eId: type: string nullable: true example: D54811417202609082224L1aDrByinUX settledAt: type: string format: date-time nullable: true createdAt: type: string description: 创建时间 format: date-time updatedAt: type: string description: 更新时间 format: date-time required: - id - status - type - paymentMethod - amount - currency - createdAt UnauthorizedErrorResponse: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication token is required details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp NotFoundErrorResponse: type: object properties: statusCode: type: number example: 404 error: type: string example: NotFound message: type: string example: Resource with id 550e8400-e29b-41d4-a716-446655440000 not found details: type: object example: resource: Example id: 550e8400-e29b-41d4-a716-446655440000 timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp InternalServerErrorResponse: type: object properties: statusCode: type: number example: 500 error: type: string example: InternalError message: type: string example: An unexpected error occurred details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string example: 2771463d58840c8e116dc6dda1e1e5d0 required: - statusCode - error - message - timestamp securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 通过 POST /auth（client_id + client_secret）获取的访问令牌。有效期 300 秒。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.