Send money — money out

Send money out to somebody — the money-out entry point. This is what your app calls to pay a person: a seller payout, a withdrawal to a user’s momo wallet, a payroll run, a refund you are settling manually. You name an amount, a destination (momo number, bank account, or a provider wallet) and the gateway debits YOUR float and credits them.

ONE call. Providers that need a quotation-then-execute handshake do it INTERNALLY; that two-call shape never leaks to you, which is also why you never have to race a quote’s expiry window.

Returns 201 with a gateway reference. Payouts are asynchronous — pending is the normal first answer, and the webhook (or GET /v1/payouts/{reference}) tells you when it actually landed.

Idempotency-Key is required. A retried payout without one is a double payment; with one, a replay returns the original response verbatim and no second transfer happens.

Check the corridor first. Capability is per (country, currency, direction, method), never per country — Nigeria takes bank payouts but no momo, Rwanda momo but no bank, Tanzania only wallet-to-wallet. GET /v1/reference/corridors is the matrix to render your UI against; a route that does not exist is a 422 here, not a surprise at settlement.

Cross-currency payouts REQUIRE amount_type. It decides whether the sender pays a fixed amount or the recipient RECEIVES one — a materially different product, so there is no silent default.

Refused BEFORE any provider call, with no money moved: an amount over your float, outside a corridor’s min/max window, over your velocity cap, or (in test mode) over the test ceiling. A 422 is therefore always safe — nothing was sent.

The provider’s fee is charged ON TOP of amount_minor, and it comes out of your float. A UGX 10,000 bank payout debits the wallet UGX 15,400 at current rates (bank fees are far higher than mobile money — UGX 5,400 versus UGX 1,000 on a comparable momo transfer). fees_minor on the response carries the provider’s own figure, and your float is debited both the amount and the fee when the payout settles. Budget for amount + fee, not the amount alone.

Your float is checked against amount + fee, so a payout can never take you negative. Before reserving anything the gateway asks the provider what this exact transfer will cost and holds that full total, refusing the payout if it does not fit — the same rule the aggregators enforce, applied here where you still get a usable error instead of a provider rejection. On refusal, error.details carries amount_minor, estimated_fee_minor, shortfall_minor, and — when a cheaper rail would fit — suggested_method with suggested_total_minor, so an unaffordable bank payout can point you at momo rather than leaving you to guess.

Call POST /v1/payouts/quote yourself to show the same figure on a confirm screen: total_amount_minor is what leaves your float. Quoting is free, moves no money, and works even when the amount is unaffordable.

To withdraw a whole balance, set deduct_fee_from_amount: true and pass the balance as amount_minor. The fee is taken out of it rather than added on top, so the total lands exactly on the balance. The same flag works on /quote, so a confirm screen shows the reduced destination_amount_minor the recipient will actually receive.

Note the interaction with per-method minimums: the reduction happens BEFORE the minimum is checked, so a UGX 10,000 withdraw-all by BANK nets 4,600 and is refused against bank’s own 10,000 floor. By momo the same 10,000 nets 9,000 and succeeds. error.details.suggested_method points at the rail that fits.

Minimums are per corridor AND per method. Some rails impose a floor the others do not: a Uganda BANK payout is refused below UGX 10,000, while momo on the same corridor is accepted from UGX 500. An amount under the floor is amount_below_minimum, and error.details names the minimum_minor that applies to the method you sent — check it there rather than hardcoding the figure, since floors are provider-set and change without a release.