Pular para o conteúdo principal
Quando uma transação é paga, o valor (descontadas taxas e splits) é creditado na carteira (wallet) do recebedor. Esse saldo passa por estágios — pending, available e blocked — até ficar disponível para saque. Esta página explica esse ciclo e os endpoints para consultar saldo e solicitar saques.
As carteiras são organizadas por recebedor (recipient) e por moeda. A API agrega todas as carteiras internas de um recebedor numa visão única por moeda — você não precisa lidar com IDs de carteira individuais.

​
Do pagamento ao saldo

1

Pagamento confirmado

Uma transação é paga. O valor líquido (após taxas e split) é creditado na carteira do recebedor.
2

Saldo a liberar (pending)

Logo após o pagamento, o valor entra como pending (a liberar). Ele ainda não pode ser sacado.
3

Saldo disponível (available)

Após o período de liberação, o valor passa de pending para available (disponível).
4

Solicitação de saque

Você solicita um saque do saldo sacável. O saque entra como requested e aguarda aprovação. Ver fluxo de saque.

​
Estágios do saldo

A consulta de saldo retorna quatro valores por moeda, todos em centavos (inteiros):
​
availableBalance
integer
Saldo disponível: valor já liberado, soma de todas as carteiras da moeda.
​
pendingBalance
integer
Saldo a liberar (pending): valor creditado mas ainda em período de liberação. Não pode ser sacado.
​
blockedBalance
integer
Saldo bloqueado: valor retido (ex.: por contestação/chargeback ou reserva). Reduz o quanto pode ser sacado.
​
withdrawableBalance
integer
Saldo sacável: o quanto efetivamente pode ser sacado agora. É calculado a partir de available - blocked, aplicando o limite percentual de saque configurado para a sua conta na moeda. É este valor que você compara antes de chamar o saque.
Sempre use withdrawableBalance para decidir o valor de um saque. availableBalance não desconta o bloqueio nem o limite percentual da conta.

​
Endpoints

Todas as requisições usam o header x-api-key (ver Autenticação).
MétodoRotaDescrição
GET/wallets/owner/{ownerId}/balanceSaldo agregado por moeda do recebedor
GET/withdrawals/configTaxas e valor mínimo de saque
POST/withdrawalsSolicitar um saque
GET/withdrawalsListar saques (paginado)
GET/withdrawals/{id}Buscar um saque por ID
POST/withdrawals/{id}/cancelCancelar um saque ainda não aprovado
O extrato detalhado da carteira (lançamentos, resumo por período) é coberto em Carteiras.

​
Consultar saldo

​
ownerId
string
obrigatório
ID do recebedor (recipient), no formato rec_....
Requisição
curl https://api.sandbox.z2pay.com/wallets/owner/rec_8a1f2c3d4e5f/balance \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "recipientId": "rec_8a1f2c3d4e5f",
  "balances": [
    {
      "currency": "BRL",
      "availableBalance": 150000,
      "pendingBalance": 32000,
      "blockedBalance": 0,
      "withdrawableBalance": 150000
    }
  ]
}
balances traz um item por moeda. Se o recebedor não tiver carteiras, o array vem vazio. Os valores estão em centavos: 150000 = R$ 1.500,00.

​
Configuração de saque

Antes de solicitar um saque, consulte a configuração para saber a taxa e o valor mínimo. Os valores monetários estão em centavos.
​
currency
string
Filtra a configuração por moeda (ISO 4217, 3 letras, ex.: BRL). Opcional.
Requisição
curl "https://api.sandbox.z2pay.com/withdrawals/config?currency=BRL" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "feePercentage": 0,
  "feeFixed": 367,
  "minimumAmount": 1000
}
​
feePercentage
number
Percentual da taxa de saque aplicada sobre o valor solicitado.
​
feeFixed
integer
Taxa fixa de saque, em centavos (ex.: 367 = R$ 3,67).
​
minimumAmount
integer
Valor mínimo para solicitar um saque, em centavos. Solicitações abaixo desse valor são recusadas.

​
Solicitar saque

Solicita um saque para um recebedor numa moeda. O saque agrega o saldo de todas as carteiras da moeda e entra com status requested, aguardando aprovação.
Este endpoint retorna 201 Created e aceita o header opcional Idempotency-Key para evitar saques duplicados em caso de retry. Ver Convenções.
​
recipientId
string
obrigatório
ID do recebedor (recipient), formato rec_....
​
amount
integer
obrigatório
Valor bruto do saque, em centavos. Deve ser inteiro e maior que 0.
​
currency
string
padrão:"BRL"
Moeda do saque (ISO 4217, exatamente 3 letras, ex.: BRL). Opcional — quando omitido, usa BRL.
Requisição
curl -X POST https://api.sandbox.z2pay.com/withdrawals \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 9c1e7b40-2f3a-4d18-9a77-6b2c1d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "rec_8a1f2c3d4e5f",
    "amount": 50000,
    "currency": "BRL"
  }'
