跳转到主要内容
GET
按 ID 查询交易

授权

Authorization
string
header
必填

通过 POST /auth(client_id + client_secret)获取的访问令牌。有效期 300 秒。

请求头

X-Sub-Account
string

执行操作的子账户的 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。

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
示例:

"loja-centro"

路径参数

id
string
必填

交易 ID(UUID)、您的 external_reference,或创建时使用的 Idempotency-Key。按此顺序解析。仍在处理中的提现(尚未生成交易)同样可以通过其中任意一项查询。

响应

交易详情

id
string<uuid>
必填

交易 ID

status
enum<string>
必填

交易状态

可用选项:
pending,
completed,
failed,
cancelled
type
enum<string>
必填

交易类型。internal_transfer 是同一持有人名下账户之间的资金划转——内部转账或分账明细——不经过 PIX 网络。

可用选项:
payment,
fee,
refund,
chargeback,
withdrawal,
adjustment,
referral_commission,
internal_transfer
paymentMethod
enum<string>
必填

使用的支付方式

可用选项:
pix,
credit_card,
boleto
amount
number
必填

金额(BRL)

示例:

150.75

currency
string
必填

货币代码

示例:

"BRL"

createdAt
string<date-time>
必填

创建时间

description
string

交易描述

externalReference
string

您的外部参考 ID

示例:

"pedido-12345"

customerId
string<uuid>

客户 ID

projectId
string<uuid>

项目 ID

metadata
object

自定义元数据(键值对)

示例:
pixCopyPaste
string

PIX 复制粘贴码(仅适用于待支付的 PIX 交易)

示例:

"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890"

expiresAt
string<date-time>

过期时间(仅适用于待支付的交易)

paidAt
string<date-time>

交易支付时间

e2eId
string

PIX 网络的端到端 ID(PSP 确认后才存在)

示例:

"E18189547202603160145ZYFfVx3jP8D"

counterpartName
string

PSP 返回的交易对手名称(收款时为付款人,提现时为收款人)

示例:

"Maria Silva"

counterpartDocument
string

交易对手的 CPF/CNPJ,不带格式符号

示例:

"12345678900"

failureReason
string

失败原因(仅当 status = failed 时)

示例:

"Bloqueio de depósito: pagador CNPJ não permitido"

blockedDeposit
object | null

当一笔已收到的入账因账户策略被拦截时存在(例如:不允许 CNPJ 付款人)。该金额未入账;refund 说明资金是否已退回付款人(状态 pending/confirmed/failed)、退回的 E2E 以及结算时间。

updatedAt
string<date-time>

更新时间