Make every shilling clear.
Understand the wallet principal, phone charge, recipient amount and fees before creating a payment.
What amount means
All current payment operations use UGX. Send amounts as decimal strings, such as "500.00", rather than JSON numbers or binary floating-point values.
| Field | Collection | Disbursement |
|---|---|---|
amount | Wallet principal to receive. | Amount the recipient receives. |
fee | Added to the payer’s charge. | Added to the wallet’s debit. |
gross_amount | Total payer charge. | Total wallet debit. |
| Explicit fields | payer_charge, wallet_credit | recipient_amount, wallet_debit |
Collections round the total charge up
The requested principal is preserved. The collection fee is calculated to two decimals, then principal plus fee is rounded up to a whole shilling. The actual fee equals the rounded total minus the principal.
| Example principal | Illustrative fee at 3.9% | Total phone charge |
|---|---|---|
| UGX 500.00 | UGX 20.00 | UGX 520.00 |
| UGX 500.25 | UGX 19.75 | UGX 520.00 |
Use the quote endpoint for the current configured fee. Show the actual total to the payer before requesting approval.
Payouts use whole UGX
The disbursement principal must be a whole-shilling amount, such as "500.00". Fractional-shilling payouts are rejected before a debit or dispatch. The available wallet balance must cover the principal and fee.
Limits and quote validity
The current principal ceiling is UGX 5,000,000 per payment. A quote checks amount rules and returns current prices, but does not reserve funds, lock a future fee, or guarantee live provider availability.