Saldo (Balance)

Endpoint para consultar o saldo da conta.

GET /v1/balance

Retorna o saldo do usuário autenticado, incluindo saldo total, disponível para saque e retido.

Headers

Authorization: Bearer {access_token}

Exemplo de Request

curl -X GET https://api.misespay.com/v1/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
  "success": true,
  "data": {
    "total": {
      "cents": 150000,
      "amount": 1500.0,
      "formatted": "R$ 1.500,00"
    },
    "available": {
      "cents": 100000,
      "amount": 1000.0,
      "formatted": "R$ 1.000,00"
    },
    "hold": {
      "cents": 50000,
      "amount": 500.0,
      "formatted": "R$ 500,00"
    }
  }
}

Campos da Resposta

Campo	Tipo	Descrição
success	boolean	Indica se a operação foi bem-sucedida
data.total	object	Saldo total da conta
data.total.cents	integer	Valor total em centavos
data.total.amount	number	Valor total em reais
data.total.formatted	string	Valor total formatado (ex: "R$ 1.500,00")
data.available	object	Saldo disponível para saque
data.available.cents	integer	Valor disponível em centavos
data.available.amount	number	Valor disponível em reais
data.available.formatted	string	Valor disponível formatado
data.hold	object	Saldo retido/bloqueado
data.hold.cents	integer	Valor retido em centavos
data.hold.amount	number	Valor retido em reais
data.hold.formatted	string	Valor retido formatado

Tipos de Saldo

Total

Soma de todo o dinheiro na conta (disponível + retido).

Disponível (Available)

Valor que pode ser sacado imediatamente. Este é o saldo usado para validar saques.

Retido (Hold)

Valor temporariamente bloqueado por:

• Vendas em processamento
• Saques pendentes de aprovação
• Revisões de compliance
• Disputas ou chargebacks

Erros Possíveis

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

500 Internal Server Error

{
  "success": false,
  "message": "Erro ao consultar saldo"
}

Formatos de Valores

A API retorna valores em três formatos para facilitar diferentes casos de uso:

Cents (Centavos)

• Tipo: Integer
• Uso: Cálculos precisos, evita problemas de ponto flutuante
• Exemplo: 150000 = R$ 1.500,00

Amount (Reais)

• Tipo: Number (float)
• Uso: Exibição e cálculos simples
• Exemplo: 1500.00

Formatted (Formatado)

• Tipo: String
• Uso: Exibição direta para usuários
• Exemplo: "R$ 1.500,00"

DICA

Para cálculos precisos, sempre use o valor em cents para evitar problemas de arredondamento com números decimais.

Fluxo Recomendado

1. Consultar saldo antes de criar saques
2. Verificar available (não total) para validar se há saldo suficiente
3. Considerar taxa de saque (R$ 0,20) no cálculo
4. Atualizar saldo após operações de venda ou saque

Próximos Passos

• Withdrawals - Criar saques
• Sales - Criar vendas e receber pagamentos