Subscribers
A subscriber is anyone who uses SmartPay to store and move money. When you register, you become a subscriber with your own wallet, identity, and access to the SmartPay financial network.
What is a Subscriber?
Think of a subscriber as an SmartPay 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 SmartPay - payments, transfers, cash-in, cash-out - involves subscribers on one or both ends.
How Registration Works
When someone registers on SmartPay (via WhatsApp, agent, or dashboard), here's what happens:
1. Phone Number Check
First, SmartPay 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, SmartPay 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
SmartPay 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.,25for 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. SmartPay has four categories with different rules:
Retail (Default)
Regular individuals using SmartPay for personal payments.
- Default maximum of 4 child cards
- Standard KYC limits apply
- No extra requirements
Corporate
Registered businesses using SmartPay for operations.
- Required:
organisation_nameandregistration_id_no - Can have up to 100 child cards (for employees)
- May have
organisation_typeandcertificate_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 SmartPay 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
- SmartPay 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
- SmartPay 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 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
SmartPay normalizes all Sierra Leone phone numbers to international format.
| You Enter | SmartPay 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:
+1through+999...(up to 15 digits) - Local Sierra Leone:
0XXXXXXXX(9 digits starting with 0)
VULT Integration
SmartPay can link to VULT, a partner cash-in network.
When linked:
- Your
vult_wallet_idstores the VULT account ID - You can deposit cash at VULT locations
- VULT sends a webhook to credit your SmartPay wallet
What Gets Stored
Here's what SmartPay 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 SmartPay |
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
SmartPay 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), SmartPay 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