Paystack settles funds to Kenyan merchants via bank account or M-Pesa wallet. Bank settlement is the default, configured during onboarding with your bank name and account number. M-Pesa settlement sends funds directly to your registered M-Pesa number. Settlement timelines vary by account type and payment method. Fees are deducted before settlement, so you receive the net amount.
When a customer pays you through Paystack, the money does not go directly into your bank account or M-Pesa wallet. It goes into Paystack's collection account first. Paystack holds the funds, deducts its fees, and then sends the remainder to you on a schedule. That "sending" step is settlement.
This is important to understand because there is a gap between "customer paid" and "you have the money." A customer paying you KES 5,000 at 3 PM on Wednesday does not mean you have KES 5,000 in your bank by 3:01 PM. Depending on your settlement schedule, you might see that money the next day, or a few days later.
For developers, settlement matters for three reasons:
Settlement is not the same as Paystack Transfers. Settlement is automatic: Paystack sends your accumulated balance to you on a schedule. Transfers are manual: you explicitly send money from your Paystack balance to a recipient using the Transfers API. You can do both, but they serve different purposes.
Bank account settlement is the default for Kenyan Paystack merchants. During onboarding, you provide your bank name, branch, and account number. Paystack settles your accumulated balance to that account on your settlement schedule.
How to configure it:
Which banks work: Paystack supports settlement to all major Kenyan banks. KCB, Equity, Co-operative, NCBA, Absa, Standard Chartered, DTB, Family Bank, and others. The full list is available in the settlement configuration section of your dashboard. If your bank is not listed, contact Paystack support.
Settlement timing: Bank settlements process on business days. The exact schedule depends on your account tier and your agreement with Paystack. [TODO: verify current settlement schedules on Paystack dashboard or support documentation]
Some practical things to know:
Get weekly developer tips
Join 25,000+ developers. Practical guides, job tips, and new content — straight to your inbox.
No spam. Unsubscribe anytime.
Some Kenyan merchants can receive settlement directly to their M-Pesa wallet. This sends your accumulated balance to the M-Pesa phone number registered on your Paystack account.
How to configure it:
When M-Pesa settlement makes sense:
Limitations to know:
Paystack settlement is net of fees. This is the single most important thing to understand about settlement, and the thing most likely to confuse your finance team.
Here is what happens:
The amount that arrives in your bank is not the sum of your transactions. It is the sum of your transactions minus fees. If you processed KES 100,000 in transactions today and Paystack's total fees on those transactions were KES 3,500, your settlement will be KES 96,500.
For your reconciliation logic:
// What NOT to do: match the settlement amount to the transaction total
// This will always be off by the fee amount
// What to do: track gross, fees, and net separately
const transactions = await getTransactionsForSettlementPeriod(startDate, endDate);
let grossTotal = 0;
let feesTotal = 0;
for (const txn of transactions) {
grossTotal += txn.amount; // What the customer paid (in kobo/cents)
feesTotal += txn.fees; // What Paystack charged (in kobo/cents)
}
const expectedNetSettlement = grossTotal - feesTotal;
// Compare expectedNetSettlement to what actually arrived in your bank
// They should match. If they don't, investigate.
console.log('Gross:', grossTotal / 100);
console.log('Fees:', feesTotal / 100);
console.log('Expected net:', expectedNetSettlement / 100);
The Paystack API returns the fee for each transaction in the transaction object (data.fees). Use this to calculate expected settlement amounts. The Paystack dashboard also provides settlement reports that break down each settlement batch by transaction, showing the gross, fees, and net for each one.
For comprehensive reconciliation patterns, see Reconciling M-Pesa Payments Received Through Paystack.
The question every merchant asks: "When will I get my money?"
The honest answer is that it depends. Paystack's settlement timelines for Kenya are determined by several factors:
What to expect:
Check your Paystack dashboard for your specific settlement schedule. The dashboard shows your next expected settlement date and the transactions included in that settlement. [TODO: verify current default settlement timeline for Kenya on Paystack dashboard]
Practical implications for your code:
charge.success webhook means the customer paid successfully. It does not mean the money is in your bank. If you are selling physical goods, you can ship on payment confirmation. But if you need the money in your account before taking action (e.g., paying a supplier), you need to wait for settlement.The decision comes down to your business size, your cash flow needs, and your accounting setup.
Choose bank settlement when:
Choose M-Pesa settlement when:
Can you use both? Check with Paystack support whether your account supports split settlement or whether you can change the settlement destination. Some account types may allow you to switch between bank and M-Pesa, but simultaneous settlement to both destinations may not be available. [TODO: verify with Paystack whether split settlement to both bank and M-Pesa is supported in Kenya]
If you need to distribute funds to multiple destinations after settlement (e.g., settle to your bank, then send operational funds to your M-Pesa), you can use Paystack Transfers to move money from your Paystack balance to specific recipients before the settlement cycle runs.
Paystack provides API endpoints for querying your settlement data programmatically. This is useful if you want to build automated reconciliation, settlement tracking dashboards, or alerting systems.
Fetching settlements:
// List settlements
const response = await fetch('https://api.paystack.co/settlement', {
method: 'GET',
headers: {
Authorization: 'Bearer sk_live_YOUR_SECRET_KEY',
},
});
const settlements = await response.json();
for (const settlement of settlements.data) {
console.log('Settlement ID:', settlement.id);
console.log('Amount:', settlement.total_amount / 100, 'KES');
console.log('Status:', settlement.status);
console.log('Settlement date:', settlement.settled_date);
console.log('Total transactions:', settlement.total_processed);
}
Fetching transactions in a settlement:
// Get transactions in a specific settlement
const settlementId = 12345;
const response = await fetch(
`https://api.paystack.co/settlement/${settlementId}/transactions`,
{
method: 'GET',
headers: {
Authorization: 'Bearer sk_live_YOUR_SECRET_KEY',
},
}
);
const txns = await response.json();
for (const txn of txns.data) {
console.log('Reference:', txn.reference);
console.log('Gross amount:', txn.amount / 100, 'KES');
console.log('Fee:', txn.fees / 100, 'KES');
console.log('Net:', (txn.amount - txn.fees) / 100, 'KES');
}
Use this data to build a daily reconciliation job that compares the settlement amounts against your internal records. Any discrepancy (settlement amount does not match expected net total) should trigger an alert for your finance team to investigate.
The pillar engineering guide covers the Balance and Settlement APIs in more detail.
These are the problems Kenyan merchants actually hit with settlement. Know them before they hit you.
1. Wrong bank account details. This is the most common cause of failed settlements. A digit is wrong in the account number, or the bank name does not match the branch. Paystack cannot send money to an account that does not match. Fix: double-check your details in the dashboard. If you change banks, update your settlement account immediately.
2. Dormant bank account. Some Kenyan banks classify accounts as dormant after a period of inactivity. A dormant account may reject incoming credits. Fix: contact your bank to reactivate the account before configuring it for settlement.
3. M-Pesa wallet limits exceeded. If your settlement amount exceeds your M-Pesa daily or wallet balance limit, the settlement fails. This is especially common for merchants who grow quickly and did not anticipate the volume increase. Fix: upgrade your M-Pesa account tier (full KYC verification increases limits) or switch to bank settlement.
4. Settlement delays during holidays. Kenyan public holidays (Jamhuri Day, Mashujaa Day, Madaraka Day, etc.) are not business days. If your settlement falls on a holiday, it moves to the next business day. December is particularly tricky with multiple holidays. Plan your cash flow accordingly.
5. Refund and chargeback deductions. If you process refunds or receive chargebacks, the refunded amount is deducted from your next settlement. This can surprise merchants who expected a certain settlement amount. Your reconciliation needs to account for refunds and chargebacks in the settlement calculation.
6. Currency mismatch. If you accept payments in USD (from international customers) and settle in KES, the settlement involves a currency conversion. The exchange rate Paystack uses and the timing of the conversion affect the final KES amount. Track the expected amount in both currencies.
Settlement is not the glamorous part of payment integration. But it is the part that determines whether your business has money in the bank. Getting it wrong means cash flow surprises, reconciliation headaches, and confused conversations with your accountant.
McTaba's M-Pesa Integration micro-course (KES 9,999) covers payment reconciliation, settlement tracking, and the bookkeeping patterns that keep your financials accurate. The 26-week bootcamp (KES 120,000) covers the full payment lifecycle, from checkout to settlement to payout, as part of building production-ready applications.
KES 2,999
The definitive guide to building payment systems with Paystack — from your first transaction to production-grade payment infrastructure across Africa. 9 modules, 47 lessons. Free preview available.
Start Paystack Course