> ## 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.
# Resumo do extrato por período
> Totais do extrato agrupados por moeda e por natureza do lançamento.
`GET /wallets/owner/:ownerId/summary`
Faz parte do recurso [Carteiras](/pt-BR/wallets) — o modelo de saldo e liberação está lá.
Devolve, para cada moeda, quanto entrou e quanto saiu em cada tipo de lançamento no período. É a
leitura de fechamento: responde "de onde veio e para onde foi", sem percorrer o
[extrato](/pt-BR/wallets/owner-transactions) linha a linha.
**`total` já vem com sinal.** Entradas são positivas e saídas negativas — taxa, estorno e saque
aparecem com valor negativo. Somar os `total` de todos os tipos dá o resultado líquido do período;
somar os valores absolutos não dá nada.
**`credits` e `debits` separam os dois sentidos** dentro do mesmo tipo, e `count` diz quantos
lançamentos entraram na conta. Um tipo com `credits` e `debits` preenchidos teve movimento nos
dois sentidos no período.
**O resumo é do período, o saldo é de agora.** Este endpoint não responde quanto o recebedor tem —
para isso é [`/balance`](/pt-BR/wallets/owner-balance). Um período fechado com net positivo pode
conviver com saldo disponível zero, se o dinheiro já foi sacado.
**`startDate` e `endDate` em ISO 8601 com fuso.** Sem eles, o resumo cobre todo o histórico.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/wallets/owner/rec_v57bi6ruyolouw3cpaq2ofy1k/summary \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d startDate=2026-08-01T00:00:00-03:00 \
-d endDate=2026-08-31T23:59:59-03:00
```
```json Resposta 200 theme={null}
{
"recipientId": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"data": [
{
"currency": "BRL",
"byType": [
{ "type": "sale", "total": 1800000, "credits": 1800000, "debits": 0, "count": 42 },
{ "type": "fee", "total": -90000, "credits": 0, "debits": -90000, "count": 42 },
{ "type": "refund", "total": -120000, "credits": 0, "debits": -120000, "count": 3 },
{ "type": "withdrawal", "total": -500000, "credits": 0, "debits": -500000, "count": 2 }
]
}
]
}
```
No exemplo, o net do mês em BRL é `1090000` — R\$ 10.900,00 — somando os quatro `total`.
## OpenAPI
````yaml openapi/psp.json GET /wallets/owner/{ownerId}/summary
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}/summary:
get:
tags:
- Wallets
summary: Resumo do extrato por período
description: >-
Retorna totais do extrato agrupados por moeda e tipo de lançamento
(entradas, saídas e net em centavos). Filtros startDate/endDate em ISO
8601 com timezone
operationId: WalletController_getSummary
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: ownerId
in: path
required: true
description: ID do recebedor
schema:
type: string
responses:
'200':
description: Resumo do extrato agrupado por moeda
content:
application/json:
schema:
type: object
properties:
recipientId:
type: string
description: ID do recebedor.
data:
type: array
items:
type: object
properties:
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
byType:
type: array
items:
type: object
properties:
type:
type: string
description: >-
Tipo de lançamento (sale, refund, chargeback,
withdrawal, fee, etc)
total:
type: integer
description: Net por tipo em centavos
credits:
type: integer
description: Total de créditos em centavos
debits:
type: integer
description: Total de débitos em centavos
count:
type: integer
description: Quantidade de lançamentos
description: Totais agrupados por tipo de lançamento.
totalCredits:
type: integer
description: Total de entradas em centavos
totalDebits:
type: integer
description: Total de saídas em centavos
net:
type: integer
description: Net (entradas - saídas) em centavos
description: Lista de registros retornados na página atual.
example:
recipientId: rec_t8wq4hz2mxk9rpf5snc7ydv3b
data:
- currency: BRL
byType:
- type: sale
total: 1800000
credits: 1800000
debits: 0
count: 42
- type: fee
total: -90000
credits: 0
debits: -90000
count: 42
- type: refund
total: -120000
credits: 0
debits: -120000
count: 3
- type: withdrawal
total: -500000
credits: 0
debits: -500000
count: 2
totalCredits: 1800000
totalDebits: -710000
net: 1090000
'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)
````