API Specification

RESTful API endpoints organized by module — JAX-RS on WildFly 31 + Node.js data services

8
API Modules
2
Backend Servers
JWT
Authentication
RBAC
Authorization

WildFly Backend (:8080)

Base URL/temco-loan-system/api/v1
FrameworkJAX-RS (Jakarta EE)
AuthBearer JWT token
Content-Typeapplication/json
DocsMicroProfile OpenAPI 3.1

Node.js API (:8086)

Base URL/api
FrameworkExpress.js
AuthSession / JWT
DB Drivermysql2
PurposeData services, student lookup

Authentication & User Management

POST/api/v1/customer/auth/loginAuthenticate user, return JWT token
POST/api/v1/customer/auth/logoutInvalidate session token
POST/api/v1/customer/auth/refreshRefresh JWT token
POST/api/v1/customer/auth/forgot-passwordInitiate password reset (OTP via WhatsApp)
POST/api/v1/customer/auth/reset-passwordReset password with OTP verification
GET/api/v1/customer/auth/profileGet current user profile
PUT/api/v1/customer/auth/profileUpdate user profile
GET/api/v1/usersList all users (Admin)
POST/api/v1/usersCreate new user (Admin)
PUT/api/v1/users/{id}/unlockUnlock locked account (Admin)
GET/api/v1/rolesList all roles
GET/api/v1/permissionsList all permissions

Loan Management

GET/api/v1/loansList all loan products
GET/api/v1/loans/{id}Get loan product details
POST/api/v1/loan-applicationsSubmit new loan application
GET/api/v1/loan-applicationsList loan applications (filtered by role)
GET/api/v1/loan-applications/{id}Get application details with status history
PUT/api/v1/loan-applications/{id}/statusUpdate application status (approve/reject)
GET/api/v1/loan-applications/{id}/installmentsGet installment schedule
POST/api/v1/loan-applications/{id}/guarantorsAdd guarantor to application
GET/api/v1/loan-applications/{id}/paymentsGet payment history
POST/api/v1/loan-applications/{id}/paymentsRecord loan payment
GET/api/v1/interest-ratesList interest rates by loan type
POST/api/v1/emi-calculatorCalculate EMI for given parameters

Deposit Management

POST/api/v1/accountsOpen new account (savings/current)
GET/api/v1/accountsList member accounts
GET/api/v1/accounts/{id}/balanceGet account balance
GET/api/v1/accounts/{id}/statementGet account statement (date range)
POST/api/v1/fixed-depositsCreate fixed deposit
GET/api/v1/fixed-depositsList FDs for member
PUT/api/v1/fixed-deposits/{id}/renewRenew fixed deposit
POST/api/v1/fixed-deposits/{id}/withdrawPremature withdrawal
POST/api/v1/recurring-depositsCreate recurring deposit
GET/api/v1/fd-ratesGet FD interest rate slabs

Transaction Services

POST/api/v1/transfers/internalInternal fund transfer
POST/api/v1/transfers/ceftCEFT interbank transfer
POST/api/v1/transfers/slipsSLIPS batch transfer
GET/api/v1/transfersList transfer history
POST/api/v1/standing-ordersCreate standing order
GET/api/v1/standing-ordersList standing orders
DEL/api/v1/standing-orders/{id}Cancel standing order
POST/api/v1/bill-paymentsPay bill
GET/api/v1/billersList available billers
POST/api/v1/cheques/issueIssue cheque book
POST/api/v1/cheques/stopStop cheque request
POST/api/v1/demand-draftsIssue demand draft

Payment Gateway

POST/api/v1/merchantsRegister merchant
POST/api/v1/merchants/{id}/api-keysGenerate API key
POST/api/v1/payments/initiateInitiate payment
GET/api/v1/payments/{id}/statusCheck payment status
POST/api/v1/payments/{id}/refundProcess refund
POST/api/v1/qr/generateGenerate QR code for merchant
POST/api/v1/qr/payProcess QR payment

Joint Venture

POST/api/v1/joint-venturesCreate JV account
GET/api/v1/joint-venturesList JV accounts
GET/api/v1/joint-ventures/{id}Get JV details with partners
POST/api/v1/joint-ventures/{id}/partnersAdd partner to JV
POST/api/v1/joint-ventures/{id}/distributeDistribute P&L to partners
GET/api/v1/joint-ventures/{id}/pnlGet P&L statement
POST/api/v1/escrowCreate escrow account
POST/api/v1/escrow/{id}/releaseRelease escrow funds

Investment Services

POST/api/v1/investments/accountsCreate investment account
POST/api/v1/investments/stocks/buyBuy stock
POST/api/v1/investments/stocks/sellSell stock
GET/api/v1/investments/portfolioGet portfolio holdings
GET/api/v1/investments/portfolio/valuationMark-to-market valuation
GET/api/v1/securitiesList available securities
POST/api/v1/investments/bonds/buyBuy government/corporate bond
POST/api/v1/investments/unit-trusts/subscribeSubscribe to unit trust
POST/api/v1/investments/unit-trusts/redeemRedeem unit trust units
GET/api/v1/investments/money-marketList money market instruments

Finance & Accounting

GET/api/v1/chart-of-accountsList chart of accounts
POST/api/v1/journal-entriesCreate journal entry
GET/api/v1/journal-entriesList journal entries
POST/api/v1/vouchersCreate voucher
GET/api/v1/vouchersList vouchers
PUT/api/v1/vouchers/{id}/approveApprove voucher
GET/api/v1/reconciliationBank reconciliation
GET/api/v1/reports/balance-sheetGenerate balance sheet (JasperReports)
GET/api/v1/reports/income-statementGenerate income statement
GET/api/v1/reports/trial-balanceGenerate trial balance

Node.js Data Services (:8086)

POST/api/v1/auth/loginNode.js auth (BCrypt + PBE)
GET/api/customersList customers from GUP
GET/api/student-lookup?nic={nic}Lookup student by NIC
GET/api/students?page={n}&search={q}Paginated student list with search

Authentication Response Format

// POST /api/v1/customer/auth/login
// Request:
{
    "username": "[email protected]",
    "password": "••••••••"
}

// Response (200 OK):
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
        "id": 1,
        "username": "[email protected]",
        "email": "[email protected]",
        "fullName": "Ishantha Siribaddana",
        "nic": "199012345678",
        "roleId": 1,
        "roleName": "Super Admin"
    },
    "expiresAt": "2026-02-13T22:00:00.000Z"
}

// Error Response (401):
{
    "success": false,
    "message": "Invalid credentials",
    "remainingAttempts": 3
}

// Error Response (423 Locked):
{
    "success": false,
    "message": "Account locked. Contact administrator.",
    "lockedAt": "2026-02-12T21:00:00.000Z"
}