Saldo

cURL

curl --request GET \
  --url https://api.cakto.com.br/public_api/balance/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cakto.com.br/public_api/balance/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cakto.com.br/public_api/balance/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.cakto.com.br/public_api/balance/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

using RestSharp;


var options = new RestClientOptions("https://api.cakto.com.br/public_api/balance/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "currency": "BRL",
  "available": "1250.40",
  "pending": "3890.15",
  "reserved": "412.00",
  "anticipatable": "1100.00",
  "heldByRefund": "89.90",
  "refundBlocked": "289.90",
  "refundBlockedFromPending": "120.00",
  "refundBlockedFromReserved": "50.00"
}

{
  "detail": "Moeda não suportada. Use uma de: BRL, USD."
}

{
  "detail": "As credenciais de autenticação não foram fornecidas."
}

{
  "detail": "Você não tem permissão para executar esta ação."
}

{
  "detail": "Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para que o saldo exista."
}

GET

public_api

balance

cURL

curl --request GET \
  --url https://api.cakto.com.br/public_api/balance/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cakto.com.br/public_api/balance/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cakto.com.br/public_api/balance/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.cakto.com.br/public_api/balance/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

using RestSharp;


var options = new RestClientOptions("https://api.cakto.com.br/public_api/balance/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "currency": "BRL",
  "available": "1250.40",
  "pending": "3890.15",
  "reserved": "412.00",
  "anticipatable": "1100.00",
  "heldByRefund": "89.90",
  "refundBlocked": "289.90",
  "refundBlockedFromPending": "120.00",
  "refundBlockedFromReserved": "50.00"
}

{
  "detail": "Moeda não suportada. Use uma de: BRL, USD."
}

{
  "detail": "As credenciais de autenticação não foram fornecidas."
}

{
  "detail": "Você não tem permissão para executar esta ação."
}

{
  "detail": "Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para que o saldo exista."
}

Escopo

    read payments

O que é este endpoint?

É a versão consultável por API do cartão de saldo do painel. Ele separa o dinheiro em cinco parcelas disjuntas — cada real aparece em no máximo uma delas, e há dinheiro a receber que não aparece em nenhuma (ver “As cinco parcelas não se sobrepõem”, abaixo):

available — o que dá para sacar agora;
reserved — a reserva de segurança, retida até passar a janela de risco da venda;
pending — o que ainda vai liberar e ainda não entrou na janela de antecipação;
anticipatable — o que já entrou nessa janela e pode ser antecipado hoje pelo painel. Não é um recorte de pending: é um balde próprio, e os dois não se sobrepõem;
refundBlocked — o total bloqueado por pedidos de reembolso em processamento.

E mais três campos que detalham de onde veio o refundBlocked, em vez de somar com as parcelas acima:

heldByRefund — a fatia do bloqueio que já foi descontada de available;
refundBlockedFromPending — a fatia que saiu de pending;
refundBlockedFromReserved — a fatia que saiu de reserved.

A operação lê sempre a conta dona do token. Não existe parâmetro de produtor: não há como consultar o saldo de outra conta, e mandar um identificador na query não muda o resultado.

`refundBlocked` e `heldByRefund` não são o mesmo número

Quando um comprador pede reembolso, a parte que é sua naquele pedido fica bloqueada até a análise terminar. O efeito depende de onde esse dinheiro estava quando o pedido entrou:

se já tinha liberado e estava sacável, ele sai de available;
se ainda não tinha liberado, ele sai de pending ou de reserved, conforme o caso.

heldByRefund conta só o primeiro caso — a fatia que o saque de fato recusa. refundBlocked conta os dois, e é o total que a Cakto está de fato segurando por esses pedidos. Por isso refundBlocked é sempre maior ou igual a heldByRefund.

refundBlocked nem sempre é o valor das vendas em análise. Numa venda parcialmente antecipada que ainda não liberou, a parte que você já recebeu por antecipação saiu da conta como saque, e o bloqueio é só o resto. Uma venda de R

50,00 com R

20,00 já antecipados entra em refundBlocked por **R

30,00** enquanto não libera, embora o pedido de reembolso apareça em "Minhas vendas" sobre os R

50,00.Depois que a venda libera — e também na venda antecipada por inteiro —, o bloqueio é o valor cheio da venda: os mesmos R$ 50,00 do exemplo, em refundBlocked e em heldByRefund. Conciliar linha a linha contra o valor das vendas só acha diferença nas vendas parcialmente antecipadas e ainda não liberadas — e ali ela está certa.

De onde saiu cada fatia

refundBlockedFromPending e refundBlockedFromReserved dizem quanto do bloqueio saiu de cada um desses campos. As três fatias não somam o total:

heldByRefund + refundBlockedFromPending + refundBlockedFromReserved  ≤  refundBlocked

