Skip to main content
Subscribers are the end-users of the OLIVE platform. Each subscriber has a wallet, can link NFC cards, and perform transactions.

​
Quick Start

1

Register Subscriber

Create account with phone number and PIN
2

Link Card

Associate NFC card for payments
3

Upgrade KYC

Submit documents for higher limits
4

Transact

P2P transfers, POS payments, cash-in/out

​
Endpoints

Register

POST /api/v1/subscribersCreate new subscriber account

Get Subscriber

GET /api/v1/subscribers/{id}Retrieve subscriber by ID

Lookup

GET /api/v1/subscribers/lookupFind subscriber by phone number

List

GET /api/v1/subscribersList all subscribers with filters

Update

PUT /api/v1/subscribers/{id}Update profile and KYC info

Block

POST /api/v1/subscribers/{id}/blockBlock subscriber account

Unblock

POST /api/v1/subscribers/{id}/unblockRestore blocked account

Verify PIN

POST /api/v1/subscribers/{id}/verify-pinVerify subscriber’s PIN

Change PIN

POST /api/v1/subscribers/{id}/change-pinChange subscriber’s PIN

Cards

GET /api/v1/subscribers/{id}/cardsList 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

LevelMax BalanceDaily LimitMonthly LimitRequirements
1500,000 SLE100,000 SLE1,000,000 SLEPhone + PIN
22,000,000 SLE500,000 SLE5,000,000 SLE+ ID Document
310,000,000 SLE2,000,000 SLE20,000,000 SLE+ Address Proof
KYC upgrades require document verification and may take 1-2 business days.

​
Common Workflows

  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
  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
  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
  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

Cards

Link and manage NFC cards

Wallet

Balance and transactions