NTX Paydocs
集成指南

按 PIX 密钥查询交易

概述

按 PIX 密钥查询交易的端点允许您查询与特定 PIX 密钥（CPF、CNPJ、手机号、邮箱或随机 EVP 密钥）关联的交易历史。适用于以下场景：

  • 按密钥对账：验证特定 CNPJ 或 CPF 的所有收款
  • 审计：审计特定时间段内某个 PIX 密钥的资金变动
  • 收款监控：追踪通过特定密钥收到的付款

与通用 /api/transactions 端点相比，主要区别在于强制的 PIX 密钥筛选和更大的 size 上限：每页最多 1000 条记录（通用端点为 100 条）。查询最多返回 1000 条结果 -- 如果该密钥在该时间段内有更多交易，请使用 type、status 或更短的时间段筛选来缩小范围。

认证

此端点需要在 Authorization 请求头中提供有效的 Bearer token：

Authorization: Bearer <your_token>

令牌必须通过生成令牌端点获取。

支持的 PIX 密钥类型

类型格式示例
CPF仅数字（11 位）12345678900
CNPJ仅数字（14 位）12345678000190
手机号E.164 格式，+ 编码为 %2B%2B5511999999999
邮箱有效的邮箱地址joao@example.com
随机密钥 (EVP)UUID v4550e8400-e29b-41d4-a716-446655440000

在 URL 中使用包含特殊字符的密钥时（如手机号中的 +），请始终进行 URL 编码。在代码示例中，encodeURIComponent（JavaScript）和 quote(..., safe="")（Python）会自动处理。

端点 1：按 PIX 密钥列出交易

GET /api/pix/transactions/pix-key/{pixKey}

参数

参数类型必填默认值描述
pixKeystring是（路径）--PIX 密钥（URL 编码）
pageinteger--1页码
sizeinteger--20每页记录数（最大 1000）
statusstring----PENDING、CONFIRMED 或 ERROR
typestring----PAYMENT、WITHDRAW、REFUND_IN 或 REFUND_OUT
startDatedate--最近 30 天开始日期（ISO 8601）
endDatedate--今天结束日期（ISO 8601）

startDate 和 endDate 之间的间隔不能超过 31 天。查询最多返回 1000 条结果 -- 如果该时间段内有更多交易，请使用附加筛选（type、status 或更短的时间段）缩小范围。

无结果的密钥

如果提供的 pixKey 在查询时间段内没有交易，API 返回 HTTP 200 和空 data：

{
  "data": [],
  "metadata": { "page": 1, "size": 20, "total": 0, "totalPages": 0, "hasNext": false, "hasPrevious": false }
}

示例

curl -X GET "https://api.ntxpay.com/api/pix/transactions/pix-key/joao%40example.com?status=CONFIRMED&page=1&size=50" \
  -H "Authorization: Bearer your_token_here"
const pixKey = 'joao@example.com';
const params = new URLSearchParams({
  status: 'CONFIRMED',
  page: '1',
  size: '50'
});

const response = await fetch(
  `https://api.ntxpay.com/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
  {
    headers: {
      'Authorization': 'Bearer your_token_here'
    }
  }
);

const data = await response.json();
console.log(data);
import requests
from urllib.parse import quote

pix_key = 'joao@example.com'

response = requests.get(
    f'https://api.ntxpay.com/api/pix/transactions/pix-key/{quote(pix_key, safe="")}',
    params={
        'status': 'CONFIRMED',
        'page': 1,
        'size': 50
    },
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

data = response.json()
print(data)

分页

字段描述
page当前页码
size每页记录数
total找到的总记录数（最大 1000）
totalPages可用总页数
hasNext是否有下一页
hasPrevious是否有上一页

要一次获取所有结果，使用 size=1000。要分批处理，在 hasNext 为 true 时遍历页面：

async function getAllTransactions(pixKey, filters = {}) {
  const results = [];
  let page = 1;

  do {
    const params = new URLSearchParams({ ...filters, page, size: 100 });
    const response = await fetch(
      `https://api.ntxpay.com/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
      { headers: { 'Authorization': 'Bearer your_token_here' } }
    );
    const { data, metadata } = await response.json();
    results.push(...data);
    if (!metadata.hasNext) break;
    page++;
  } while (true);

  return results;
}

端点 2：按 PIX 密钥和标识符查询交易

GET /api/pix/transactions/pix-key/{pixKey}/{identifier}

参数

参数类型必填描述
pixKeystring是PIX 密钥（URL 编码）
identifierstring是交易标识符（URL 编码）

identifier 同时与三个交易字段进行比较：

  • endToEndId -- PIX End-to-End ID（例如：E00416968202501151030VX5Sx8fIpkY）
  • externalId -- 创建交易时提供的外部标识符
  • id（数字） -- Avista 内部交易 ID（仅当值为纯数字时）

实际上不存在歧义：每种标识符类型都有唯一的格式（e2eId 以 E 开头后跟 32 个字母数字字符；id 为纯数字；externalId 为任意字符串）。

响应 200 -- 找到交易

{
  "transactionId": "12345",
  "externalId": "order-abc123",
  "status": "Confirmado",
  "operationType": "Pix in",
  "movementType": "CREDIT",
  "originalAmount": 100.00,
  "feeAmount": 1.00,
  "finalAmount": 99.00,
  "endToEndId": "E00416968202501151030VX5Sx8fIpkY",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "processedAt": "2025-01-15T10:30:05.000Z",
  "counterpart": {
    "name": "João Silva",
    "document": "***.456.789-**",
    "bank": {
      "bankISPB": "00000000",
      "bankName": "Banco do Brasil",
      "bankCode": "001",
      "accountBranch": "0001",
      "accountNumber": "123456-7"
    }
  }
}

响应 404 -- 未找到

当指定 pixKey 的 identifier 没有匹配的交易时返回。

{
  "statusCode": 404,
  "message": "Transação não encontrada"
}

与 /api/transactions 的区别

方面/api/transactions/api/pix/transactions/pix-key/\{pixKey\}
主要筛选整个账户按特定 PIX 密钥
每页最大 size1001000
最大总结果数无限制1000
默认 startDate最近 31 天最近 30 天
不存在的密钥/无结果200 返回空列表200 返回空列表
按 externalId 查询查询参数 ?externalId=路径参数 /\{identifier\}
按 endToEndId 查询查询参数 ?endToEndId=路径参数 /\{identifier\}

使用场景

错误码

状态码描述
400参数无效、日期顺序错误或间隔超过 31 天
401未提供令牌或令牌无效
404交易未找到（仅 /\{pixKey\}/\{identifier\} 端点）

后续步骤

查询交易

使用高级筛选查询账户的通用交易

查询状态

查询特定交易的详细状态

配置 Webhooks

在交易到达时接收自动通知

查询交易

查询和筛选您账户的 PIX 交易并支持分页

沙盒测试

模拟错误和延迟场景以测试您的集成

本页目录

概述认证支持的 PIX 密钥类型端点 1：按 PIX 密钥列出交易参数无结果的密钥示例分页端点 2：按 PIX 密钥和标识符查询交易参数响应 200 -- 找到交易响应 404 -- 未找到与 /api/transactions 的区别使用场景错误码后续步骤