> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar saques

> Lista as solicitações de saque da sua conta e, para a conta master, também das subcontas, com filtros por conta, status, moeda e período.

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

| Situação | Como usar esta rota |
| - | - |
| Descobrir o `id` de um saque que você acabou de pedir | `POST /v1/payout-requests` responde sem corpo. Liste com `merchantId` da sua conta: a lista vem do mais recente para o mais antigo |
| Acompanhar um saque da conta master ou de conta sem Connect | Esse saque não gera webhook (só os saques de subconta geram, qualquer que seja a rota usada para criar). Consulte esta rota até o `status` mudar |
| Fila de saques aguardando aprovação | Filtre por `status=pending` ou use `pendingCount` |
| Extrato de saques de um vendedor (conta master) | Filtre por `merchantId` da subconta |
| Conciliação mensal | Use `createdAtStart` e `createdAtEnd` |

## Antes de chamar

* Use a chave secreta (`sk_`) em Basic, como no resto da API ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* 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](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md)).

> [!NOTE]
>
> **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.

**merchantId** `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`.

**status** `string`

Filtra pelo status da solicitação: `pending`, `approved` ou `rejected`. Ex.: `pending`.

**currency** `string`

Filtra pela moeda. Ex.: `BRL`.

**createdAtStart** `string`

Data inicial do filtro pela data de criação, no formato `AAAA-MM-DD`. A data é inclusiva. Ex.: `2026-10-01`.

**createdAtEnd** `string`

Data final do filtro pela data de criação, no formato `AAAA-MM-DD`. A data é inclusiva. Ex.: `2026-10-31`.

**page** `integer` (default: 1)

Número da página, começando em `1`.

**size** `integer` (default: 10)

Quantidade de itens por página. Ex.: `20`.

> [!WARNING]
>
> 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

**data** `object[]`

Solicitações de saque da página atual.

**propriedades**

**id** `string`

Identificador da solicitação de saque. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**merchantId** `string`

Conta que solicitou o saque. Pode ser a sua própria conta ou, para a conta master, uma subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

**amount** `string`

Valor bruto pedido, em reais, como texto decimal com 8 casas. Ex.: `"100.00000000"`.

**currency** `string`

Moeda do saque. Ex.: `BRL`.

**status** `string`

Status atual: `pending`, `approved` ou `rejected`.

**payoutFee** `string`

Taxa de saque cobrada, em reais, como texto decimal com 8 casas. Ex.: `"1.00000000"`.

**externalAccountDetails** `object`

Destino do saque, com as chaves em snake\_case, como foram gravadas.

**propriedades**

**type** `string`

Tipo do destino. Ex.: `pix`.

**pix\_key** `string`

Chave Pix de destino: o CNPJ cadastrado na conta que sacou. Ex.: `11222333000181`.

**processedAt** `string | null`

Data e hora da decisão (formato `date-time`). Preenchido quando o saque é aprovado ou recusado.

**createdAt** `string`

Data e hora de criação (formato `date-time`). Ex.: `2026-10-20T18:45:52.988Z`.

**merchantLegalName** `string`

Razão social da conta que solicitou o saque. Ex.: `LOJA EXEMPLO LTDA`.

**merchantEmail** `string`

E-mail de contato da conta que solicitou o saque. Ex.: `financeiro@lojaexemplo.com.br`.

**total** `integer`

Total de solicitações em todas as páginas. Ex.: `42`.

**page** `integer`

Página atual. Ex.: `1`.

**size** `integer`

Solicitações por página. Ex.: `20`.

**pages** `integer`

Total de páginas. Ex.: `3`.

**pendingCount** `integer`

Total de saques `pending` com os mesmos filtros da consulta, sem considerar o filtro `status`. Ex.: `3`.

> [!NOTE]
>
> 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.

> [!TIP]
>
> **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

