Your balance is not a single number. Money that a customer has successfully paid may not yet be money you can pay out, and money you have committed to a payout is no longer money you can spend twice.

Understanding the distinction prevents the most common payout failure: an insufficient funds error on an account that appears to have plenty in it.

Balance States

Alongside these, your balance tracks cumulative totals for collections and fees.

Balances are held per currency and per rail, not as one global pot. A healthy NGN balance does not fund a KES payout.

Why A Successful Payment Is Not Immediately Spendable

When a customer pays, the collection is recognised straight away, but the underlying provider has not necessarily released the funds. Until it does, the money sits in pending settlement.

This is why charge.success is not a signal that you can now make a payout of the same size. It means the customer paid. Whether you can move that money depends on whether it has been released.

Two different questions, two different checks:

• Did the customer pay? — verify the transaction.
• Can I pay out? — check available balance.

Reserved Funds

When you initiate a payout, the amount plus its fees are reserved before the money actually leaves. The reservation prevents you spending the same balance twice while the transfer is in flight.

When the payout completes, the reservation is consumed. If the payout fails, the reservation is released back to available.

This means a payout that is still in flight has already reduced what you can spend, even though it has not yet arrived with the beneficiary.

Checking Available Balance

-H "x-api-key: your_secret_key"

GET {{host}}/v1/wallets/balance

See Retrieve Wallet Balance for the full response.

Before You Pay Out

Kyshi checks that your available balance covers both the payout amount and the payout fees. If it does not, the request is rejected with an insufficient funds error.

Size your payouts accordingly:

const { availableBalance } = await kyshi.virtualAccounts.getBalance('NGN');

// Leave room for fees rather than attempting the full balance.
if (availableBalance < payoutAmount + estimatedFees) {
  return deferPayout();
}

Attempting to pay out your exact available balance will usually fail, because the fee has nowhere to come from. See Fees And Who Pays Them.

Virtual Account Collections

Virtual account collections move through the balance in two steps: the credit is recognised when it arrives, then completed once it is confirmed.

Overpayments are handled separately again. When a customer sends more than expected, the excess is held aside pending refund rather than silently added to your spendable balance. This is why an OVERPAID collection does not increase your available balance by the full amount the customer sent. See Statuses And Lifecycles.

Adjustments

Balances can also move through credits and debits that are not tied to a customer payment or a payout — corrections, chargebacks, and manual treasury operations.

These appear in your balance history. If a balance moves without a corresponding transaction in your own records, an adjustment is the likely explanation; your dashboard shows the reason.

Reconciling Balances

A balance is the running result of everything that has happened to it. To reconcile:

available
  = released collections
  − fees
  − completed payouts
  − reserved (in-flight payouts)
  ± adjustments

If your figure and Kyshi's disagree, the discrepancy is almost always one of: a payout still reserved rather than completed, collections still pending settlement, or an adjustment you have not accounted for. Check those three before anything else.

Next

• Settlements — how balances become bank transfers
• Fees And Who Pays Them — what is deducted
• Transfers — making payouts