查询交易状态

GET /api/pix/transaction/{id}

GET https://api.avista.global/api/pix/transaction/{id}

需要在 Authorization 头中提供 Bearer token。请参阅生成令牌获取。

返回 PIX 交易的当前状态，包括金额、对手方和时间戳的详细信息。

标识符可以是：

数字 ID：Avista 返回的内部交易标识符
externalId：您在创建交易时提供的外部标识符

认证

需要在 Authorization 头中提供 Bearer 令牌。

路径参数

参数	类型	必填	描述
`id`	string	是	交易 ID（数字）或 externalId（字符串）

代码示例

cURL

curl -X GET "https://api.avista.global/api/pix/transaction/txn_abc123" \
  -H "Authorization: Bearer $AVISTA_TOKEN"

const axios = require('axios');

const response = await axios.get('https://api.avista.global/api/pix/transaction/txn_abc123', {
  headers: { 'Authorization': `Bearer ${process.env.AVISTA_TOKEN}` },
});
console.log(response.data);

import os, requests

response = requests.get(
    'https://api.avista.global/api/pix/transaction/txn_abc123',
    headers={'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}'},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/transaction/txn_abc123');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/transaction/txn_abc123"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

响应 (200)

字段	类型	描述
`id`	string	交易 ID
`externalId`	string \| null	客户端提供的外部 ID
`type`	string	交易类型：`PAYMENT`、`WITHDRAW`、`REFUND_IN`、`REFUND_OUT`、`TRANSFER`
`status`	string	状态：`PENDING`、`CONFIRMED`、`ERROR`
`originalAmount`	number	原始金额（巴西雷亚尔）
`feeAmount`	number	手续费金额（巴西雷亚尔）
`finalAmount`	number	最终金额（巴西雷亚尔）
`e2eId`	string \| null	PIX End-to-end ID
`counterpartName`	string \| null	对手方名称
`counterpartDocument`	string \| null	对手方证件（CPF/CNPJ）
`counterpartAccountBankCode`	string \| null	对手方银行代码
`counterpartAccountBranch`	string \| null	对手方支行
`counterpartAccountNumber`	string \| null	对手方账号
`counterpartAccountIspb`	string \| null	对手方银行 ISPB
`counterpartAccountBankName`	string \| null	对手方银行名称
`createdAt`	string	创建日期（ISO 8601）
`updatedAt`	string	更新日期（ISO 8601）
`processedAt`	string \| null	处理日期（ISO 8601）
`refunded`	boolean	表示交易是否已退款（部分或全部）。如果至少有一笔已确认（CONFIRMED）的退款关联，则为 true。
`partiallyRefunded`	boolean	表示交易是否被部分退款（`refundedAmount > 0` 且 `refundedAmount < amount`）。
`refundedAmount`	number	已确认退款的金额合计（雷亚尔）。无退款或不可退款类型时为 `0`。
`refundableAmount`	number	可退款余额（雷亚尔）。PENDING/ERROR 或不可退款类型时为 `0`。
`relatedTransactions`	array	关联的交易。双向：PAYMENT/WITHDRAW 返回退款列表（children）；REFUND_IN/REFUND_OUT 返回原交易（parent）。

{
  "id": "123",
  "externalId": "ext-001",
  "type": "PAYMENT",
  "status": "CONFIRMED",
  "originalAmount": 100,
  "feeAmount": 1.5,
  "finalAmount": 98.5,
  "e2eId": "E00416968202512121343VX5Sx8fIpkY",
  "counterpartName": "John Marvin",
  "counterpartDocument": "12312312387",
  "counterpartAccountBankCode": "001",
  "counterpartAccountBranch": "0001",
  "counterpartAccountNumber": "123456-7",
  "counterpartAccountIspb": "00000000",
  "counterpartAccountBankName": "Banco do Brasil",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:35:00.000Z",
  "processedAt": "2026-01-15T10:35:00.000Z",
  "refunded": true,
  "partiallyRefunded": true,
  "refundedAmount": 30,
  "refundableAmount": 70,
  "relatedTransactions": [
    {
      "id": "456",
      "externalId": "ext-refund-001",
      "type": "REFUND_IN",
      "status": "CONFIRMED",
      "amount": 30,
      "e2eId": "E0041696820260120ABCxyz1234567",
      "createdAt": "2026-01-20T14:22:00.000Z"
    }
  ]
}

关联退款

relatedTransactions 字段是双向的：

当您查询 PAYMENT 或 WITHDRAW 交易时，它会列出所有关联的退款（REFUND_IN 或 REFUND_OUT），不论状态。
当您查询 REFUND_IN 或 REFUND_OUT 交易时，它会返回原始 parent 交易（数组中 1 个元素）。
对于其他类型（TRANSFER 或没有已注册关系的交易），返回 []。

只有 status: "CONFIRMED" 的退款会计入 refundedAmount 和 refundableAmount。PENDING 或 ERROR 状态的退款会出现在 relatedTransactions 中，但不影响合计值。

错误

状态码	描述
401	令牌缺失或无效
404	交易未找到