> ## 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.
# Listar saques
> Lista paginada dos saques da sua conta, com filtro por etapa.
`GET /withdrawals`
Faz parte do recurso [saques](/pt-BR/withdrawals) — o fluxo do saque e seus
pré-requisitos estão lá.
Retorna os saques da sua conta **do mais recente para o mais antigo**, paginados: `limit` vem `20`
por padrão e aceita até `100`. Nada no corpo avisa que houve corte — confira
`pagination.totalPages` antes de concluir que a lista acabou.
**Filtro com valor inválido responde `400`, não é ignorado.** `?status=pendente` recusa a
requisição inteira, sem devolver resultado parcial.
**`amount` é o valor solicitado e `netAmount` é o que cai na conta** — a diferença é a `fee`,
todos em centavos. Para conferir a taxa antes de solicitar, use
[Configuração de saque](/pt-BR/withdrawals/config).
**`cancelled` e `rejected` não são a mesma coisa.** `cancelled` é o saque que **você** cancelou
enquanto ele ainda podia ser interrompido; `rejected` é o que não passou na nossa análise. Em
ambos os casos o valor volta para a carteira. Já `failed` é falha no envio ao banco — vale
conferir os dados da conta bancária.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/withdrawals -H "x-api-key: SUA_CHAVE_DE_SANDBOX" --data-urlencode "status=requested" --data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "wdr_cdo734b90lnwlndzd5e571d5r",
"amount": 50000,
"currency": "BRL",
"fee": 367,
"netAmount": 49633,
"status": "requested",
"createdAt": "2026-06-20T09:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3,
"totalPages": 1
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /withdrawals
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:
/withdrawals:
get:
tags:
- Withdrawals
summary: Listar saques
description: >-
Retorna lista paginada de saques da company, com filtro opcional por
status (requested, approved, processing, paid, cancelled, rejected,
failed)
operationId: WithdrawalController_list
parameters:
- 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: status
in: query
required: false
description: >-
Etapa do saque: `requested` (solicitado), `approved` (aprovado),
`processing` (em processamento), `paid` (pago), `cancelled`
(cancelado por você), `rejected` (recusado) ou `failed` (falhou). Um
valor por requisição.
schema:
type: string
enum:
- requested
- approved
- processing
- paid
- cancelled
- rejected
- failed
description: >-
Etapa do saque: `requested` (solicitado), `approved` (aprovado),
`processing` (em processamento), `paid` (pago), `cancelled`
(cancelado por você), `rejected` (recusado) ou `failed` (falhou).
Um valor por requisição.
responses:
'200':
description: Lista paginada de saques
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
amount:
type: integer
description: Valor bruto em centavos
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
fee:
type: integer
description: Taxa em centavos
netAmount:
type: integer
description: Valor líquido (amount - fee) em centavos
status:
type: string
description: >-
Situação do saque. Valores: `requested`, `approved`,
`processing`, `paid`, `cancelled`, `rejected`,
`failed`.
bankAccountId:
type: string
nullable: true
description: ID da conta bancária de destino do saque.
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi liquidado (ISO
8601).
statusHistory:
type: array
nullable: true
items:
type: object
properties:
status:
type: string
description: >-
Situação do saque. Valores: `requested`,
`approved`, `processing`, `paid`, `cancelled`,
`rejected`, `failed`.
changedBy:
type: string
nullable: true
description: >-
Autor da alteração de status (usuário, api ou
sistema).
changedAt:
type: string
format: date-time
description: >-
Data e hora em que o status foi alterado (ISO
8601).
reason:
type: string
description: Motivo informado para a operação.
description: Histórico de mudanças de status do saque.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualizaçã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: wdr_cdo734b90lnwlndzd5e571d5r
amount: 500000
currency: BRL
fee: 7867
netAmount: 492133
status: paid
bankAccountId: rba_mmw0ae28gelp9xz08x2czcgx0
paidAt: '2025-06-30T10:12:05.000Z'
statusHistory:
- status: requested
changedBy: api
changedAt: '2025-06-29T13:45:30.000Z'
reason: null
- status: approved
changedBy: user_w9k2mx7qzt4rpf8hnc5ydv3bj
changedAt: '2025-06-29T18:20:11.000Z'
reason: null
- status: processing
changedBy: null
changedAt: '2025-06-30T09:00:00.000Z'
reason: null
- status: paid
changedBy: null
changedAt: '2025-06-30T10:12:05.000Z'
reason: null
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-30T10:12:05.000Z'
pagination:
page: 1
limit: 20
total: 12
totalPages: 1
'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)
````