KYC tier limits at the ledger
Risk controls implemented as accounting code, not application logic.
By Solomon Ajayi · Free to read, no signup
Your fintech runs three KYC tiers. Tier 1 (basic phone-number verification) caps wallet balance at ₦300,000. Tier 2 (full ID) caps at ₦5,000,000. Tier 3 (biometric + address) is unlimited. When a deposit would push a user's wallet over their tier cap, you don't just block it, you accept the cash AND park the overflow in a 'Pending KYC Upgrade' liability. The user is notified to upgrade. This is risk control implemented at the LEDGER level, where it's bulletproof, instead of in application code where every new code path is a new bypass.
KYC tier limits are a regulatory cap on how much a lightly verified user is allowed to hold. The naive response is to reject any deposit that would breach the cap, but you usually cannot: the cash has already arrived at the sponsor bank, and bouncing it is both bad product and operationally messy. So you accept the money and split where it lands instead of refusing it.
The split happens in the credit. The full deposit debits the FBO, but the credit divides: enough goes to User Wallet to fill it exactly to the tier cap, and the overflow goes to a Pending KYC Upgrade liability the user cannot see or spend until they verify. The entry still balances, debits equal credits, but now the ledger itself records both the money you accepted and the portion you are legally holding back. When the user upgrades, you simply move the held amount from Pending KYC Upgrade into their wallet.
The real lesson is where the control lives. Enforce tier limits in application code and every new endpoint that touches a wallet is a fresh chance to forget the check, a new bypass waiting to ship. Enforce it at the moment of credit in the ledger and there is exactly one place the rule can be violated. Better still, the ledger becomes regulator evidence: an auditor can query for overflows held past thirty days and read your compliance posture straight off the books.
Worked example, step by step
Set the stage: Tier 1 user has ₦250,000 in wallet
Existing state: user has ₦250,000 in their wallet. Their KYC tier (Tier 1) caps the wallet at ₦300,000. They have ₦50,000 of headroom.
| Account | Debit | Credit |
|---|---|---|
| FBO at Sponsor Bank (1300) | ₦250,000.00 | |
| User Wallet (2000) | ₦250,000.00 |
Standard funding state. FBO ₦250,000, User Wallet ₦250,000.
₦100,000 deposit arrives, ₦50,000 fits, ₦50,000 overflows
Money lands in the FBO. But the user's wallet only has ₦50,000 of room before hitting the ₦300,000 tier cap. The ledger SPLITS the credit: ₦50,000 to wallet (fills to cap), ₦50,000 to Pending KYC Upgrade (held until they verify).
| Account | Debit | Credit |
|---|---|---|
| FBO at Sponsor Bank (1300) | ₦100,000.00 | |
| User Wallet (2000) | ₦50,000.00 | |
| Pending KYC Upgrade (2010) | ₦50,000.00 |
FBO UP ₦100,000 (full deposit arrived). User Wallet UP ₦50,000 (filled to ₦300,000 cap). Pending KYC Upgrade UP ₦50,000 (overflow, the user does NOT see this in their app until they upgrade). Debits 100,000 = Credits 50,000 + 50,000. Balanced. This is the cleanest place to enforce the limit, at the moment of credit, not later.
User upgrades to Tier 2, release the held ₦50,000
User uploads their ID. Compliance approves. New cap: ₦5,000,000. Move the held ₦50,000 from Pending KYC Upgrade into the user's actual wallet.
| Account | Debit | Credit |
|---|---|---|
| Pending KYC Upgrade (2010) | ₦50,000.00 | |
| User Wallet (2000) | ₦50,000.00 |
Pending KYC Upgrade DOWN ₦50,000 (cleared). User Wallet UP ₦50,000 (now ₦350,000, well within the new Tier 2 cap). FBO UNCHANGED, the money was always at the sponsor bank; only the classification on your books moved.
Takeaway
KYC tier limits are risk controls. The wrong place to enforce them is application code (bypassable by every new code path that touches user wallets). The right place is the ledger: split deposits over the cap into wallet + pending-upgrade liability. The ledger itself becomes regulator-evidence that you respected tier limits, auditors can literally query 'show me overflows held > 30 days' and see your compliance posture. CBN tier rules in particular require this kind of accountable enforcement, not just UI gates.
Practice this on a real ledger
Reading is half of it. Open this lesson in the lab to post the entries yourself against a real Postgres-backed double-entry ledger, with the validation on. Free, your sandbox is yours.