docs
Guías de Integración

Transacciones por Clave PIX

Descripción General

Los endpoints de transacciones por clave PIX permiten consultar el historial de transacciones asociadas a una clave PIX específica (CPF, CNPJ, teléfono, e-mail o clave aleatoria EVP). Son ideales para escenarios como:

  • Conciliación por clave: verificar todas las recepciones de un CNPJ o CPF específico
  • Auditoría: auditar los movimientos de una clave PIX en un período
  • Monitoreo de recepciones: seguir los pagos recibidos vía una clave específica

Comparado con el endpoint general /api/transactions, la diferencia principal es el filtro obligatorio por clave PIX y el size máximo mayor: hasta 1000 registros por página (vs. 100 en el endpoint general). La consulta devuelve como máximo 1000 resultados en total — si la clave tiene más transacciones en el período, use filtros de type, status o períodos más cortos para refinar.

Autenticación

Este endpoint requiere un token Bearer válido en el header Authorization:

Authorization: Bearer <su_token>

El token debe obtenerse a través del endpoint Generar Token.

Tipos de Clave PIX Soportados

TipoFormatoEjemplo
CPFSolo números (11 dígitos)12345678900
CNPJSolo números (14 dígitos)12345678000190
TeléfonoFormato E.164 con + codificado como %2B%2B5511999999999
E-mailDirección de e-mail válidajoao@example.com
Clave aleatoria (EVP)UUID v4550e8400-e29b-41d4-a716-446655440000

Al usar claves con caracteres especiales en la URL (como + en el teléfono), aplique siempre URL encoding. En los ejemplos de código, encodeURIComponent (JavaScript) y quote(..., safe="") (Python) lo hacen automáticamente.

Endpoint 1: Listar Transacciones por Clave PIX

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

Parámetros

ParámetroTipoObligatorioPredeterminadoDescripción
pixKeystring✓ (path)—Clave PIX (URL-encoded)
pageinteger—1Número de página
sizeinteger—20Registros por página (máx. 1000)
statusstring——PENDING, CONFIRMED o ERROR
typestring——PAYMENT, WITHDRAW, REFUND_IN o REFUND_OUT
startDatedate—Últimos 30 díasFecha inicial (ISO 8601)
endDatedate—HoyFecha final (ISO 8601)

El intervalo entre startDate y endDate no puede exceder 31 días. La consulta devuelve como máximo 1000 resultados — si hay más transacciones en el período, use filtros adicionales (type, status, o períodos más cortos) para refinar.

Clave sin resultados

Si la pixKey informada no tiene transacciones en el período consultado, la API devuelve HTTP 200 con data vacío:

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

Ejemplos

curl -X GET "https://api.fypay.me/api/pix/transactions/pix-key/joao%40example.com?status=CONFIRMED&page=1&size=50" \
  -H "Authorization: Bearer su_token_aqui"
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 su_token_aqui'
    }
  }
);

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 su_token_aqui'
    }
)

data = response.json()
print(data)

Ejemplo de Respuesta

{
  "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
  }
}

Paginación

CampoDescripción
pagePágina actual
sizeCantidad de registros por página
totalTotal de registros encontrados (máx. 1000)
totalPagesTotal de páginas disponibles
hasNextIndica si existe una página siguiente
hasPreviousIndica si existe una página anterior

Para obtener todos los resultados de una vez, use size=1000. Para procesar en lotes, recorra las páginas mientras hasNext sea 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 su_token_aqui' } }
    );
    const { data, metadata } = await response.json();
    results.push(...data);
    if (!metadata.hasNext) break;
    page++;
  } while (true);

  return results;
}

Endpoint 2: Consultar Transacción por Clave PIX e Identificador

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

Parámetros

ParámetroTipoObligatorioDescripción
pixKeystring✓Clave PIX (URL-encoded)
identifierstring✓Identificador de la transacción (URL-encoded)