| Status | O que significa |
| - | - |
| `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão |
| `approved` | Aprovado pela operação ou por aprovação automática e enviado para pagamento. `processedAt` é preenchido |
| `rejected` | Recusado. O valor reservado volta ao saldo disponível e `processedAt` é preenchido |

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

### Códigos HTTP

| HTTP | Significado | Exemplo de corpo |
| - | - | - |
| `200` | Lista devolvida | `data`, `total`, `page`, `size`, `pages`, `pendingCount` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Usuário dono da chave sem permissão de saque (ex.: perfil Desenvolvedor) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |
| `404` | `merchantId` de uma conta a que a credencial não tem acesso | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` |

Trate o erro pelo código HTTP, não pelo texto da mensagem.

> [!NOTE]
>
> **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

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` `Acesso negado` | A chave foi gerada por um usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com um usuário Owner ou Manager |
| Lista vazia no Modo Teste | Não existe saque com chave de teste | Consulte com a chave de produção |
| Filtro por data não muda o resultado | Foi usado `createdAt` ou `processedAt`, que não existem e são ignorados | Use `createdAtStart` e `createdAtEnd` no formato `AAAA-MM-DD` |
| Conta master vê saques que não são dela | A listagem traz as contas a que a credencial tem acesso, inclusive subcontas | Filtre por `merchantId` |
| Soma de valores errada no código | `amount` e `payoutFee` chegam como texto | Converta para número decimal antes de calcular |

```http REST (JSON) theme={null}
GET /v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -G "https://api-global.fastpaybrasil.com/v1/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  --data-urlencode "merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo" \
  --data-urlencode "status=pending" \
  --data-urlencode "createdAtStart=2026-10-01" \
  --data-urlencode "createdAtEnd=2026-10-31" \
  --data-urlencode "page=1" \
  --data-urlencode "size=20"
```

```javascript Node.js theme={null}
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const params = new URLSearchParams({
  merchantId: '36OO3bcGjhPjjF3tzrqOGcmQuKo',
  status: 'pending',
  createdAtStart: '2026-10-01',
  createdAtEnd: '2026-10-31',
  page: '1',
  size: '20',
});

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/payout-requests?${params}`, {
  headers: { Authorization: `Basic ${auth}` },
});

const { data, pendingCount } = await response.json();
for (const saque of data) {
  const bruto = Number(saque.amount);
  const taxa = Number(saque.payoutFee);
  console.log(saque.id, saque.status, (bruto - taxa).toFixed(2));
}
console.log(`${pendingCount} saques pendentes`);
```

```python Python theme={null}
import os

import requests

params = [
    ("merchantId", "36OO3bcGjhPjjF3tzrqOGcmQuKo"),
    ("status", "pending"),
    ("createdAtStart", "2026-10-01"),
    ("createdAtEnd", "2026-10-31"),
    ("page", "1"),
    ("size", "20"),
]

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/payout-requests",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    params=params,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2vorkDcXyvzifL63YX09S9VqcnI",
      "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
      "amount": "100.00000000",
      "currency": "BRL",
      "status": "pending",
      "payoutFee": "1.00000000",
      "externalAccountDetails": {
        "type": "pix",
        "pix_key": "11222333000181"
      },
      "processedAt": null,
      "createdAt": "2026-10-20T18:45:52.988Z",
      "merchantLegalName": "LOJA EXEMPLO LTDA",
      "merchantEmail": "financeiro@lojaexemplo.com.br"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1,
  "pendingCount": 1
}
```

```json 401 theme={null}
{ "statusCode": 401, "message": "Unauthorized" }
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }
```

```json 404 theme={null}
{ "statusCode": 404, "message": "Merchant not found", "error": "Not Found" }
```

## Veja também

> [card] [Solicitar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md)
>
> Saque do saldo da própria conta, por Pix.

> [card] [Criar saque de subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md)
>
> Saque da conta master para uma subconta.

> [card] [Saques no Connect](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
>
> Fluxo, taxas e status dos saques.

> [card] [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
>
> Avisos de aprovação e recusa dos saques de subconta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.