Subscribers - OLIVE Payment Platform

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

Quick Start

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

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

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

Common Workflows

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

Upgrade KYC Level

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

Handle Blocked Account

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

Password Reset (PIN Change)

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

Cards

Link and manage NFC cards

Wallet

Balance and transactions

Agent-TS Tools

​Quick Start

​Endpoints

Register

Get Subscriber

Lookup

List

Update

Block

Unblock

Verify PIN

Change PIN

Cards

​Subscriber Object

​Account Status

Active

Pending

Blocked

​KYC Levels

​Common Workflows

​Related

Cards

Wallet

Quick Start

Endpoints

Subscriber Object

Account Status

KYC Levels

Common Workflows

Related