ZypfyDocs Acessar painel
Guia de integração

Saldo

O endpoint de saldo retorna o estado atual da sua carteira na Zypfy. É útil para pre-check antes de disparar um saque e para reconciliar o saldo gerencial no seu ERP.

Endpoint

código
GET https://api.zypfy.com/api/accounts/balance

Headers: Authorization: Bearer SEU_TOKEN.

Resposta 200 OK

json
{
  "message": "Wallet balance retrieved successfully.",
  "total_balance": 1000.00,
  "balance": 800.00,
  "balance_block": 200.00,
  "balance_mxn": 0.00,
  "available_balance": 800.00
}

Semântica dos campos

CampoDescrição
balanceSaldo disponível para saque no momento. É o valor que você pode efetivamente mover.
balance_blockSaldo bloqueado — reservado por saques em processamento que ainda não foram liquidados. Não pode ser movido.
total_balancebalance + balance_block. Reflete o total que você "tem" na Zypfy, incluindo o que está preso em saques pendentes.
available_balanceAlias de balance (mesma coisa — há pelo histórico de API).
balance_mxnSaldo em pesos mexicanos (MXN), alimentado pelos Depósitos MXN. Carteira separada do BRL. Não é sacável direto: converta para reais com POST /api/accounts/mxn/convert antes de sacar. Vale 0 se sua conta não usa o México.

Por que existe balance_block?

Quando você cria um saque:

  1. A Zypfy move amount + fee de balance → balance_block. Esse valor fica reservado.
  2. Se o saque for COMPLETED, o valor é debitado de balance_block (sai da carteira).
  3. Se o saque for FAILED, o valor volta de balance_block para balance.

Isso evita que você disparar N saques concorrentes com saldo insuficiente real (cada um reserva sua fatia no block).

Exemplo: pre-check antes de saque

javascript
async function saqueSeguro({ amount, pix_key, key_type, external_id }) {
  const token = await getToken();

  // 1. Pre-check do saldo
  const { data: saldoResp } = await axios.get(
    'https://api.zypfy.com/api/accounts/balance',
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const taxaEstimada = amount * 0.02; // sua fee contratada (exemplo)
  const necessario = amount + taxaEstimada;

  if (saldoResp.balance < necessario) {
    throw new Error(
      `Saldo insuficiente: disponível R$ ${saldoResp.balance.toFixed(2)}, ` +
      `necessário R$ ${necessario.toFixed(2)}.`
    );
  }

  // 2. Disparar saque
  const { data } = await axios.post(
    'https://api.zypfy.com/api/withdrawals/withdraw',
    { amount, pix_key, key_type, external_id },
    { headers: { Authorization: `Bearer ${token}` } }
  );

  return data;
}

Códigos de erro

HTTPRespostaCausa
401Unauthorized.Token ausente.
403—Token inválido ou expirado.
404Wallet not found for this user.Carteira não existe para este usuário (conta recém-criada sem carteira provisionada — contatar suporte).

Boas práticas