KYC Upgrade

Complete guide for upgrading user KYC (Know Your Customer) levels to unlock higher transaction limits.

Overview

SmartPay uses a tiered KYC system that balances ease of use with regulatory compliance. Higher KYC levels unlock greater transaction limits.

---

KYC Levels

Level	Requirements	Daily Limit	Monthly Limit
Basic	Phone + Name	100,000 SLE	500,000 SLE
Enhanced	ID Front + Back	500,000 SLE	2,500,000 SLE
Full	Verified ID + Address	2,000,000 SLE	10,000,000 SLE

Info

All new users start at Basic level after phone verification.

---

Upgrade Methods

Users can upgrade via the WhatsApp conversational agent

---

WhatsApp Upgrade Flow

The most common upgrade path uses the WhatsApp agent:

Initiate Upgrade

User messages: "upgrade my account" or "I want higher limits"

Agent Explains

Agent explains requirements and asks for ID front photo

Upload ID Front

User sends photo of ID card (front)

Upload ID Back

Agent asks for ID back photo, user sends

Validation

System validates both images using OCR and AI

Result

If valid, account upgraded. If issues found, user notified.

Example Conversation

User: upgrade my account
Agent: I can help you upgrade your account! This will increase your 
       transaction limits. Please send a clear photo of the FRONT 
       of your Sierra Leone National ID card.

User: [sends ID front photo]
Agent: Great! Now please send the BACK of your ID card.

User: [sends ID back photo]  
Agent: Your documents have been verified. Your account has been 
       upgraded to Enhanced level. Your new daily limit is 500,000 SLE.

---

ID Requirements

Accepted Documents

Document	Requirements
Sierra Leone National ID	Front and back photos
Passport	Photo page
Driver's License	Front and back photos

Photo Requirements

Do

• Clear, well-lit photo
• All text readable
• Full document visible
• Flat surface

Don't

• Blurry or dark images
• Glare covering text
• Cropped or partial
• Tampered documents

---

Validation Process

Multi-Layer Verification

The system uses multiple validation layers:

1. OpenAI Vision

• Validates document authenticity
• Checks for photo presence
• Verifies official document look
• Detects obvious tampering

2. OCR Extraction

• Extracts text using Tesseract
• Parses ID number, name, dates
• Calculates confidence scores
• Detects low-quality images

3. Cross-Validation

• Compares front and back data
• Verifies name consistency
• Checks dates match
• Flags mismatches

Extracted Fields

For Sierra Leone National ID:

Field	Source	Example
NIN (ID Number)	Front	SL-NIN-12345678
Full Name	Front	John Doe Smith
Date of Birth	Front	1990-05-15
Gender	Front	Male
Date of Expiry	Back	2028-03-20

---

Fraud Detection

The system automatically detects:

Warning

Fraudulent documents are flagged and may result in account suspension.

Indicator	Detection Method
Tampered text	OCR confidence analysis
Missing headers	Pattern matching for official text
Suspicious patterns	Keywords like "sample", "test", "photoshop"
Repeating ID numbers	Pattern detection (e.g., 11111111)
Front/back mismatch	Cross-validation of names/numbers
Low image quality	Confidence score thresholds

Fraud Response Example

{
  "valid": false,
  "fraudDetected": true,
  "fraudIndicators": [
    "OCR confidence below threshold (45%)",
    "Missing official header text",
    "ID number contains repeating pattern"
  ]
}

---

API Integration

For third-party integrations that need to submit KYC documents:

Upload Single Image

curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/:id/kyc/upload" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_type": "id_front",
    "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'

Complete KYC Upgrade

curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/:id/kyc/upgrade" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target_level": "enhanced",
    "id_front": "data:image/jpeg;base64,/9j/...",
    "id_back": "data:image/jpeg;base64,/9j/..."
  }'

Response

{
  "success": true,
  "previous_level": "basic",
  "new_level": "enhanced",
  "subscriber_id": "sub_abc123",
  "validation": {
    "front": { "valid": true, "confidence": 0.95 },
    "back": { "valid": true, "confidence": 0.92 },
    "crossValidation": { "consistent": true }
  }
}

---

Troubleshooting

"Image validation failed"

Cause	Solution
Blurry image	Ask user to retake in good lighting
Glare on card	Tilt card to avoid reflections
Partial image	Ensure entire document is visible
Wrong format	Convert to JPEG or PNG

"Documents don't match"

• Front and back should be same document
• Names should match exactly
• Dates should be consistent

"OCR confidence too low"

• Image may be too dark or have shadows
• Text may be obscured or damaged
• Ask for better quality photo

---

Related

KYC Validation Technical

Technical OCR and validation details

Compliance API

Compliance monitoring endpoints