Extratos

Referência

O extrato lista as movimentações financeiras (créditos e débitos) de uma conta ValidaPay: pagamentos recebidos, saques, transferências, taxas e estornos. Este guia explica os campos retornados, como filtrar e paginar, e a diferença entre consultar o extrato de uma subconta e o da master account.

"Extrato subconta" e "Extrato conta master" são o mesmo endpoint

As duas páginas da collection documentam a mesma rota: GET /v1/wallet/transactions. A diferença é só o parâmetro accountId na query string: informado, retorna o extrato da subconta indicada; omitido, retorna o da própria conta autenticada.

O que é o extrato

O extrato retorna uma lista paginada de lançamentos (items) ordenados do mais recente para o mais antigo, junto com informações de paginação. Cada lançamento representa um crédito ou débito no saldo da conta.

Exemplo de resposta (valores e nomes fictícios):

JSON

{
  "items": [
    {
      "transactionId": "txn_1773694940975_r10b6fyzm",
      "type": "CREDIT",
      "category": "PIX_IN",
      "status": null,
      "amount": 2.56,
      "title": "PIX recebido de Empresa Exemplo LTDA",
      "paymentMethod": "PIX",
      "chargeId": null,
      "subscriptionId": null,
      "endToEndId": "E13935893202603162102IfDcitXf0zO",
      "counterparty": {
        "name": "Empresa Exemplo LTDA",
        "bank": "13935893",
        "taxId": "37134852000458",
        "account": "410900056"
      },
      "createdAt": "2026-03-16T21:02:20.975Z"
    }
  ],
  "capabilities": { "showSellerColumn": false },
  "pagination": {
    "total": 42,
    "totalPages": 3,
    "limit": 15,
    "hasMore": true,
    "lastKey": "eyJTSyI6IjIwMjYtMDMtMTZUMjE6MDI6MjAuOTc1WiN0eG5fMTc3MzY5NDk0MDk3NV9yMTBiNmZ5em0iLCJhY2NvdW50SWQiOiI0MjkxMzQ1NjMifQ=="
  }
}

Extrato subconta vs. extrato conta master

	Extrato subconta	Extrato conta master
Endpoint	GET /v1/wallet/transactions	GET /v1/wallet/transactions
Query param accountId	Informado: número da subconta a consultar	Omitido: usa a própria conta autenticada
Titularidade	A subconta precisa pertencer à master do token (senão 404 SUBACCOUNT_NOT_FOUND ou 401 UNAUTHORIZED_SUBACCOUNT)	Não se aplica

Campos de uma transação

Campo	O que é
`transactionId`	Identificador único do lançamento.
`type`	CREDIT (entrada) ou DEBIT (saída).
`category`	Natureza do lançamento. Ver categorias abaixo. Usado também como filtro.
`status`	Status do lançamento quando aplicável (ex.: bloqueios cautelares); null na maioria dos casos.
`amount`	Valor do lançamento, em reais.
`title`	Descrição pronta para exibição, já formatada por categoria e método de pagamento.
`paymentMethod`	PIX, CREDIT_CARD ou BOLETO, quando o lançamento vem de uma cobrança ou saque/transferência.
`chargeId / subscriptionId`	Referência à cobrança ou assinatura de origem, quando existir.
`endToEndId`	Identificador Pix (E2E) do movimento, quando é uma transação Pix.
`pixKey`	Chave Pix envolvida, quando aplicável.
`counterparty`	Dados de quem enviou/recebeu (name, bank, taxId, account) em PIX direto e saques.
`customer`	Dados do cliente pagador (name, taxId, customerId), quando o lançamento vem de uma cobrança.
`grossAmount / feeAmount`	Valor bruto e taxa associada, quando o lançamento tiver desconto de taxa.
`nfNumber`	Número da nota fiscal, em lançamentos de taxa de nota fiscal.
`note`	Anotação livre associada ao lançamento, quando existir.
`createdAt`	Data/hora ISO 8601 do lançamento.

Categorias de lançamento

O valor de category também funciona como filtro (?category=WITHDRAWAL). As mais comuns:

