Listar transações

GET /api/v1/valepix/transactions

Lista as movimentações financeiras disponíveis para a integração autorizada, com paginação e filtros.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Path params

Esta rota não possui path params.

Query params

Parâmetro	Tipo	Obrigatório	Descrição
page	number	Não	Página atual; padrão 1
limit	number	Não	Itens por página; padrão 20 e máximo 100
start_date	string	Não	Data inicial inclusiva no formato YYYY-MM-DD
end_date	string	Não	Data final inclusiva no formato YYYY-MM-DD
type	string	Não	Tipo da movimentação, como DEPOSIT ou TRANSFER
wallet_type	string	Não	Conta de benefício, como livre, alimentacao ou transporte
status	string	Não	Um ou mais estados separados por vírgula, como PENDING, COMPLETED, FAILED, CANCELLED, SCHEDULED ou EXPIRED

Exemplo curl

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/transactions?page=1&limit=20&type=DEPOSIT&status=COMPLETED" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "transactions": [
      {
        "id": "00000000-0000-4000-8000-000000000501",
        "amount": 100000,
        "fee": 250,
        "gross_amount": 100250,
        "type": "DEPOSIT",
        "status": "COMPLETED",
        "to_account_id": "00000000-0000-4000-8000-000000000611",
        "from_account_id": "",
        "description": "Depósito",
        "created_at": "2026-07-23T12:00:00Z",
        "updated_at": "2026-07-23T12:03:00Z",
        "batch_id": "",
        "sender_document": "12345678000190",
        "sender_name": "Empresa Exemplo",
        "sender_name_visible": true,
        "recipient_document": "",
        "recipient_name": "",
        "recipient_name_visible": true,
        "idempotency_key": "",
        "metadata": "",
        "completed_at": "2026-07-23T12:03:00Z",
        "payment_date": "2026-07-23T12:03:00Z",
        "payment_method": "PIX",
        "transfer_method": "",
        "payment_txid": "pix_000000000501",
        "end_to_end": "E0000000020260723120300000000001",
        "payment_expires_at": "2026-07-25T12:00:00Z",
        "wallet_slug": "livre",
        "scheduled_for": "",
        "category": "",
        "cnae": "",
        "cnae_description": "",
        "invoices": [],
        "attachments": []
      }
    ],
    "meta": {
      "total": 1,
      "current_page": 1,
      "last_page": 1,
      "limit": 20
    }
  }
}

Valores monetários são retornados em centavos. Campos sem informação podem vir como string vazia, null ou lista vazia. Use paginação determinística e avance até last_page.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	Filtro, período ou paginação inválida	Corrigir a query string
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
429	Limite de chamadas excedido	Reduzir a frequência das consultas e aplicar backoff
500, 502, 503, 504	Falha temporária na consulta	Tentar novamente com backoff