Skip to main content
POST
cURL

Escopo

Antes de integrar, três coisas

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.
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.
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.
  • O saldo que pode ser sacado agora é o available de Saldo — não o pending.

Exemplo


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.

Authorizations

Authorization
string
header
required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Body

amount
string<decimal>
required

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.

Example:

"2.49"

Response

Pedido registrado. status vem pending: o saque entrou na fila de análise, e 201 não significa dinheiro transferido.

id
string
required

Identificador do saque.

amount
string<decimal>
required

Valor solicitado, como string decimal.

Example:

"2.49"

fee
string<decimal>
required

Taxa de saque cobrada.

Example:

"2.49"

amountReceived
string<decimal>
required

amount menos fee: o que efetivamente cai na conta de destino.

Example:

"2.49"

currency
string
required

Moeda do saque.

status
enum<string>
required

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
Available options:
pending,
approved,
rejected,
blocked
reason
string | null
required

Motivo da recusa, quando houver — o mesmo texto que o produtor vê no painel. null enquanto o pedido não foi recusado.

createdAt
string<date-time>
required

Quando o saque foi solicitado.

paidAt
string<date-time> | null
required

Quando o dinheiro foi enviado. null enquanto o saque não foi pago.