Resposta 201
{
  "id": "wdr_3b9c1a2d4e6f",
  "walletId": "wlt_7d2e1f0a3b4c",
  "tenantId": "comp_1a2b3c4d5e6f",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "requested",
  "bankAccountId": null,
  "paidAt": null,
  "pspTransferId": null,
  "statusHistory": [
    {
      "status": "requested",
      "changedBy": "api",
      "changedAt": "2026-06-24T13:45:00.000Z"
    }
  ],
  "image": null,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T13:45:00.000Z"
}
O netAmount é o valor que o recebedor efetivamente recebe: amount - fee. A taxa (fee) é calculada no momento da solicitação a partir da configuração de saque.
Se o saldo sacável for insuficiente, o valor estiver abaixo do mínimo, ou não houver carteira ativa na moeda, a API retorna 409 Conflict. Confira o saldo (withdrawableBalance) e o mínimo (minimumAmount) antes de solicitar. Ver Erros.

​
Fluxo de saque

Um saque percorre os seguintes status: 
requested → approved → processing → paid
Caminhos alternativos: cancelled (cancelado pelo lojista antes da aprovação), rejected (recusado na análise) e failed (falha no processamento).
Estado inicial logo após a solicitação. Aguarda aprovação manual. É o único status em que o saque pode ser cancelado via API.
O saque foi aprovado na análise e segue para processamento.
O pagamento está sendo executado junto ao destino bancário.
cancelled: cancelado pelo lojista enquanto ainda estava em requested. rejected: recusado na análise. failed: falha durante o processamento.
Acompanhe transições de saque em tempo real assinando os eventos de webhook (withdrawal.requested, withdrawal.paid, withdrawal.rejected). Ver Webhooks.

​
Listar saques

Retorna a lista paginada de saques da conta, com filtro opcional por status.
​
status
string
Filtra por status. Valores: requested, approved, processing, paid, cancelled, rejected, failed. Opcional.
​
page
integer
padrão:"1"
Página da paginação.
​
limit
integer
padrão:"20"
Quantidade de itens por página (máximo 100).
Requisição
curl "https://api.sandbox.z2pay.com/withdrawals?status=paid&page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "data": [
    {
      "id": "wdr_3b9c1a2d4e6f",
      "walletId": "wlt_7d2e1f0a3b4c",
      "amount": 50000,
      "currency": "BRL",
      "fee": 367,
      "netAmount": 49633,
      "status": "paid",
      "paidAt": "2026-06-23T18:10:00.000Z",
      "createdAt": "2026-06-23T13:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

​
Buscar saque por ID

Retorna os dados completos de um saque, incluindo o histórico de status (statusHistory).
​
id
string
obrigatório
ID do saque, formato wdr_....
Requisição
curl https://api.sandbox.z2pay.com/withdrawals/wdr_3b9c1a2d4e6f \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "id": "wdr_3b9c1a2d4e6f",
  "walletId": "wlt_7d2e1f0a3b4c",
  "tenantId": "comp_1a2b3c4d5e6f",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "paid",
  "bankAccountId": null,
  "paidAt": "2026-06-23T18:10:00.000Z",
  "pspTransferId": "psp_xfer_2c4e6a8b0d1f",
  "statusHistory": [
    { "status": "requested", "changedBy": null, "changedAt": "2026-06-23T13:45:00.000Z" },
    { "status": "approved", "changedBy": "user_9f8e7d6c5b4a", "changedAt": "2026-06-23T15:00:00.000Z" },
    { "status": "processing", "changedBy": null, "changedAt": "2026-06-23T17:30:00.000Z" },
    { "status": "paid", "changedBy": null, "changedAt": "2026-06-23T18:10:00.000Z" }
  ],
  "image": null,
  "createdAt": "2026-06-23T13:45:00.000Z",
  "updatedAt": "2026-06-23T18:10:00.000Z"
}
Se o saque não existir, a API retorna 404 Not Found. Ver Erros.

​
Cancelar saque

Cancela um saque somente enquanto ele está em requested (ainda não aprovado).
Este endpoint aceita o header opcional Idempotency-Key.
​
id
string
obrigatório
ID do saque, formato wdr_....
​
reason
string
Motivo do cancelamento (no mínimo 1 caractere). Opcional — quando omitido, é registrado um motivo padrão.
Requisição
curl -X POST https://api.sandbox.z2pay.com/withdrawals/wdr_3b9c1a2d4e6f/cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Solicitado pelo lojista" }'
Resposta 200
{
  "id": "wdr_3b9c1a2d4e6f",
  "status": "cancelled",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "updatedAt": "2026-06-24T14:02:00.000Z"
}
Saque não encontrado retorna 404; saque que não pode ser cancelado no status atual (ex.: já aprovado ou pago) retorna 409. Ver Erros.

​
Testar em sandbox

No sandbox você pode simular a liberação de saldo e a liquidação de saques sem mover dinheiro real.

Visão geral do sandbox

Como funciona o ambiente de testes.

Simular eventos

Force transições para testar o fluxo de saque.

​
Veja também

Carteiras

Saldo, extrato e resumo por período.

Taxas

Como as taxas são calculadas.

Split

Divisão de valores entre recebedores.

Webhooks

Receba notificações de saque em tempo real.