> ## 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.
# Buscar saque por ID
> Retorna um saque com o histórico de status por que ele passou.
`GET /withdrawals/:id`
Faz parte do recurso [Saques](/pt-BR/withdrawals) — os estados e o fluxo de aprovação estão lá.
Devolve o saque completo, incluindo o `statusHistory` — a trilha de cada mudança de estado, com
quem a fez e quando.
**O `statusHistory` é onde está o "por quê".** Cada entrada traz `status`, `changedBy`,
`changedAt` e `reason`. Num saque `rejected` ou `failed`, é a `reason` da última entrada que
explica — o objeto raiz não tem campo de motivo.
**`paidAt` é o que confirma o dinheiro.** Enquanto ele for nulo, o saque não chegou à conta, mesmo
que o status já tenha avançado. É o campo a observar em conciliação.
**Você não precisa ficar consultando.** Três eventos cobrem o ciclo — `withdrawal.requested`,
`withdrawal.paid` e `withdrawal.rejected`. Assine-os em [Webhooks](/pt-BR/webhooks) e use esta
rota para o detalhe, não para descobrir que algo mudou.
Repare que não há evento para `approved`, `processing`, `cancelled` nem `failed`: entre o pedido e
o desfecho, o silêncio é esperado.
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/withdrawals/wdr_unbd7bvw5wiyyo5go6e9um9dm \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "wdr_unbd7bvw5wiyyo5go6e9um9dm",
"amount": 300000,
"currency": "BRL",
"fee": 4867,
"netAmount": 295133,
"status": "paid",
"bankAccountId": "rba_mmw0ae28gelp9xz08x2czcgx0",
"paidAt": "2026-08-12T10:15:00.000Z",
"statusHistory": [
{
"status": "requested",
"changedBy": "api",
"changedAt": "2026-08-11T13:00:00.000Z",
"reason": null
},
{
"status": "approved",
"changedBy": "admin",
"changedAt": "2026-08-11T16:40:00.000Z",
"reason": null
},
{
"status": "paid",
"changedBy": "system",
"changedAt": "2026-08-12T10:15:00.000Z",
"reason": null
}
],
"createdAt": "2026-08-11T13:00:00.000Z",
"updatedAt": "2026-08-12T10:15:00.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json GET /withdrawals/{id}
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/{id}:
get:
tags:
- Withdrawals
summary: Buscar saque por ID
description: Retorna os dados completos de um saque, incluindo histórico de status
operationId: WithdrawalController_getById
parameters:
- name: id
in: path
required: true
description: ID do saque
schema:
type: string
responses:
'200':
description: Dados do saque
content:
application/json:
schema:
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).
example:
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'
'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
'404':
description: Saque não encontrado
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: NOT_FOUND
message: Withdrawal not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````