DOCS

Balance

API para consulta do saldo da conta.

GET /v1/balance

Retorna o saldo consolidado da conta do merchant.

Exemplo

curl https://api.kirvex.com.br/v1/balance \
  -u sk_test_...:

Resposta (200)

{
  "object": "balance",
  "livemode": true,
  "merchant_balance": { "amount": "1500000", "currency": "BRL" },
  "merchant_balance_pix": { "amount": "1200000", "currency": "BRL" },
  "merchant_balance_card": { "amount": "300000", "currency": "BRL" },
  "withdrawable_pix": { "amount": "1200000", "currency": "BRL" },
  "withdrawable_card": { "amount": "300000", "currency": "BRL" },
  "reserve_held": { "amount": "40000", "currency": "BRL" },
  "card_pending_release": { "amount": "250000", "currency": "BRL" },
  "fees_earned_lifetime": { "amount": "50000", "currency": "BRL" },
  "refunds_out_lifetime": { "amount": "25000", "currency": "BRL" },
  "acquirer_in": { "amount": "2000000", "currency": "BRL" },
  "pending_capture": { "amount": "100000", "currency": "BRL" }
}

Campos

CampoTipoDescrição
livemodebooleanfalse para uma chave sk_test_: todos os valores vêm zerados
merchant_balanceMoneySaldo disponível total (Pix + cartão)
merchant_balance_pixMoneyParte do saldo disponível vinda de vendas Pix
merchant_balance_cardMoneyParte do saldo disponível vinda de vendas no cartão. Pode ficar negativa (ver abaixo)
withdrawable_pixMoneyQuanto um saque com source: "pix" pode sacar agora
withdrawable_cardMoneyQuanto um saque com source: "card" pode sacar agora
reserve_heldMoneyRetido como reserva; não pode ser sacado
card_pending_releaseMoneyVendas no cartão ainda a receber (não liberadas); não pode ser sacado
fees_earned_lifetimeMoneyTotal de taxas acumuladas (se sub-adquirente)
refunds_out_lifetimeMoneyTotal de reembolsos emitidos
acquirer_inMoneyTotal recebido dos adquirentes
pending_captureMoneyCobranças autorizadas aguardando captura

Saldo Pix e saldo cartão

O saldo disponível é mantido em dois saldos: o das vendas Pix e o das vendas no cartão. merchant_balance continua sendo o total dos dois — nenhuma integração existente vê o saldo diminuir por causa da separação.

Cada saque sai de um único saldo, escolhido no campo source de POST /v1/payouts. O limite de cada um é withdrawable_pix / withdrawable_card, nunca merchant_balance: um saque Pix não usa o saldo cartão, nem o contrário.

Um saldo pode ficar negativo — por exemplo, um reembolso de cartão feito antes de a venda ser liberada. Essa dívida é descontada do que o outro saldo pode sacar, para que os dois saques juntos nunca passem do que existe de fato:

merchant_balance_pixmerchant_balance_cardwithdrawable_pixwithdrawable_card
100003000100003000
10000-200080000

Nota: todos os valores são em centavos (inteiros). R$ 15.000,00 = "1500000".

On this page