Buscar Transacciones

Descripción General

El endpoint de búsqueda de transacciones permite consultar el historial de transacciones PIX de su cuenta con diversos filtros y paginación. Los datos se devuelven en un formato amigable, con estados y tipos traducidos al portugués y valores en reales.

Autenticación

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

Authorization: Bearer <su_token>

Límite de Solicitudes

GET /api/transactions acepta hasta 30 solicitudes por minuto por cuenta. Por encima de eso, la API responde 429 Too Many Requests; espere el final de la ventana de 1 minuto antes de intentar de nuevo. Para recorrer un período largo, prefiera páginas más grandes (size hasta 100) en lugar de muchas llamadas pequeñas.

Parámetros de Consulta

Mapeo de Campos

Estado

Los estados internos se traducen al formato público:

Tipo de Operación

Los tipos de transacción se traducen al portugués:

Tipo de Movimiento

Indica si la transacción es una entrada o una salida en la cuenta:

Valores

Todos los valores monetarios se devuelven en reales con 2 decimales:

• originalAmount: Valor efectivamente pagado; antes de la confirmación, muestra el valor cobrado
• feeAmount: Tarifa aplicada
• finalAmount: Valor final (original ± tarifa)
• amountPaid: Valor efectivamente pagado; null mientras el pago no se confirma
• mismatchAmount: Diferencia entre el valor cobrado y el pagado; null sin divergencia. Positivo: pagó de menos. Negativo: pagó de más

Enmascaramiento de Documentos

Por seguridad, los documentos de las contrapartes se enmascaran:

• CPF: 123.456.789-00 → ***.456.789-**
• CNPJ: 12.345.678/0001-90 → **.345.678/****-**

Ejemplo de Uso

Buscar todas las transacciones confirmadas

curl -X GET "https://api.fypay.me/api/transactions?status=CONFIRMED&page=1&size=10" \
  -H "Authorization: Bearer su_token_aqui"

const response = await fetch(
  'https://api.fypay.me/api/transactions?status=CONFIRMED&page=1&size=10',
  {
    headers: {
      'Authorization': 'Bearer su_token_aqui'
    }
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.fypay.me/api/transactions',
    params={
        'status': 'CONFIRMED',
        'page': 1,
        'size': 10
    },
    headers={
        'Authorization': 'Bearer su_token_aqui'
    }
)

data = response.json()
print(data)

Buscar transacciones por período

curl -X GET "https://api.fypay.me/api/transactions?startDate=2025-01-01&endDate=2025-01-15&type=PAYMENT" \
  -H "Authorization: Bearer su_token_aqui"

const params = new URLSearchParams({
  startDate: '2025-01-01',
  endDate: '2025-01-15',
  type: 'PAYMENT'
});

const response = await fetch(
  `https://api.fypay.me/api/transactions?${params}`,
  {
    headers: {
      'Authorization': 'Bearer su_token_aqui'
    }
  }
);

Buscar por identificador específico

# Por externalId (su identificador)
curl -X GET "https://api.fypay.me/api/transactions?externalId=order-12345" \
  -H "Authorization: Bearer su_token_aqui"

# Por endToEndId (ID del PIX)
curl -X GET "https://api.fypay.me/api/transactions?endToEndId=E12345678901234567890123456789012" \
  -H "Authorization: Bearer su_token_aqui"

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": "E12345678901234567890123456789012",
      "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": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}

Paginación

La respuesta incluye metadatos de paginación para facilitar la navegación:

Navegación entre páginas

// Primera página
const page1 = await fetchTransactions({ page: 1, size: 20 });

if (page1.metadata.hasNext) {
  // Página siguiente
  const page2 = await fetchTransactions({ page: 2, size: 20 });
}

Casos de Uso Comunes

Códigos de Error

Próximos Pasos