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

# Listar Saques

> Histórico de saques da conta, do mais recente para o mais antigo.

#### Escopo

```bash theme={null}
    read withdrawals_read
```

## Filtros

| Parâmetro | |
| - | - |
| `status` | `pending`, `approved`, `rejected` ou `blocked` |
| `createdAt__gte` / `createdAt__lte` | janela pela data da **solicitação** (`YYYY-MM-DD`), inclusive nos dois lados |
| `page` / `limit` | paginação, como em toda listagem do contrato. Default `10` por página, máximo `1000` |

A resposta vem no [envelope de paginação](/conceitos/paginacao) do contrato: `count`, `next`,
`previous` e `results`.

> [!NOTE]
>
> A listagem traz **sempre a conta dona do token**. Não existe parâmetro de produtor.

***

## Exemplo

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

resposta = requests.get(
    "https://api.cakto.com.br/public_api/withdrawals/",
    params={"status": "pending", "limit": 50},
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."},
    timeout=30,
)
resposta.raise_for_status()
pagina = resposta.json()

print(f"{pagina['count']} saques em análise")
for saque in pagina["results"]:
    print(saque["createdAt"], saque["amount"])
```

```javascript Node.js theme={null}
const params = new URLSearchParams({ status: "pending", limit: "50" });

const resposta = await fetch(
  `https://api.cakto.com.br/public_api/withdrawals/?${params}`,
  { headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." } },
);

if (!resposta.ok) throw new Error(`Cakto API error ${resposta.status}`);

const pagina = await resposta.json();
console.log(`${pagina.count} saques em análise`);
```

***

## Boas práticas

* **Concilie por `id`, não por valor e data.** Dois saques do mesmo valor no mesmo dia são
  indistinguíveis por qualquer outro critério.
* **Para saber o que ainda vai entrar**, use a [Agenda de Recebimentos](/api-reference/balance/schedule);
  esta lista é sobre o que já **saiu** ou foi pedido.


## OpenAPI

````yaml GET /public_api/withdrawals/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/withdrawals/:
    get:
      tags:
        - withdrawals
      description: >-
        Solicita um saque e lista os saques da conta.


        O valor vai para a **chave Pix já cadastrada** no painel. A operação não
        recebe chave Pix nem

        conta de destino: mandar esses campos no corpo não muda o destino do
        dinheiro.


        Todo pedido feito por aqui entra na **fila de análise** — `201`
        significa pedido registrado,

        não dinheiro transferido. O estado final se acompanha pela consulta.


        `X-Idempotency-Key` é obrigatório: sem ele, um retry de timeout vira um
        segundo saque.
      operationId: withdrawals_list
      parameters:
        - in: query
          name: createdAt__gte
          schema:
            type: string
            format: date
          description: Solicitados a partir desta data (`YYYY-MM-DD`), inclusive.
        - in: query
          name: createdAt__lte
          schema:
            type: string
            format: date
          description: Solicitados até esta data (`YYYY-MM-DD`), inclusive.
        - in: query
          name: limit
          schema:
            type: integer
          description: Itens por página. Default `10`, máximo `1000`.
        - in: query
          name: page
          schema:
            type: integer
          description: Página a retornar. Default `1`.
        - in: query
          name: status
          schema:
            type: string
            enum:
              - approved
              - blocked
              - pending
              - rejected
          description: Filtra por estado do pedido.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedWithdrawalList'
              examples:
                Sucesso:
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - id: '184620'
                        amount: '150.00'
                        fee: '3.67'
                        amountReceived: '146.33'
                        currency: BRL
                        status: pending
                        reason: null
                        createdAt: '2026-09-17T14:32:10.512340-03:00'
                        paidAt: null
                      - id: '184455'
                        amount: '150.00'
                        fee: '3.67'
                        amountReceived: '146.33'
                        currency: BRL
                        status: rejected
                        reason: Chave PIX não cadastrada
                        createdAt: '2026-09-17T14:32:10.512340-03:00'
                        paidAt: null
          description: Saques da conta, do mais recente para o mais antigo.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                StatusInvalido:
                  value:
                    detail: >-
                      Status inválido. Use um de: pending, approved, rejected,
                      blocked.
          description: Corpo da resposta status 400
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
        '409':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                ContaSemRecebimento:
                  value:
                    detail: >-
                      Conta ainda não habilitada para recebimento. Conclua o
                      cadastro no painel da Cakto para poder solicitar saques.
          description: >-
            O cadastro de recebimento não foi concluído no painel. Repetir a
            chamada não muda isso.
      security:
        - OAuth Token: []
components:
  schemas:
    PaginatedWithdrawalList:
      type: object
      properties:
        count:
          type: integer
          description: Total de saques que atendem ao filtro, em todas as páginas.
        next:
          type: string
          nullable: true
          description: URL da próxima página, ou `null` na última.
        previous:
          type: string
          nullable: true
          description: URL da página anterior, ou `null` na primeira.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Withdrawal'
      required:
        - count
        - next
        - previous
        - results
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    Withdrawal:
      type: object
      properties:
        id:
          type: string
          description: Identificador do saque.
        amount:
          type: string
          format: decimal
          example: '2.49'
          description: Valor solicitado, como string decimal.
        fee:
          type: string
          format: decimal
          example: '2.49'
          description: Taxa de saque cobrada.
        amountReceived:
          type: string
          format: decimal
          example: '2.49'
          description: '`amount` menos `fee`: o que efetivamente cai na conta de destino.'
        currency:
          type: string
          description: Moeda do saque.
        status:
          allOf:
            - $ref: '#/components/schemas/WithdrawalStatusEnum'
          description: >-
            Estado do pedido. **Saque solicitado pela API nasce `pending`**:
            entra na fila de análise em vez de sair automático. `approved` é o
            dinheiro já enviado; `rejected` devolve o valor ao saldo, com o
            motivo em `reason`; `blocked` exige contato com o suporte.


            * `pending` - pending

            * `approved` - approved

            * `rejected` - rejected

            * `blocked` - blocked
        reason:
          type: string
          nullable: true
          description: >-
            Motivo da recusa, quando houver — o mesmo texto que o produtor vê no
            painel. `null` enquanto o pedido não foi recusado.
        createdAt:
          type: string
          format: date-time
          description: Quando o saque foi solicitado.
        paidAt:
          type: string
          format: date-time
          nullable: true
          description: Quando o dinheiro foi enviado. `null` enquanto o saque não foi pago.
      required:
        - amount
        - amountReceived
        - createdAt
        - currency
        - fee
        - id
        - paidAt
        - reason
        - status
    WithdrawalStatusEnum:
      enum:
        - pending
        - approved
        - rejected
        - blocked
      type: string
      description: |-
        * `pending` - pending
        * `approved` - approved
        * `rejected` - rejected
        * `blocked` - blocked
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````

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