Balance and withdrawals

Money you have collected sits with us for a day, then becomes available to pay out or withdraw. Here is exactly where it is in between.

Two numbers, not one

GET/v1/balanceApp key

Read your balance

curl https://api.xendlypay.com/v1/balance \
  -H "Authorization: Bearer $XENDLY_KEY"

{
  "success": true,
  "payload": {
    "currency": "RWF",
    "mode": "live",
    "pending": 12000,
    "available": 48500
  },
  "timestamp": "2026-09-12T09:14:02.000Z"
}

	What it is
`pending`	Collections that have succeeded but not yet matured. Real money, genuinely yours, not yet movable. It becomes available 24 hours after each payment succeeded.
`available`	What you can pay out or withdraw right now, after fees.

Why the wait

A collection that is minutes old can still be disputed or reversed by the network. Paying it straight out would mean occasionally paying out money that then walks back in the other direction, and that gap is paid for by somebody. 24 hours is the window where that stops happening.

Where a payment's money goes

Following one 20,000 RWF collection all the way through:

When	pending	available	What happened
Customer approves	+19,380	no change	The full 20,000 arrives; our 620 fee comes off immediately.
24h later	−19,380	+19,380	It matures. Nothing about the amount changes, only which bucket it is in.
You withdraw	no change	−19,380	It leaves for your own MoMo number.

Every one of those movements is a double-entry ledger transaction whose entries sum to zero. Balances are derived by summing entries, never stored in a column and adjusted, so a balance cannot drift away from the transactions that produced it, and every franc has a row naming where it came from.

Test and live never mix

Balances are scoped to a mode. Your test balance is simulated money in a simulated ledger; your live balance is real. A test key reading /v1/balance sees only test money, and no arithmetic anywhere in the system adds the two together.

Withdrawing

A withdrawal moves your available balance to the mobile money number on your account. It runs through exactly the same code as a payout, so there is one money-moving path to keep correct rather than two. All that differs is who asked and where it goes.


Where	Dashboard → Withdraw
Destination	The payout number on your account. Not chosen per withdrawal; that is what payouts are for.
Requires	A verified business. A test balance cannot be withdrawn; it is not money.
Fee	None. We absorb it.
Speed	Seconds, like any payout.

Set a payout number first

Withdrawals refuse with a 400 until there is a number on the account. Set it in Settings . Set it to a number you control, because a withdrawal, like every payout, cannot be pulled back.

Not yet built

Bank withdrawals. Everything today lands on a mobile money wallet. Moving a balance to a BK or Equity account is a different rail with different settlement times and a different compliance conversation, and we would rather not have a half-built version of it. If your volume makes MoMo withdrawal limits painful, tell us. That is the signal that moves it up the list.

← Refunds Apps and keys →