Wallets
A wallet is where a subscriber’s money lives. Think of it like a digital version of a bank account - it holds your balance and tracks every Leone that goes in or out.What is a Wallet?
When you register on OLIVE, the system automatically creates a wallet for you. This wallet:- Holds your SLE (Sierra Leonean Leone) balance
- Is linked to your subscriber account
- Is accessed via your NFC card or WhatsApp
- Is protected by your 4-digit PIN
How Balances Work
The Single Currency
OLIVE wallets only hold Sierra Leonean Leones (SLE). There’s no multi-currency support - everything is in Leones. This keeps things simple for users in Sierra Leone. If you receive money, it goes into your SLE balance. If you pay someone, it comes from your SLE balance.Storage Format: Minor Units
Balances are stored as whole numbers without decimals. While the Leone doesn’t have fractional units in practice, this approach prevents floating-point errors that can occur with decimal math.| What You See | What’s Stored |
|---|---|
| 1,500 SLE | 1500 |
| 25,000 SLE | 25000 |
| 3,500,000 SLE | 3500000 |
500000 in the database equals 500,000 Leones.
When is a Wallet Created?
Your wallet is created in two scenarios:1. At Registration
When you first register on OLIVE (via WhatsApp or through an agent), the system creates your subscriber record AND your wallet account. You start with a zero balance.2. First Incoming Money
If somehow a subscriber exists without a wallet (edge case), OLIVE creates one automatically when they first receive money. This ensures nobody loses funds due to a missing account. The system runs a background job (SeedSubscriberWallets) that ensures every subscriber has a wallet.
Your Wallet Balance is Real-Time
Your balance updates instantly with every transaction: Scenario: You have 50,000 SLE and buy groceries for 12,000 SLE- Before purchase: Balance = 50,000
- You tap your card at the POS terminal
- Transaction created, validated, executed
- Your wallet debited 12,000
- After purchase: Balance = 38,000
What Can You Do With Your Wallet?
Add Money (Increase Balance)
| Method | How It Works |
|---|---|
| Agent Cash-In | Walk into any OLIVE agent shop, hand them cash, and they credit your wallet |
| VULT Funding | If linked to VULT, deposit cash at VULT locations to fund your OLIVE wallet |
| Receive Transfer | Someone sends you money from their OLIVE wallet |
| Refund | A merchant refunds a previous purchase |
Spend Money (Decrease Balance)
| Method | How It Works |
|---|---|
| POS Payment | Tap your NFC card at a merchant to pay for goods/services |
| Send Transfer | Send money to another OLIVE user via WhatsApp or agent |
| Agent Cash-Out | Visit an agent, request cash, enter your PIN, receive physical money |
Transaction Limits Based on KYC
Your wallet has limits based on your KYC (Know Your Customer) level. These limits protect against fraud and ensure regulatory compliance.KYC Level 1 (Phone Only)
You’ve only verified your phone number. This is the most restricted level.| Limit Type | Amount |
|---|---|
| Maximum Balance | 500,000 SLE |
| Single Transaction | 50,000 SLE |
| Daily Total | 200,000 SLE |
| Monthly Total | 2,000,000 SLE |
KYC Level 2 (ID Verified)
You’ve uploaded your national ID and it’s been verified.| Limit Type | Amount |
|---|---|
| Maximum Balance | 2,000,000 SLE |
| Single Transaction | 200,000 SLE |
| Daily Total | 1,000,000 SLE |
| Monthly Total | 10,000,000 SLE |
KYC Level 3 (Fully Verified)
Full verification with all documents.| Limit Type | Amount |
|---|---|
| Maximum Balance | 10,000,000 SLE |
| Single Transaction | 1,000,000 SLE |
| Daily Total | 5,000,000 SLE |
| Monthly Total | 50,000,000 SLE |
How Limit Enforcement Works
Before any transaction, OLIVE checks:- Balance Check - Do you have enough money?
- Single Transaction Limit - Is this amount within your per-transaction limit?
- Daily Turnover - Have you already hit your daily limit?
- Monthly Turnover - Have you hit your monthly limit?
- Max Balance Check (for receiving) - Would this push you over your max balance?
The Wallet Never Goes Negative
OLIVE wallets cannot have negative balances. Every payment or withdrawal is validated against your current balance before execution. If you have 10,000 SLE and try to pay 15,000 SLE, the transaction fails with “insufficient balance.”Wallet vs. Card: What’s the Difference?
Wallet = Your money (the balance) Card = How you access your money (the key) Think of it like:- Wallet = Bank account
- Card = ATM card / Debit card
Daily Spending Tracking
OLIVE tracks how much you’ve spent today:- Query all completed transactions where you’re the sender
- Filter to today’s date
- Sum up the amounts + fees
- Compare against your daily limit
The Ledger: Your Wallet’s History
Every change to your balance creates a ledger entry. This provides a complete, auditable history of your wallet:| Time | Type | Amount | Balance After | Description |
|---|---|---|---|---|
| 10:00 | credit | +50,000 | 50,000 | Agent cash-in |
| 11:30 | debit | -12,000 | 38,000 | POS payment at Shop A |
| 14:15 | debit | -5,000 | 33,000 | Transfer to Ahmed |
| 16:00 | credit | +20,000 | 53,000 | Received from Maria |
Account Uniqueness
Each subscriber has exactly one SLE wallet. The database enforces this with a unique constraint on(user_id, currency).
This means:
- You can’t have two SLE accounts
- Your balance is always in one place
- No confusion about “which account”
What Happens When Your Account is Blocked?
If your subscriber status becomesblocked:
- Your wallet balance remains intact
- You cannot make any transactions
- You cannot receive money either
- Once unblocked, full access is restored