Skip to main content

API Reference

Info

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​

Authorization: Bearer olive_live_xxxxxxxxxxxxx

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

Authentication Guide

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

API Categories​

Subscribers

Manage subscriber accounts, KYC levels, and profile information.

EndpointDescription
POST /api/v1/subscribersRegister new subscriber
GET /api/v1/subscribers/:idGet subscriber details
GET /api/v1/subscribersList all subscribers
PUT /api/v1/subscribers/:idUpdate subscriber
POST /api/v1/subscribers/:id/blockBlock subscriber
POST /api/v1/subscribers/:id/unblockUnblock subscriber
POST /api/v1/subscribers/:id/verify-pinVerify PIN
POST /api/v1/subscribers/:id/change-pinChange PIN
Cards

NFC card management, linking, and child cards.

EndpointDescription
POST /api/v1/cards/linkLink card to subscriber
POST /api/v1/cards/childCreate child card
GET /api/v1/cards/:serialGet card details
GET /api/v1/cardsList all cards
POST /api/v1/cards/:serial/blockBlock card
POST /api/v1/cards/:serial/unblockUnblock card
POST /api/v1/cards/upload-csvBulk upload cards
Wallet

Financial operations, transfers, and transaction history.

EndpointDescription
GET /api/v1/balance/:user_idGet wallet balance
GET /api/v1/transactionsTransaction history
POST /api/v1/wallet/transferInternal transfer
POST /api/v1/wallet/transfer-p2pP2P by card serial
POST /api/v1/wallet/fund-from-vultFund from VULT
POST /api/v1/wallet/account-statementGenerate statement
Agents

Agent network management and cash-in operations.

EndpointDescription
POST /api/v1/agentsRegister agent
GET /api/v1/agents/:idGet agent details
GET /api/v1/agentsList agents
POST /api/v1/agents/:id/fundFund agent float
POST /api/v1/agents/cashinAgent cash-in
POST /api/v1/agents/transferTransfer to sub-agent
GET /api/v1/agents/:id/balanceGet agent balance
POS

Point-of-sale terminal operations.

EndpointDescription
POST /pos/paymentProcess payment
POST /pos/verify-cardVerify card before payment
POST /pos/refundRefund transaction
POST /pos/lookup-cardLook up card info
Processors

Payment processor (merchant) management.

EndpointDescription
POST /api/v1/processorsCreate processor
GET /api/v1/processors/:idGet processor
GET /api/v1/processorsList processors
POST /api/v1/processors/:id/suspendSuspend processor
POST /api/v1/processors/:id/transferProcessor transfer
GET /api/v1/processors/:id/transactionsProcessor history
Compliance

Fraud detection and compliance monitoring.

EndpointDescription
POST /api/v1/compliance/checkRun compliance check
GET /api/v1/compliance/alertsList alerts
POST /api/v1/compliance/alertsCreate alert
POST /api/v1/compliance/alerts/:id/resolveResolve alert
GET /api/v1/compliance/rulesList monitoring rules
GET /api/v1/account-rules/:kyc_levelGet KYC limits
Admin

System administration and user management.

EndpointDescription
POST /api/v1/admin/loginUser login
POST /api/v1/admin/refreshRefresh token
POST /api/v1/admin/logoutLogout
GET /api/v1/admin/meCurrent user
POST /api/v1/admin/usersCreate user
POST /api/v1/admin/api-keysCreate API key
GET /api/v1/audit/logsAudit logs

Request & 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"
  }'

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​

Warning

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