The verdict in three sentences
Beyond a few dozen vendors, manual payment becomes a source of errors and delays: you need an automatic split at collection and a scheduled payout via API. On a 20,000 order at 15 % commission, 17,000 goes to the vendor and 3,000 to the platform, computed automatically. Batching 500 payouts/week instead of 500 manual triggers removes forgotten transfers and makes accounting reconciliation reliable.
Split and payout architecture
The principle: each customer payment is immediately split into vendor share and platform commission, then vendor shares accumulate in a balance until the scheduled payout. Here are the components and their roles.
| Component | Role | Frequency |
|---|---|---|
| Collection webhook | Confirms customer payment | Real time |
| Split engine | Computes vendor share / commission | Per order |
| Vendor ledger | Accrues each vendor's balance | Continuous |
| Payout batch | Groups amounts due | Weekly |
| Disbursement API | Executes transfers (Flutterwave/others) | At batch |
| Reconciliation | Matches payouts to orders | After batch |
Decoupling collection (real time) from payout (batch) is what lets you handle load while keeping the books correct.
Cost per payout and optimal cadence
The cost of an API payout depends on amount and provider. Batching cuts the number of calls and thus fixed fees, but you must balance against vendor wait. Here are 2026 orders of magnitude for a Lagos marketplace.
| Cadence | Payouts/week | Indicative fee cost | Vendor wait |
|---|---|---|---|
| Daily | 3,500 | High | 1 day |
| Twice weekly | 1,000 | Medium | 3-4 days |
| Weekly | 500 | Low | 7 days |
| On-demand | Variable | Per withdrawal | Instant (paid) |
| Threshold 25,000 | Reduced | Optimised | Variable |
In Nigeria, batching 500 payouts/week via a transfers API avoids 500 manual triggers: fewer entry errors, a single reconciliation per batch and a traceable failure rate.
Failure rate and retry strategy
An automatic payout sometimes fails: invalid number, capped wallet, provider down. Good architecture provides smart retry and a failure queue. Here are orders of magnitude.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
| Failure cause | Indicative frequency | Strategy |
|---|---|---|
| Invalid number/account | 1 to 2 % | Notify vendor, correct |
| Wallet cap reached | < 1 % | Retry after 24h |
| Provider unavailable | 0.5 to 1 % | Auto retry x3 spaced |
| Insufficient float | Variable | Alert + top-up |
| Network timeout | 1 to 2 % | Immediate idempotent retry |
The key is idempotence: each payout carries a unique id so a retry never creates a double transfer. Without it, a timeout followed by a retry can pay a vendor twice.
Mini case study
Chioma, founder of a crafts marketplace in Lagos, handles 500 orders/week at an average basket of 20,000 and 15 % commission. The automatic split sends 17,000/order to vendors, about 8,500,000/week in payouts, and retains 1,500,000 in commission. Moving from manual payment to a weekly batch with idempotent retry removes roughly 3 hours of manual work/week and cuts her payout error rate from 4 % to under 0.5 %, avoiding costly vendor disputes.
FAQ
How does the automatic split work? On each payment confirmed by webhook, the engine instantly computes vendor share and commission. On 20,000 at 15 %, the vendor gets 17,000 and the platform 3,000, with no manual step.
Why batch payouts? Grouping 500 transfers into one weekly batch cuts fixed fees, limits entry errors and allows a single reconciliation per cycle instead of 500.
What is idempotence and why is it vital? It means the same payout, even replayed after a timeout, executes only once. Without it, a retry can pay a vendor twice and open a cash gap.
What failure rate should I expect? Expect an order of magnitude of 2 to 4 % cumulative failures (invalid numbers, timeouts, caps). A retry queue and alerts bring net failure to under 0.5 %.
How do I handle insufficient float? An automatic alert triggers a top-up before the batch. Without enough float, payouts queue and vendor wait slips by hours.
Let's talk about your project. We build your automatic split and payout engine with idempotent retry and reconciliation. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionate about digital and entrepreneurship in Africa, Mohamed has been helping Sénégalese businesses with their digital transformation since 2020. Founder of Kolonell, he believes every SME deserves a professional and accessible online présence.
