Subscribers

Info

Subscribers are the end-users of the SmartPay platform. Each subscriber has a wallet, can link NFC cards, and perform transactions.

Quick Start

Register Subscriber

Create account with phone number and PIN

Link Card

Associate NFC card for payments

Upgrade KYC

Submit documents for higher limits

Transact

P2P transfers, POS payments, cash-in/out

---

Endpoints

Register

POST /api/v1/subscribers

Create new subscriber account

Get Subscriber

GET /api/v1/subscribers/{id}

Retrieve subscriber by ID

Lookup

GET /api/v1/subscribers/lookup

Find subscriber by phone number

List

GET /api/v1/subscribers

List all subscribers with filters

Update

PUT /api/v1/subscribers/{id}

Update profile and KYC info

Block

POST /api/v1/subscribers/{id}/block

Block subscriber account

Unblock

POST /api/v1/subscribers/{id}/unblock

Restore blocked account

Verify PIN

POST /api/v1/subscribers/{id}/verify-pin

Verify subscriber's PIN

Change PIN

POST /api/v1/subscribers/{id}/change-pin

Change subscriber's PIN

Cards

GET /api/v1/subscribers/{id}/cards

List linked NFC cards

---

Subscriber Object

{
  "id": "sub_abc123",
  "phone_number": "+23279123456",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "date_of_birth": "1990-05-15",
  "address": "123 Main Street, Freetown",
  "kyc_level": 2,
  "status": "ACTIVE",
  "balance": "125,000.00 SLE",
  "id_number": "SL12345678",
  "id_type": "NATIONAL_ID",
  "vult_wallet_id": "vult_xyz789",
  "cards_count": 2,
  "max_child_cards": 4,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:45:00Z"
}

---

Account Status

Active

Full access to all features

Pending

Awaiting KYC verification

Blocked

Account suspended, no transactions

---

KYC Levels

Level	Max Balance	Daily Limit	Monthly Limit	Requirements
1	500,000 SLE	100,000 SLE	1,000,000 SLE	Phone + PIN
2	2,000,000 SLE	500,000 SLE	5,000,000 SLE	+ ID Document
3	10,000,000 SLE	2,000,000 SLE	20,000,000 SLE	+ Address Proof

Info

KYC upgrades require document verification and may take 1-2 business days.

---

Common Workflows

Register New Subscriber

1. Call POST /api/v1/subscribers with phone, name, and PIN
2. Subscriber receives WhatsApp welcome message
3. Link an NFC card via POST /api/v1/cards/link
4. Subscriber can now receive funds and make payments

Upgrade KYC Level

1. Collect ID document and selfie from subscriber
2. Upload documents to storage
3. Call PUT /api/v1/subscribers/{id} with document URLs and KYC level
4. System verifies documents (OCR + face match)
5. If approved, limits are automatically increased

Handle Blocked Account

1. Check block reason in subscriber details
2. Investigate any associated compliance alerts
3. If resolved, call POST /api/v1/subscribers/{id}/unblock
4. All cards are automatically reactivated

Password Reset (PIN Change)

1. Verify subscriber identity through support channel
2. Admin calls POST /api/v1/subscribers/{id}/change-pin
3. Subscriber receives new PIN via WhatsApp
4. Subscriber should change PIN on first use

---

Related

Cards

Link and manage NFC cards

Wallet

Balance and transactions