A diferença é real: é o dinheiro bloqueado que não aparece em nenhum outro campo da resposta — pendente já dentro da janela de antecipação, e venda parcialmente antecipada ainda não liberada. Ele está em refundBlocked, e em nenhum outro lugar.

As cinco parcelas não se sobrepõem

Somar as cinco não conta nada duas vezes:

available + pending + reserved + anticipatable + refundBlocked

Isso não é “o patrimônio da conta”, e não monte um card de total com essa soma. Uma venda parcialmente antecipada que não esteja sob pedido de reembolso deixa o resto a receber fora dos cinco campos — ele não entra em pending, nem em anticipatable, nem em refundBlocked. A garantia deste endpoint é de não duplicar, não de somar tudo o que você tem a receber. Para o que cai e quando, use Agenda de Recebimentos.

refundBlocked pode vir null, e null não é zero. Significa que não há número a publicar — a retenção não está ativa para a sua conta, ou a apuração falhou nesta chamada. Zero de verdade vem "0.00". Um cliente que leia null como zero anuncia ao produtor que nada está bloqueado, o que pode ser falso.refundBlockedFromPending e refundBlockedFromReserved acompanham esse null — se não houve apuração, não há fatia a publicar. heldByRefund não acompanha: ele mantém o próprio valor, que é "0.00" com a retenção desligada e a fatia já descontada de available quando a apuração falhou.

pending e reserved vêm descontados do que está retido. Quando refundBlocked vem preenchido, a parte retida que estaria neles é refundBlockedFromPending e refundBlockedFromReserved, e conta só em refundBlocked. Com refundBlocked: null nada foi descontado deles.Não use refundBlocked - heldByRefund no lugar das fatias. Essa diferença mistura o que saiu de pending, o que saiu de reserved e o retido que não aparece em nenhum outro campo — ela não é a parcela de campo nenhum.Até 23/09/2026 a parte retida ainda aparecia dentro de pending e de reserved. Para reconstituir esses valores e conciliar com um histórico anterior, use as fórmulas do Changelog.

`available` pode ser negativo

Não é erro de cálculo. Retenção por pedido de reembolso, chargeback e MED descontam do disponível sem piso: se o dinheiro já tinha sido sacado quando a retenção entrou, o saldo fica negativo e representa dívida real com a plataforma. Saques são recusados enquanto isso, e vendas novas abatem o negativo antes de virar saldo. Um cliente que trate saldo como “sempre ≥ 0” vai truncar esse número e mostrar zero ao produtor, escondendo exatamente a informação que ele precisa ver.

Valores em string

Todo valor monetário sai como string decimal — "1250.40", não 1250.4. O motivo é o de sempre: 0.1 + 0.2 não é 0.3 em ponto flutuante, e dinheiro não tolera esse erro. Converta para o tipo decimal da sua linguagem (Decimal em Python, BigDecimal em Java), nunca para float.

Exemplo

import requests
from decimal import Decimal

response = requests.get(
    "https://api.cakto.com.br/public_api/balance/",
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."},
    timeout=30,
)
response.raise_for_status()
saldo = response.json()

disponivel = Decimal(saldo["available"])
if disponivel < 0:
    print(f"Conta devedora: R$ {disponivel}")
else:
    print(f"Disponível para saque: R$ {disponivel}")

const response = await fetch("https://api.cakto.com.br/public_api/balance/", {
  headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." },
});

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

const saldo = await response.json();
// Sem biblioteca decimal, mantenha a string para exibir e só converta para comparar.
console.log(`Disponível: R$ ${saldo.available}`);

Boas práticas

Não some available com pending para dizer “quanto eu tenho”. São dinheiros de momentos diferentes: um é sacável hoje, o outro é previsão. O que cai e quando está em Agenda de Recebimentos.
heldByRefund, refundBlockedFromPending e refundBlockedFromReserved não são parcelas novas. Os três detalham refundBlocked; somá-los ao total conta o mesmo dinheiro duas vezes.
Para reconstituir o available de antes da retenção, some heldByRefund, não refundBlocked. Só a fatia heldByRefund saiu de available; o resto de refundBlocked saiu de pending e de reserved, ou não aparece em nenhum outro campo.
Trate null como “não sei”, nunca como zero. refundBlocked e as duas fatias dele são as únicas respostas de valor deste endpoint que podem ser nulas, e vêm nulas juntas.
409 não significa “sem saldo”. Significa que o cadastro de recebimento não foi concluído no painel, e repetir a chamada não muda isso. Saldo zero responde 200 com "0.00".
Consulte sob demanda, não em loop. O saldo muda quando há venda, saque ou liberação — não a cada segundo.

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.

Query Parameters

currency

enum<string>

Moeda dos valores. Default BRL.

Available options:

BRL,

USD

Response

Saldo da conta autenticada, na moeda pedida.

currency

string

required

