Documentation Index Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
Use this file to discover all available pages before exploring further.
Subscribers A subscriber is anyone who uses OLIVE to store and move money. When you register, you become a subscriber with your own wallet, identity, and access to the OLIVE financial network.
What is a Subscriber? Think of a subscriber as an OLIVE member. Once registered, you have:
A unique Subscriber ID - Your identifier in the systemA wallet - Where your money livesA 4-digit PIN - To authorize transactionsAccess to NFC cards - Physical cards to make payments
Every financial operation in OLIVE - payments, transfers, cash-in, cash-out - involves subscribers on one or both ends.
How Registration Works When someone registers on OLIVE (via WhatsApp, agent, or dashboard), here’s what happens:
1. Phone Number Check First, OLIVE checks if the phone number is already registered. Sierra Leone numbers can be in local format (077XXXXXX) or international format (+23277XXXXXX). The system normalizes them to international format automatically.
2. National ID Check (Optional) If a national ID is provided, OLIVE checks it’s not already registered. This prevents duplicate accounts.
3. PIN Hashing Your 4-digit PIN is hashed using SHA-256 with your phone number as salt:
hash = SHA256(PIN + phone_number)
This means your PIN is tied to your phone number. If your phone changes, your PIN must be reset (this is a security feature).
4. Atomic Creation OLIVE creates your subscriber record AND wallet account in a single database transaction. Either both succeed or both fail - you’ll never have a subscriber without a wallet.
5. Welcome Notification You receive a WhatsApp message confirming your registration.
Your subscriber ID follows this pattern: S-YY00000000
S- = Prefix indicating “Subscriber”YY = Last 2 digits of the year you registered (e.g., 25 for 2025)00000000 = Last 8 digits of your phone number
Example: If you registered in 2025 with phone +23277123456, your ID would be S-2577123456.Subscriber Status Your account can be in one of four states:
Active You can do everything - send, receive, pay, withdraw. This is the default status when you register.
Pending Your account is awaiting verification. Some features may be limited until verified.
Blocked Your account has been suspended. You cannot make any transactions. Money in your wallet is frozen but safe. When unblocked, full access returns.
When blocked:
You receive a WhatsApp notification
All transaction attempts are rejected
Compliance or admin must unblock you
Inactive Your account is dormant. Limited operations available.
Subscriber Categories Not all subscribers are the same. OLIVE has four categories with different rules:
Retail (Default) Regular individuals using OLIVE for personal payments.
Default maximum of 4 child cards
Standard KYC limits apply
No extra requirements
Corporate Registered businesses using OLIVE for operations.
Required: organisation_name and registration_id_noCan have up to 100 child cards (for employees)
May have organisation_type and certificate_url
Validation: If you select corporate, you must provide the business registration details or registration fails.VIP High-value individuals with personalized service.
Required: A relationship_manager_id (assigned admin user)Your relationship manager can be looked up by name
Same limits as retail but dedicated support
Validation: VIP subscribers must have an assigned relationship manager.PEP (Politically Exposed Person) Government officials, public figures, and those with elevated compliance risk.
Enhanced transaction monitoring
Staff need OTP verification to access your account
Extra audit logging on all access
Usually have a relationship manager too
KYC Levels Explained KYC (Know Your Customer) determines how much you can transact. It’s based on how much OLIVE knows about you.
Level 1 - Phone Only You’ve registered with just your phone number and name. Lowest limits.
Limit Amount Maximum Wallet Balance 500,000 SLE Maximum Per Transaction 50,000 SLE Daily Total Spending 200,000 SLE Monthly Total Spending 2,000,000 SLE
Level 2 - ID Verified You’ve uploaded your national ID and it’s been verified.
Limit Amount Maximum Wallet Balance 2,000,000 SLE Maximum Per Transaction 200,000 SLE Daily Total Spending 1,000,000 SLE Monthly Total Spending 10,000,000 SLE
Requirement: national_id must be provided.Level 3 - Fully Verified Complete verification with all documents.
Limit Amount Maximum Wallet Balance 10,000,000 SLE Maximum Per Transaction 1,000,000 SLE Daily Total Spending 5,000,000 SLE Monthly Total Spending 50,000,000 SLE
Requirement: national_id must be provided.The 4-Digit PIN Your PIN is the key to authorizing transactions.
PIN Rules
Exactly 4 digits (0-9)
Required for all payments and withdrawals
Hashed, never stored in plain text
How PIN Verification Works
You enter your PIN at a POS terminal or via agent
OLIVE computes: SHA256(entered_PIN + your_phone_number)
Result is compared to your stored PIN hash
If they match, transaction proceeds
Why Phone Number is the Salt Your PIN is cryptographically tied to your phone number. This means:
If your phone changes, your PIN becomes invalid
You must reset your PIN after a phone number change
This protects against attackers who might obtain your PIN hash
Changing Your PIN
You provide your current PIN
You provide your new PIN
OLIVE verifies the old PIN is correct
The new PIN must be different from the old one
New hash is computed and stored
You receive a WhatsApp security notification
Child Cards Subscribers can have multiple NFC cards sharing their wallet.
Default Limits
Retail/VIP/PEP: 4 child cardsCorporate: 100 child cards (for employees)
You can check max_child_cards to see your limit, and it can be customized by an admin.
Phone Number Handling OLIVE normalizes all Sierra Leone phone numbers to international format.
You Enter OLIVE Stores 077123456+23277123456+23277123456+2327712345623277123456+23277123456
This ensures consistency - you can use any format when logging in or receiving money.
Phone Validation Valid formats:
International E.164: +1 through +999... (up to 15 digits)
Local Sierra Leone: 0XXXXXXXX (9 digits starting with 0)
VULT Integration OLIVE can link to VULT, a partner cash-in network.
When linked:
Your vult_wallet_id stores the VULT account ID
You can deposit cash at VULT locations
VULT sends a webhook to credit your OLIVE wallet
What Gets Stored Here’s what OLIVE knows about you:
Field Required Description phone_numberYes Your Sierra Leone mobile number first_nameYes Your first name last_nameYes Your last name pin_hashYes Hashed PIN (never visible) other_namesNo Middle names national_idFor KYC 2+ Your national ID number id_front_urlNo Photo of ID front id_back_urlNo Photo of ID back emailNo Email address addressNo Physical address districtNo Sierra Leone district whatsapp_numberNo WhatsApp contact (for notifications) referral_codeNo How you heard about OLIVE
Corporate-Specific Fields Field Description organisation_nameCompany name organisation_typeType of business registration_id_noBusiness registration number certificate_urlRegistration certificate image
Notifications OLIVE sends WhatsApp messages for important events:
Event Message Registration Welcome message with your info Account Blocked Alert that your account is suspended Account Unblocked Confirmation your account is restored PIN Changed Security alert (not initiated by you? Contact support)
Balance Fetching When displaying subscribers (in dashboards), OLIVE fetches balances concurrently using a worker pool pattern. This means:
Multiple balance queries run in parallel
Large subscriber lists load quickly
Uses all available CPU cores
Wallets Where your balance lives
Cards NFC cards for payments
Compliance PEP and monitoring