El identifier se compara simultáneamente contra tres campos de la transacción:

  • endToEndId — End-to-End ID del PIX (ej.: E00416968202501151030VX5Sx8fIpkY)
  • externalId — Identificador externo proporcionado en la creación de la transacción
  • id numérico — ID interno de la transacción en FyPay (solo si el valor es puramente numérico)

En la práctica no hay ambigüedad: el formato de cada tipo de identificador es único (el e2eId comienza con E seguido de 32 caracteres alfanuméricos; el id es puramente numérico; el externalId es cualquier string).

Ejemplos

curl -X GET "https://api.fypay.me/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \
  -H "Authorization: Bearer su_token_aqui"
curl -X GET "https://api.fypay.me/api/pix/transactions/pix-key/joao%40example.com/order-abc123" \
  -H "Authorization: Bearer su_token_aqui"
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 su_token_aqui'
    }
  }
);

if (response.status === 404) {
  console.log('Transacción no encontrada');
} 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 su_token_aqui'
    }
)

if response.status_code == 404:
    print('Transacción no encontrada')
else:
    transaction = response.json()
    print(transaction)

Respuesta 200 — Transacción Encontrada

{
  "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"
    }
  }
}

Respuesta 404 — No Encontrada

Se devuelve cuando ninguna transacción corresponde al identifier informado para la pixKey especificada.

{
  "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"
}

Mapeo de Campos

Estado

Valor InternoValor Devuelto
PENDINGPendente
CONFIRMEDConfirmado
ERRORError

Tipo de Operación

Valor InternoValor DevueltoDescripción
PAYMENTPix inRecepción vía PIX
WITHDRAWPix outPago vía PIX
REFUND_INRefund inDevolución solicitada (débito)
REFUND_OUTRefund outDevolución recibida (crédito)

Tipo de Movimiento

Tipo de OperaciónMovimiento
Pix inCREDIT
Pix outDEBIT
Refund inDEBIT
Refund outCREDIT

Diferencias con /api/transactions

Aspecto/api/transactions/api/pix/transactions/pix-key/\{pixKey\}
Filtro principalToda la cuentaPor clave PIX específica
Máx. size por página1001000
Máx. resultados totalesSin límite1000
startDate predeterminadoÚltimos 31 díasÚltimos 30 días
Clave inexistente / sin resultados200 con lista vacía200 con lista vacía
Búsqueda por externalIdQuery param ?externalId=Path param /\{identifier\}
Búsqueda por endToEndIdQuery param ?endToEndId=Path param /\{identifier\}

Casos de Uso

Códigos de Error

CódigoDescripción
400Parámetros inválidos, fechas invertidas, o intervalo superior a 31 días
401Token no proporcionado o inválido
404Transacción no encontrada (solo en el endpoint /\{pixKey\}/\{identifier\})

Próximos Pasos

Buscar Transacciones

Consulte las transacciones generales de la cuenta con filtros avanzados

Consultar Estado

Verifique el estado detallado de una transacción específica

Configurar Webhooks

Reciba notificaciones automáticas cuando lleguen transacciones

Buscar Transacciones

Consulte y filtre las transacciones PIX de su cuenta con paginación

MED — Mecanismo Especial de Devolución

Entienda qué es el MED, cómo funciona y cuál es el rol de su empresa en el flujo de devolución PIX

En esta página

Descripción GeneralAutenticaciónTipos de Clave PIX SoportadosEndpoint 1: Listar Transacciones por Clave PIXParámetrosClave sin resultadosEjemplosEjemplo de RespuestaPaginaciónEndpoint 2: Consultar Transacción por Clave PIX e IdentificadorParámetrosEjemplosRespuesta 200 — Transacción EncontradaRespuesta 404 — No EncontradaMapeo de CamposEstadoTipo de OperaciónTipo de MovimientoDiferencias con /api/transactionsCasos de UsoCódigos de ErrorPróximos Pasos