docs
集成指南

按 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.fypay.me/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.fypay.me/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.fypay.me/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)

响应示例

{
  "data": [
    {
      "transactionId": "12345",
      "externalId": "order-abc123",
      "status": "Confirmado",
      "operationType": "Pix in",
      "movementType": "CREDIT",
      "originalAmount": 100.00,
      "feeAmount": 1.00,
      "finalAmount": 99.00,
      "amountPaid": 100.00,
      "mismatchAmount": null,
      "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"
        }
      }
    }
  ],
  "metadata": {
    "page": 1,
    "size": 50,
    "total": 320,
    "totalPages": 7,
    "hasNext": true,
    "hasPrevious": false
  }
}

分页

字段描述
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.fypay.me/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 — FyPay 中交易的内部 ID（仅当值为纯数字时）

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

示例

curl -X GET "https://api.fypay.me/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \
  -H "Authorization: Bearer your_token_here"
curl -X GET "https://api.fypay.me/api/pix/transactions/pix-key/joao%40example.com/order-abc123" \
  -H "Authorization: Bearer your_token_here"
const pixKey = 'joao@example.com';
const identifier = 'E00416968202501151030VX5Sx8fIpkY';

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

if (response.status === 404) {
  console.log('未找到交易');
} else {
  const transaction = await response.json();
  console.log(transaction);
}
import requests
from urllib.parse import quote

pix_key = 'joao@example.com'
identifier = 'E00416968202501151030VX5Sx8fIpkY'

response = requests.get(
    f'https://api.fypay.me/api/pix/transactions/pix-key/{quote(pix_key, safe="")}/{quote(identifier, safe="")}',
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

if response.status_code == 404:
    print('未找到交易')
else:
    transaction = response.json()
    print(transaction)

响应 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,
  "code": "PIX_TRANSACTION_NOT_FOUND",
  "message": "Transaction not found for pixKey=12345678000190 and identifier=E00416968202501151030VX5Sx8fIpkY",
  "userMessage": "Transação não encontrada.",
  "errorId": "<correlation-id>",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/api/pix/transactions/pix-key/12345678000190/E00416968202501151030VX5Sx8fIpkY",
  "method": "GET"
}

字段映射

状态

内部值返回值
PENDINGPendente
CONFIRMEDConfirmado
ERRORError

操作类型

内部值返回值描述
PAYMENTPix in通过 PIX 收款
WITHDRAWPix out通过 PIX 付款
REFUND_INRefund in发起的退款（借记）
REFUND_OUTRefund out收到的退回（贷记）

变动类型

操作类型变动
Pix inCREDIT
Pix outDEBIT
Refund inDEBIT
Refund outCREDIT

与 /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 交易

MED — 特殊退款机制

了解 MED 是什么、如何运作，以及贵公司在 PIX 退款流程中的职责

本页目录

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