API Reference - OLIVE Payment Platform

Base URL: https://demo.api.vultlocal.com (Demo) | http://localhost:8080 (Development)

Quick Access

Subscribers

User accounts, KYC, and profile management

Cards

NFC card linking, blocking, and management

Wallet

Balances, transfers, and transactions

Agents

Agent network and cash-in operations

POS

Point-of-sale terminal integrations

Admin

Authentication and user management

Authentication

API Key
JWT Token
HMAC Signature

Authorization: Bearer olive_live_xxxxxxxxxxxxx

Best for: Server-to-server integrations, POS terminals

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Best for: Dashboard users, session-based access

X-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Partner-ID: VULT

Best for: Partner integrations (VULT, external systems)

Authentication Guide

Learn about authentication methods, token refresh, and security best practices

API Categories

Subscribers

Manage subscriber accounts, KYC levels, and profile information.

Endpoint	Description
`POST /api/v1/subscribers`	Register new subscriber
`GET /api/v1/subscribers/:id`	Get subscriber details
`GET /api/v1/subscribers`	List all subscribers
`PUT /api/v1/subscribers/:id`	Update subscriber
`POST /api/v1/subscribers/:id/block`	Block subscriber
`POST /api/v1/subscribers/:id/unblock`	Unblock subscriber
`POST /api/v1/subscribers/:id/verify-pin`	Verify PIN
`POST /api/v1/subscribers/:id/change-pin`	Change PIN

Cards

NFC card management, linking, and child cards.

Endpoint	Description
`POST /api/v1/cards/link`	Link card to subscriber
`POST /api/v1/cards/child`	Create child card
`GET /api/v1/cards/:serial`	Get card details
`GET /api/v1/cards`	List all cards
`POST /api/v1/cards/:serial/block`	Block card
`POST /api/v1/cards/:serial/unblock`	Unblock card
`POST /api/v1/cards/upload-csv`	Bulk upload cards

Wallet

Financial operations, transfers, and transaction history.

Endpoint	Description
`GET /api/v1/balance/:user_id`	Get wallet balance
`GET /api/v1/transactions`	Transaction history
`POST /api/v1/wallet/transfer`	Internal transfer
`POST /api/v1/wallet/transfer-p2p`	P2P by card serial
`POST /api/v1/wallet/fund-from-vult`	Fund from VULT
`POST /api/v1/wallet/account-statement`	Generate statement

Agents

Agent network management and cash-in operations.

Endpoint	Description
`POST /api/v1/agents`	Register agent
`GET /api/v1/agents/:id`	Get agent details
`GET /api/v1/agents`	List agents
`POST /api/v1/agents/:id/fund`	Fund agent float
`POST /api/v1/agents/cashin`	Agent cash-in
`POST /api/v1/agents/transfer`	Transfer to sub-agent
`GET /api/v1/agents/:id/balance`	Get agent balance

POS

Point-of-sale terminal operations.

Endpoint	Description
`POST /pos/payment`	Process payment
`POST /pos/verify-card`	Verify card before payment
`POST /pos/refund`	Refund transaction
`POST /pos/lookup-card`	Look up card info

Processors

Payment processor (merchant) management.

Endpoint	Description
`POST /api/v1/processors`	Create processor
`GET /api/v1/processors/:id`	Get processor
`GET /api/v1/processors`	List processors
`POST /api/v1/processors/:id/suspend`	Suspend processor
`POST /api/v1/processors/:id/transfer`	Processor transfer
`GET /api/v1/processors/:id/transactions`	Processor history

Compliance

Fraud detection and compliance monitoring.

Endpoint	Description
`POST /api/v1/compliance/check`	Run compliance check
`GET /api/v1/compliance/alerts`	List alerts
`POST /api/v1/compliance/alerts`	Create alert
`POST /api/v1/compliance/alerts/:id/resolve`	Resolve alert
`GET /api/v1/compliance/rules`	List monitoring rules
`GET /api/v1/account-rules/:kyc_level`	Get KYC limits

Admin

System administration and user management.

Endpoint	Description
`POST /api/v1/admin/login`	User login
`POST /api/v1/admin/refresh`	Refresh token
`POST /api/v1/admin/logout`	Logout
`GET /api/v1/admin/me`	Current user
`POST /api/v1/admin/users`	Create user
`POST /api/v1/admin/api-keys`	Create API key
`GET /api/v1/audit/logs`	Audit logs

Request & Response

Request Format
Success Response
Error Response

curl -X POST https://demo.api.vultlocal.com/api/v1/wallet/transfer-p2p \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: unique-id-123" \
  -d '{
    "sender_id": "sub_abc123",
    "recipient_card_serial": "OLIV0002",
    "amount": "5000",
    "pin": "1234"
  }'

{
  "success": true,
  "message": "Transfer successful",
  "transaction_id": "txn_xyz789",
  "sender_new_balance": "45,000.00 SLE",
  "fee_amount": "50.00 SLE"
}

{
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_FUNDS",
  "details": {
    "available": 3000,
    "required": 5050
  }
}

HTTP Status Codes

Success Codes

200 OK - Request succeeded
201 Created - Resource created
204 No Content - Deleted successfully

Client Errors

400 Bad Request - Invalid input
401 Unauthorized - Auth required
403 Forbidden - No permission
404 Not Found - Resource missing
429 Rate Limited - Too many requests

Rate Limiting

Default limit: 100 requests/second per API key. Contact support for higher limits.

Rate limit headers in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Explore APIs

Postman Collection

Import our Postman collection for quick testing

OpenAPI Spec

Download the OpenAPI 3.0 specification

Authentication

​Quick Access

Subscribers

Cards

Wallet

Agents

POS

Admin

​Authentication

Authentication Guide

​API Categories

​Request & Response

​HTTP Status Codes

Success Codes

Client Errors

​Rate Limiting

​Explore APIs

Postman Collection

OpenAPI Spec

Quick Access

Authentication

API Categories

Request & Response

HTTP Status Codes

Rate Limiting

Explore APIs