Skip to main content

​
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.
LimitAmount
Maximum Wallet Balance500,000 SLE
Maximum Per Transaction50,000 SLE
Daily Total Spending200,000 SLE
Monthly Total Spending2,000,000 SLE

​
Level 2 - ID Verified

You’ve uploaded your national ID and it’s been verified.
LimitAmount
Maximum Wallet Balance2,000,000 SLE
Maximum Per Transaction200,000 SLE
Daily Total Spending1,000,000 SLE
Monthly Total Spending10,000,000 SLE
Requirement: national_id must be provided.

​
Level 3 - Fully Verified

Complete verification with all documents.
LimitAmount
Maximum Wallet Balance10,000,000 SLE
Maximum Per Transaction1,000,000 SLE
Daily Total Spending5,000,000 SLE
Monthly Total Spending50,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 EnterOLIVE 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:
FieldRequiredDescription
phone_numberYesYour Sierra Leone mobile number
first_nameYesYour first name
last_nameYesYour last name
pin_hashYesHashed PIN (never visible)
other_namesNoMiddle names
national_idFor KYC 2+Your national ID number
id_front_urlNoPhoto of ID front
id_back_urlNoPhoto of ID back
emailNoEmail address
addressNoPhysical address
districtNoSierra Leone district
whatsapp_numberNoWhatsApp contact (for notifications)
referral_codeNoHow you heard about OLIVE

​
Corporate-Specific Fields

FieldDescription
organisation_nameCompany name
organisation_typeType of business
registration_id_noBusiness registration number
certificate_urlRegistration certificate image

​
Notifications

OLIVE sends WhatsApp messages for important events:
EventMessage
RegistrationWelcome message with your info
Account BlockedAlert that your account is suspended
Account UnblockedConfirmation your account is restored
PIN ChangedSecurity 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

Transactions

Moving money

Compliance

PEP and monitoring