Moeda dos valores desta resposta (BRL ou USD).

available

string<decimal>

required

Disponível para saque agora, como string decimal. Pode ser negativo: retenção por pedido de reembolso, chargeback e MED descontam sem piso, e o saldo negativo é dívida real, não erro de cálculo.

Example:

"2.49"

pending

string<decimal>

required

A liberar em datas futuras, fora a reserva de segurança e fora o que já entrou na janela de antecipação. O detalhe por dia está em GET /public_api/balance/schedule/. Quando refundBlocked vem preenchido, este campo já está líquido do que está retido por pedido de reembolso: a parcela retida que estaria aqui é refundBlockedFromPending e conta só em refundBlocked. Com refundBlocked: null nada foi descontado deste campo. Para reconstituir o valor anterior a 23/09/2026, ver o Changelog.

Example:

"2.49"

reserved

string<decimal>

required

Reserva de segurança retida pela Cakto. Libera depois da janela de risco da venda e não é sacável enquanto isso. Quando refundBlocked vem preenchido, a reserva sob pedido de reembolso em análise já saiu daqui (refundBlockedFromReserved) e conta só em refundBlocked. Com refundBlocked: null nada foi descontado deste campo.

Example:

"2.49"

anticipatable

string<decimal>

required

O que pode ser antecipado hoje pelo painel. Não é um recorte de pending: é um balde próprio e disjunto dele — pending só conta o que ainda NÃO entrou na janela de antecipação, e este campo só o que já entrou. Somar os dois não conta nada duas vezes. Antecipação não é operação da API pública.

Example:

"2.49"

heldByRefund

string<decimal>

required

Retido por pedido de reembolso em análise e já descontado de available — a parcela do bloqueio que o saque de fato recusa. Quando refundBlocked vem preenchido, é um subconjunto dele, nunca maior. Vem "0.00" quando a retenção não está ativa para a sua conta; quando a apuração de refundBlocked falha, continua trazendo o valor descontado de available.

Example:

"2.49"

refundBlocked

string<decimal> | null

required

Total bloqueado por pedidos de reembolso em processamento: a soma de todas as partes da sua conta nesses pedidos, independentemente de o dinheiro já ter liberado ou não. Só a fatia heldByRefund dele está descontada de available; o resto já está fora de pending e de reserved. available, pending, reserved, anticipatable e refundBlocked são parcelas disjuntas — cada real aparece em no máximo um desses campos, então somá-los não conta nada duas vezes. A soma não é o patrimônio da conta: há dinheiro a receber fora das cinco.

Vem null quando não há número a publicar: a retenção não está ativa para a sua conta, ou a apuração falhou nesta chamada. null não é zero — tratá-lo como zero esconde um bloqueio que pode existir. Zero de verdade vem "0.00".

Example:

"2.49"

refundBlockedFromPending

string<decimal> | null

required

A parte de refundBlocked que está descontada de pending. Não é refundBlocked - heldByRefund: essa diferença mistura esta fatia com a de reserved e com o retido que não aparece em nenhum outro campo.

Acompanha refundBlocked: vem null exatamente quando ele vem null, e "0.00" só quando a apuração aconteceu e nada foi descontado de pending.

Example:

"2.49"

refundBlockedFromReserved

string<decimal> | null

required

A parte de refundBlocked que está descontada de reserved — é o que distingue a reserva retida do pendente retido.

As fatias não somam refundBlocked. refundBlockedFromPending + refundBlockedFromReserved + heldByRefund pode ser menor que ele, e a diferença é real: é o retido que não aparece em nenhum outro campo — pendente já dentro da janela de antecipação e venda parcialmente antecipada ainda não liberada.

Example:

"2.49"

Comece aqui

Conceitos

Cakto SDK

CaktoMCP

Pagamentos

Pedidos

Reembolsos

Chargeback e MED

Webhooks

Produtos

Checkouts

Ofertas

Order Bumps

Clientes

Saques

Taxas e Prazos

Juro de Parcelamento

Assinaturas

Saldo

Escopo

O que é este endpoint?

`refundBlocked` e `heldByRefund` não são o mesmo número

De onde saiu cada fatia

As cinco parcelas não se sobrepõem

`available` pode ser negativo

Valores em string

Exemplo

Boas práticas

Authorizations

Query Parameters

Response

​Escopo

​O que é este endpoint?

​refundBlocked e heldByRefund não são o mesmo número

​De onde saiu cada fatia

​As cinco parcelas não se sobrepõem

​available pode ser negativo

​Valores em string

​Exemplo

​Boas práticas

Authorizations

Query Parameters

Response

Escopo

O que é este endpoint?

`refundBlocked` e `heldByRefund` não são o mesmo número

De onde saiu cada fatia

As cinco parcelas não se sobrepõem

`available` pode ser negativo

Valores em string

Exemplo

Boas práticas