> ## 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.
# Solicitar saque
> Pede a retirada do saldo disponível de um recebedor para a conta bancária dele.
`POST /withdrawals`
Faz parte do recurso [Saques](/pt-BR/withdrawals) — os estados e o fluxo de aprovação estão lá.
Solicita a retirada do saldo de um recebedor. O saque **não sai na hora**: ele entra como
`requested` e espera aprovação.
**Solicitar não é sacar.** A resposta `201` confirma que o pedido foi registrado, não que o
dinheiro saiu. O caminho é `requested → approved → processing → paid`, e cada passo depende da
aprovação e do processamento bancário. Quem tratar o `201` como "pago" contabiliza errado.
**O `amount` é o que sai do saldo; o `netAmount` é o que chega na conta.** A taxa é descontada do
valor pedido, não somada a ele — pedir `300000` com taxa de `4867` deposita `295133`. Os três
campos vêm na resposta, e é o `netAmount` que o recebedor vê no extrato bancário.
**O saldo é agregado por moeda.** O pedido é por `recipientId`, não por carteira: a Z2Pay soma
todas as carteiras daquele recebedor na moeda indicada (`BRL` por padrão). Você não escolhe de
qual carteira sai.
**Só o saldo disponível conta.** O que está a liberar ou bloqueado não entra, e pedir mais do que
há disponível é recusado. Consulte
[`GET /wallets/owner/{ownerId}/balance`](/pt-BR/wallets/owner-balance) antes — é o campo de
sacável que responde quanto cabe no pedido.
**Há um mínimo, e as taxas são da conta.** Os três valores vêm em
[`GET /withdrawals/config`](/pt-BR/withdrawals/config): taxa percentual, taxa fixa e valor mínimo.
Abaixo do mínimo, o pedido é recusado.
**A conta de destino não se escolhe aqui.** O `bankAccountId` da resposta é a conta bancária
cadastrada do recebedor — para mudá-la, o caminho é
[atualizar o recebedor](/pt-BR/recipients/update).
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/withdrawals \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"recipientId": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"amount": 300000,
"currency": "BRL"
}'
```
```json Resposta 201 theme={null}
{
"id": "wdr_unbd7bvw5wiyyo5go6e9um9dm",
"amount": 300000,
"currency": "BRL",
"fee": 4867,
"netAmount": 295133,
"status": "requested",
"bankAccountId": "rba_mmw0ae28gelp9xz08x2czcgx0",
"paidAt": null,
"statusHistory": [
{
"status": "requested",
"changedBy": "api",
"changedAt": "2026-08-11T13:00:00.000Z",
"reason": null
}
],
"createdAt": "2026-08-11T13:00:00.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json POST /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:
post:
tags:
- Withdrawals
summary: Solicitar saque
description: >-
Solicita saque por recipientId, agregando o saldo de todas as carteiras
da moeda (default BRL). O saque entra como requested e aguarda
aprovação. Valor em centavos
operationId: WithdrawalController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
recipientId:
type: string
minLength: 1
description: ID do recebedor cuja carteira será sacada.
amount:
type: integer
minimum: 1
description: Valor do saque, em centavos.
currency:
type: string
enum:
- BRL
description: >-
Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL',
que também é o padrão quando o campo é omitido.
required:
- recipientId
- amount
responses:
'201':
description: Saque solicitado
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_unbd7bvw5wiyyo5go6e9um9dm
amount: 300000
currency: BRL
fee: 4867
netAmount: 295133
status: requested
bankAccountId: rba_mmw0ae28gelp9xz08x2czcgx0
paidAt: null
statusHistory:
- status: requested
changedBy: api
changedAt: '2025-06-29T13:45:30.000Z'
reason: null
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
'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
'409':
description: >-
Saldo insuficiente, valor abaixo do mínimo ou nenhuma carteira ativa
na moeda
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: CONFLICT
message: No refundable payment found
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````