> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Extrato do recebedor
> Extrato paginado do recebedor, com filtros por natureza do lançamento, direção, origem, moeda, disponibilidade e período.
`GET /wallets/owner/{ownerId}/transactions`
Faz parte do recurso [Carteiras](/pt-BR/wallets) — o que cada saldo significa está lá.
Retorna o extrato **do lançamento mais recente para o mais antigo**, consolidando todas as
carteiras do recebedor; cada lançamento traz a própria moeda. A página vem com `limit` `20` por
padrão e aceita até `100` — confira `pagination.totalPages` antes de concluir que o extrato
acabou. Todos os filtros são opcionais e podem ser combinados; as datas seguem **ISO 8601 com
timezone** (veja [Convenções](/pt-BR/convencoes)).
**Filtro com valor inválido responde `400`, não é ignorado.** `?flow=entrada` recusa a
requisição inteira, sem devolver resultado parcial.
**Débito vem com `amount` negativo.** O sinal acompanha o `flow`: `credit` é positivo, `debit`
é negativo — uma taxa aparece como `flow: "debit"` com `amount: -12500`. Somar o `amount` de
todos os lançamentos dá o efeito líquido direto; não aplique o `flow` por cima do sinal, ou
todo débito conta em dobro.
**`releaseStatus` separa o que já dá para sacar.** `released` é o que está disponível;
`pending` ainda está no prazo de liberação e o campo `scheduledFor` diz quando cai. O saldo
sacável não é a soma do extrato inteiro.
**Para reconstruir um pedido**, filtre por `transactionId`: a venda, as taxas e eventuais
estornos daquela transação vêm juntos, e é assim que se explica a diferença entre o valor da
venda e o que entrou na carteira.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/wallets/owner/rec_tazseadvfg6aym95njwzvc6fs/transactions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "releaseStatus=released" \
--data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "wtx_rjxtclwyb5pq7jzios7kgonna",
"type": "sale",
"flow": "credit",
"amount": 250000,
"currency": "BRL",
"scheduledFor": "2026-06-25T00:00:00.000Z",
"entityId": "txn_behjghpqfcnfp2ufpi33kei4v",
"entityType": "transaction",
"description": "Venda - pedido #1042",
"installmentNumber": null,
"createdAt": "2026-06-10T14:32:00.000Z"
},
{
"id": "wtx_egdpubba2i9ucnwxgopbo1dp4",
"type": "fee",
"flow": "debit",
"amount": -12500,
"currency": "BRL",
"scheduledFor": null,
"entityId": "txn_behjghpqfcnfp2ufpi33kei4v",
"entityType": "transaction",
"description": "Taxa de processamento",
"installmentNumber": null,
"createdAt": "2026-06-10T14:32:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 84,
"totalPages": 5
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /wallets/owner/{ownerId}/transactions
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/wallets/owner/{ownerId}/transactions:
get:
tags:
- Wallets
summary: Extrato do recebedor
description: >-
Retorna o extrato paginado consolidando todas as carteiras do recipient.
Cada lançamento traz sua currency; filtros por natureza do lançamento,
direção, origem, moeda, disponibilidade e período
operationId: WalletController_listTransactions
parameters:
- name: types
in: query
required: false
description: >-
Natureza do lançamento: `sale`, `refund`, `chargeback`,
`chargeback_reversal`, `pending_refund`, `pending_refund_reversal`,
`anticipation`, `fee`, `withdrawal`, `adjustment`, `manual` ou
`transfer`. Aceita vários valores separados por vírgula e tem
precedência sobre `type`.
schema:
type: array
items:
type: string
enum:
- sale
- refund
- chargeback
- chargeback_reversal
- pending_refund
- pending_refund_reversal
- anticipation
- fee
- withdrawal
- adjustment
- manual
- transfer
description: >-
Natureza do lançamento: `sale`, `refund`, `chargeback`,
`chargeback_reversal`, `pending_refund`,
`pending_refund_reversal`, `anticipation`, `fee`, `withdrawal`,
`adjustment`, `manual` ou `transfer`. Aceita vários valores
separados por vírgula e tem precedência sobre `type`.
- name: flow
in: query
required: false
description: >-
Direção do lançamento: `credit` (entrada) ou `debit` (saída).
Débitos vêm com `amount` negativo — o sinal e o `flow` contam a
mesma coisa.
schema:
type: string
enum:
- credit
- debit
nullable: true
description: >-
Direção do lançamento: `credit` (entrada) ou `debit` (saída).
Débitos vêm com `amount` negativo — o sinal e o `flow` contam a
mesma coisa.
- name: source
in: query
required: false
description: >-
Origem do lançamento: `psp_import` (recebido do adquirente),
`platform_calc` (calculado na liquidação) ou `manual` (ajuste
lançado por um operador).
schema:
type: string
enum:
- psp_import
- platform_calc
- manual
nullable: true
description: >-
Origem do lançamento: `psp_import` (recebido do adquirente),
`platform_calc` (calculado na liquidação) ou `manual` (ajuste
lançado por um operador).
- name: currency
in: query
required: false
description: 'Moeda no padrão ISO 4217 (ex.: `BRL`). Um valor por requisição.'
schema:
type: string
nullable: true
description: 'Moeda no padrão ISO 4217 (ex.: `BRL`). Um valor por requisição.'
- name: releaseStatus
in: query
required: false
description: >-
Disponibilidade do valor: `released` (já disponível para saque) ou
`pending` (ainda a liberar).
schema:
type: string
enum:
- released
- pending
nullable: true
description: >-
Disponibilidade do valor: `released` (já disponível para saque) ou
`pending` (ainda a liberar).
- name: startDate
in: query
required: false
description: >-
Traz lançamentos criados a partir deste instante (ISO 8601 com
timezone), inclusive.
schema:
type: string
format: date-time
nullable: true
description: >-
Traz lançamentos criados a partir deste instante (ISO 8601 com
timezone), inclusive.
- name: endDate
in: query
required: false
description: >-
Traz lançamentos criados até este instante (ISO 8601 com timezone),
inclusive.
schema:
type: string
format: date-time
nullable: true
description: >-
Traz lançamentos criados até este instante (ISO 8601 com
timezone), inclusive.
- name: transactionId
in: query
required: false
description: >-
Retorna os lançamentos originados desta transação (`txn_`).
Correspondência exata — útil para reconstruir venda, taxas e
estornos de um mesmo pedido.
schema:
type: string
minLength: 1
nullable: true
description: >-
Retorna os lançamentos originados desta transação (`txn_`).
Correspondência exata — útil para reconstruir venda, taxas e
estornos de um mesmo pedido.
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: ownerId
in: path
required: true
description: ID do recebedor
schema:
type: string
responses:
'200':
description: Lista paginada de lançamentos
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
type:
type: string
description: >-
sale, refund, chargeback, chargeback_reversal,
pending_refund, pending_refund_reversal,
anticipation, fee, withdrawal, adjustment, manual,
transfer
flow:
type: string
description: >-
Direção do lançamento: credit entra na carteira,
debit sai. Débitos vêm com amount negativo.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
scheduledFor:
type: string
format: date-time
nullable: true
description: >-
Data e hora prevista para liberação do lançamento
(ISO 8601).
entityId:
type: string
nullable: true
description: >-
ID da entidade relacionada ao registro (ex.:
transação, venda).
entityType:
type: string
nullable: true
description: >-
Tipo da entidade relacionada ao registro (ex.:
transaction, sale).
description:
type: string
nullable: true
description: Descrição do registro.
installmentNumber:
type: integer
nullable: true
description: Número da parcela referente ao lançamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: wtx_ehhx0od2vo18mq28n9h9npcjx
type: sale
flow: credit
amount: 49900
currency: BRL
scheduledFor: '2025-07-15T13:45:30.000Z'
entityId: rcv_h2wq8tz4mxk9rpf5snc7ydv3b
entityType: receivable
description: null
installmentNumber: 1
createdAt: '2025-06-29T13:45:30.000Z'
- id: wtx_ovpw4jyq10b8pn6n07elun2de
type: withdrawal
flow: debit
amount: -25000
currency: BRL
scheduledFor: null
entityId: wdr_z4hq8wt2mxk9rpf5snc7ydv3b
entityType: withdrawal
description: null
installmentNumber: null
createdAt: '2025-06-29T13:45:30.000Z'
pagination:
page: 1
limit: 20
total: 87
totalPages: 5
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````