category	Significado
`PAYMENT`	Pagamento de cobrança recebido (Pix, cartão ou boleto).
`PIX_IN`	Pix recebido diretamente, fora de uma cobrança.
`SPLIT_IN`	Valor recebido via split de uma cobrança de outra conta.
`WITHDRAWAL`	Saque enviado por Pix.
`PIX_TRANSFER`	Transferência Pix enviada (fora do fluxo de saque).
`REFUND`	Devolução Pix processada.
`SPLIT_REVERSAL / SPLIT_REVERSAL_RECEIVED`	Estorno de um split, do lado de quem pagou ou de quem recebeu.
`PIX_OUTBOUND_FEE / PIX_OUTBOUND_FEE_COLLECTION`	Taxa de saque ou transferência Pix e sua cobrança.
`NF_FEE`	Taxa de emissão de nota fiscal.
`PROPOSAL_FEE`	Taxa de abertura de conta/subconta.
`CREDIT_SETTLEMENT`	Liquidação de crédito concedido pela ValidaPay.

Filtros e paginação

Parâmetro	Descrição
`accountId`	Número da subconta a consultar. Só é considerado com autenticação client credentials (M2M). Com token de usuário, sempre retorna a própria conta.
`type`	CREDIT ou DEBIT.
`category`	Uma das categorias de lançamento (ver tabela acima).
`startDate / endDate`	Intervalo de datas em ISO 8601, aplicado sobre a data de criação do lançamento.
`search`	Busca por nome do contraparte/cliente (contém, sem diferenciar maiúsculas) ou CPF/CNPJ exato.
`limit`	Itens por página. Padrão 15 quando omitido.
`lastKey`	Cursor de paginação: copie de pagination.lastKey da resposta anterior para buscar a próxima página.

A paginação é por cursor, não por número de página. Sempre use pagination.lastKey da resposta anterior. Não tente calcular um offset manualmente.

Regras importantes

•Valores (amount, grossAmount, feeAmount) vêm sempre em reais, nunca em centavos.
•Um saque só aparece no extrato depois de confirmado. Enquanto está PROCESSING, não existe lançamento.
•Lançamentos de bloqueio cautelar (PIX_IN_PRECAUTIONARY_BLOCK) desaparecem do extrato assim que o Pix correspondente é liberado ou confirmado.
•Lançamentos internos de reconciliação nunca aparecem no extrato: são filtrados antes da resposta.
•Sem startDate/endDate, a consulta retorna o histórico completo da conta, paginado.

Perguntas frequentes

Qual a diferença entre "Extrato subconta" e "Extrato conta master"?▾

Nenhuma na implementação: as duas páginas descrevem o mesmo endpoint GET /v1/wallet/transactions. Enviando accountId na query string (com autenticação client credentials), você consulta o extrato de uma subconta específica; omitindo, consulta a própria conta autenticada.

Como faço para paginar além da primeira página?▾

Pegue o valor de pagination.lastKey na resposta atual e envie de volta como o parâmetro lastKey na próxima chamada. Quando pagination.hasMore for false, não há mais páginas.

Um saque some do extrato antes de ser confirmado?▾

Não aparece nada enquanto o saque está em PROCESSING. O lançamento de débito só é criado no extrato quando a confirmação chega. É por isso que o extrato é a forma recomendada de confirmar um saque.

Por que um PIX recebido às vezes some do extrato?▾

Lançamentos de bloqueio cautelar (categoria PIX_IN_PRECAUTIONARY_BLOCK) são removidos automaticamente do extrato assim que o Pix correspondente é liberado ou confirmado. O saldo já reflete o valor normalmente, só o lançamento de bloqueio some.

Os valores vêm em centavos?▾

Não. amount, grossAmount e feeAmount vêm sempre em reais, com até duas casas decimais (ex.: 10.00).

Próximos passos

Extrato subconta: referência completa do endpoint Extrato conta master: referência completa do endpoint Consultar saldo consolidado Saques: como confirmar um saque pelo extrato

Essa página foi útil?