Balance and withdrawals
Money you collect is yours the moment your customer approves the prompt. There is no holding period. Here is exactly where it sits and how to take it.
Two numbers, not one
/v1/balancecurl 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 | Payments the network has accepted but not yet confirmed: a prompt sitting on somebody's phone. Not money yet, and not counted as yours. |
available | What you can pay out or withdraw right now, after fees. A collection lands here the moment it succeeds. |
No holding period
available and you can withdraw it. The one thing you need first is a verified business, because Rwandan law requires us to know who is taking payments through our rails: that is a legal requirement, not a buffer we keep for our own convenience.Where a payment's money goes
Following one 20,000 RWF collection all the way through:
| When | pending | available | What happened |
|---|---|---|---|
| You create the payment | no change | no change | A prompt goes to your customer's phone. Nothing has moved; the payment is `pending`. |
| Customer approves | no change | +19,500 | The full 20,000 arrives, our 500 fee comes off, and the rest is withdrawable straight away. |
| You withdraw | no change | −19,500 | 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 and kept on separate books. Both are real money, and only the live one is withdrawable: withdrawing is what verification gates. An app in test mode reading /v1/balancesees 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. Live and test balances are one balance: both are real money, and a withdrawal draws on both. |
| Fee | 2.5%, the same as a cash in, on top of the amount |
| Minimum | 10,000 RWF. The network does not send less. |
| Speed | Seconds, like any payout. |
Set a payout number first