> ## 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 > Understanding OLIVE subscriber accounts # 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 system * **A wallet** - Where your money lives * **A 4-digit PIN** - To authorize transactions * **Access 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. *** ## Subscriber ID Format 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_no` * Can 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 1. You enter your PIN at a POS terminal or via agent 2. OLIVE computes: `SHA256(entered_PIN + your_phone_number)` 3. Result is compared to your stored PIN hash 4. 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 1. You provide your current PIN 2. You provide your new PIN 3. OLIVE verifies the old PIN is correct 4. The new PIN must be different from the old one 5. New hash is computed and stored 6. You receive a WhatsApp security notification *** ## Child Cards Subscribers can have multiple NFC cards sharing their wallet. ### Default Limits * **Retail/VIP/PEP:** 4 child cards * **Corporate:** 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` | `+23277123456` | | `23277123456` | `+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_number` | Yes | Your Sierra Leone mobile number | | `first_name` | Yes | Your first name | | `last_name` | Yes | Your last name | | `pin_hash` | Yes | Hashed PIN (never visible) | | `other_names` | No | Middle names | | `national_id` | For KYC 2+ | Your national ID number | | `id_front_url` | No | Photo of ID front | | `id_back_url` | No | Photo of ID back | | `email` | No | Email address | | `address` | No | Physical address | | `district` | No | Sierra Leone district | | `whatsapp_number` | No | WhatsApp contact (for notifications) | | `referral_code` | No | How you heard about OLIVE | ### Corporate-Specific Fields | Field | Description | | -------------------- | ------------------------------ | | `organisation_name` | Company name | | `organisation_type` | Type of business | | `registration_id_no` | Business registration number | | `certificate_url` | Registration 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 *** ## Related Concepts Where your balance lives NFC cards for payments Moving money PEP and monitoring