> ## 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.

# Solicitar Saque

> Solicita o saque do seu saldo disponível para a chave Pix cadastrada no painel.

#### Escopo

```bash theme={null}
    write withdrawals_write
```

## Antes de integrar, três coisas

> [!WARNING]
>
> **`201` não é dinheiro na conta.** Todo saque pedido pela API entra na **fila de análise** com
> `status: "pending"`. O estado final se acompanha por [Consultar Saque](/api-reference/withdrawals/retrieve.md).

> [!NOTE]
>
> **A API não cadastra nem altera chave Pix.** O saque vai sempre para a chave já cadastrada no
> painel. Mandar `pixKey` ou `account` no corpo não muda o destino — os campos são ignorados. É de
> propósito: quem tem a chave de API pode decidir *quanto* sacar, nunca *para onde*.

> [!NOTE]
>
> **Limite de 2 solicitações por hora**, por chave de API. Acima disso a resposta é `429` com
> `Retry-After`.

***

## `X-Idempotency-Key` é obrigatório

Sem ela a requisição é recusada com `400`. O motivo é específico desta operação: se a sua chamada
der timeout, você não sabe se o saque foi criado — e repetir sem chave de idempotência cria um
**segundo saque**.

Gere um identificador único por **intenção de saque** (um UUID serve) e repita a mesma chave em
toda retentativa daquela intenção. A Cakto guarda a resposta por 24 horas: a repetição devolve o
mesmo resultado em vez de sacar de novo.

Reusar a mesma chave com um `amount` diferente responde `409` — é o contrário do que você quer, e
a API prefere recusar a adivinhar qual dos dois valores vale.

***

## Valores

* `amount` é string decimal (`"150.00"`), como todo dinheiro no contrato.
* Mínimo de **R\$ 10,00**.
* A **taxa de saque** é descontada do valor pedido: você pede `amount`, a conta recebe
  `amountReceived`. A sua taxa está em [Taxas e Prazos](/api-reference/fees/retrieve.md).
* O saldo que pode ser sacado agora é o `available` de [Saldo](/api-reference/balance/retrieve.md) —
  não o `pending`.

***

## Exemplo

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

import requests

resposta = requests.post(
    "https://api.cakto.com.br/public_api/withdrawals/",
    headers={
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn...",
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={"amount": "150.00"},
    timeout=30,
)

if resposta.status_code == 429:
    raise RuntimeError("Limite de 2 saques por hora atingido.")

resposta.raise_for_status()
saque = resposta.json()
print(f"Saque {saque['id']} em análise. Cai na conta: R$ {saque['amountReceived']}")
```

```javascript Node.js theme={null}
const idempotencyKey = crypto.randomUUID();

const resposta = await fetch("https://api.cakto.com.br/public_api/withdrawals/", {
  method: "POST",
  headers: {
    Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn...",
    "X-Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "150.00" }),
});

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

const saque = await resposta.json();
console.log(`Saque ${saque.id} em análise.`);
```

***

## Boas práticas

* **Guarde o `id` retornado.** É por ele que você acompanha o pedido, e é o que liga o seu registro
  ao nosso.
* **Em `503`, repita com a mesma `X-Idempotency-Key`.** É exatamente o cenário para o qual ela
  existe: a chamada pode ter chegado.
* **Não trate `429` como erro de integração.** São 2 por hora; agrupe saques em vez de pedir de
  centavo em centavo.
* **Não saque o `pending`.** Só o `available` pode ser sacado hoje; o resto libera nas datas da
  [Agenda de Recebimentos](/api-reference/balance/schedule.md).


## OpenAPI

````yaml POST /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/:
    post:
      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_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
              examples:
                Sucesso:
                  value:
                    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
          description: >-
            Pedido registrado. `status` vem `pending`: o saque entrou na fila de
            análise, e `201` **não** significa dinheiro transferido.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                SemChaveDeIdempotencia:
                  value:
                    detail: Header X-Idempotency-Key é obrigatório.
                AbaixoDoMinimo:
                  value:
                    detail: O valor mínimo para saque é R$ 10.00.
          description: >-
            Sem a chave de idempotência a operação é recusada: um retry de
            timeout viraria um segundo saque.
        '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'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                EscopoInsuficiente:
                  value:
                    detail: Você não tem permissão para executar esta ação.
          description: >-
            Chave de API sem o escopo `withdrawals_write`. Nenhuma chave emitida
            antes deste recurso tem esse escopo: é preciso reemitir a chave
            concedendo-o.
        '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.
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                SaldoInsuficiente:
                  value:
                    detail: Saldo insuficiente para o valor solicitado.
          description: Corpo da resposta status 422
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                LimiteDeFrequencia:
                  value:
                    detail: Request was throttled. Expected available in 1800 seconds.
          description: >-
            Teto de 2 solicitações por hora, por chave de API. O header
            `Retry-After` diz quando tentar de novo.
        '503':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Indisponivel:
                  value:
                    detail: >-
                      Não foi possível solicitar o saque agora. Tente novamente
                      em instantes.
          description: >-
            Falha ao falar com o serviço que processa o saque. **Repita com a
            mesma `X-Idempotency-Key`**: é o que garante que uma tentativa
            anterior que tenha chegado não vire um segundo saque.
      security:
        - OAuth Token: []
components:
  schemas:
    WithdrawalRequest:
      type: object
      properties:
        amount:
          type: string
          format: decimal
          example: '2.49'
          description: >-
            Valor a sacar, como string decimal (`"150.00"`). Mínimo de
            `"10.00"`. A taxa de saque é descontada deste valor — o que cai na
            conta é `amountReceived`.
      required:
        - amount
    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
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    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.