Skip to main content
GET
Esta rota lista as solicitações de saque (payouts) com filtros e paginação. É por ela que você acompanha um saque depois de criado: se está pendente, se foi aprovado ou recusado, quanto foi cobrado de taxa. A resposta também traz pendingCount, o total de saques pendentes que atendem aos filtros.

Quando usar

Antes de chamar

  • Use a chave secreta (sk_) em Basic, como no resto da API (Credenciais e ambientes).
  • A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil Desenvolvedor recebe 403 Acesso negado nesta rota.
  • Com a chave de teste (sk_test_), a listagem só traz registros de teste. Como não existe saque no Modo Teste, na prática ela vem vazia.
  • Para filtrar por vendedor, tenha o id da subconta (Listar subcontas).
Escopo da listagem: a rota traz os saques de todas as contas a que a credencial tem acesso. Para a conta master do Connect, isso inclui os saques das subcontas. Para ver uma conta só, filtre por merchantId.

Parâmetros de consulta

Todos os parâmetros são opcionais. A lista vem sempre do saque mais recente para o mais antigo.
string
Filtra pela conta que pediu o saque (a sua própria conta ou uma subconta). Uma conta a que a credencial não tem acesso devolve 404 Merchant not found. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo.
string
Filtra pelo status da solicitação: pending, approved ou rejected. Ex.: pending.
string
Filtra pela moeda. Ex.: BRL.
string
Data inicial do filtro pela data de criação, no formato AAAA-MM-DD. A data é inclusiva. Ex.: 2026-10-01.
string
Data final do filtro pela data de criação, no formato AAAA-MM-DD. A data é inclusiva. Ex.: 2026-10-31.
integer
default:"1"
Número da página, começando em 1.
integer
default:"10"
Quantidade de itens por página. Ex.: 20.
A API ignora parâmetros desconhecidos sem devolver erro. Não existem filtros createdAt nem processedAt: enviados, eles não filtram nada e a lista volta completa. Use createdAtStart e createdAtEnd.

Respostas

object[]
Solicitações de saque da página atual.
integer
Total de solicitações em todas as páginas. Ex.: 42.
integer
Página atual. Ex.: 1.
integer
Solicitações por página. Ex.: 20.
integer
Total de páginas. Ex.: 3.
integer
Total de saques pending com os mesmos filtros da consulta, sem considerar o filtro status. Ex.: 3.
Os itens da listagem não trazem netAmount, rejectionReason nem updatedAt. O valor líquido é amount menos payoutFee. O motivo da recusa chega no webhook payout.rejected (saques de subconta) ou pelo suporte.
Para o desenvolvedor: amount e payoutFee chegam como texto ("100.00000000"). Converta antes de somar ou comparar, de preferência com uma biblioteca decimal ou em centavos: Math.round(Number(item.amount) * 100).

Status do saque

approved quer dizer aprovado e enviado para pagamento. Ele não confirma que o dinheiro já está na conta de destino.

Códigos HTTP

Trate o erro pelo código HTTP, não pelo texto da mensagem.
Para o negócio: com merchantId e o período, o time financeiro monta o extrato de saques de cada conta e confere a taxa cobrada (payoutFee). pendingCount mostra quantos saques ainda aguardam decisão sem precisar percorrer todas as páginas.

Erros comuns

Veja também

Solicitar saque

Saque do saldo da própria conta, por Pix.

Criar saque de subconta

Saque da conta master para uma subconta.

Saques no Connect

Fluxo, taxas e status dos saques.

Webhooks de saque

Avisos de aprovação e recusa dos saques de subconta.