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
| Campo | Tipo | Descrição |
|---|---|---|
livemode | boolean | false para uma chave sk_test_: todos os valores vêm zerados |
merchant_balance | Money | Saldo disponível total (Pix + cartão) |
merchant_balance_pix | Money | Parte do saldo disponível vinda de vendas Pix |
merchant_balance_card | Money | Parte do saldo disponível vinda de vendas no cartão. Pode ficar negativa (ver abaixo) |
withdrawable_pix | Money | Quanto um saque com source: "pix" pode sacar agora |
withdrawable_card | Money | Quanto um saque com source: "card" pode sacar agora |
reserve_held | Money | Retido como reserva; não pode ser sacado |
card_pending_release | Money | Vendas no cartão ainda a receber (não liberadas); não pode ser sacado |
fees_earned_lifetime | Money | Total de taxas acumuladas (se sub-adquirente) |
refunds_out_lifetime | Money | Total de reembolsos emitidos |
acquirer_in | Money | Total recebido dos adquirentes |
pending_capture | Money | Cobranç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_pix | merchant_balance_card | withdrawable_pix | withdrawable_card |
|---|---|---|---|
| 10000 | 3000 | 10000 | 3000 |
| 10000 | -2000 | 8000 | 0 |
Nota: todos os valores são em centavos (inteiros). R$ 15.000,00 =
"1500000".