📡RISWIS API Reference

Overview

The RISWIS API provides programmatic access to banking operations, user management, and system administration. All endpoints require authentication and follow RESTful principles.

🔐 Authentication

JWT Token Authentication

All API requests must include a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Getting a Token

POST /api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-id",
    "username": "username",
    "role": "TELLER",
    "permissions": ["READ_TRANSACTION", "CREATE_TRANSACTION"]
  }
}

🏦 Core Banking APIs

Transactions

Create Transaction

POST /api/transactions
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "type": "DEPOSIT",
  "accountId": "account-uuid",
  "amount": 1000.00,
  "currency": "USD",
  "description": "Cash deposit",
  "customerId": "customer-uuid"
}

Response:

{
  "success": true,
  "data": {
    "id": "transaction-uuid",
    "type": "DEPOSIT",
    "amount": 1000.00,
    "currency": "USD",
    "balance": 5000.00,
    "createdAt": "2025-01-15T10:30:00Z",
    "reference": "TXN-2025-001234"
  }
}

Error Response:

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Account balance insufficient for transaction"
}

Get Transaction History

GET /api/transactions?accountId=<account-id>&page=1&limit=50
Authorization: Bearer <token>

Query Parameters:

Parameter
Type
Required
Description

accountId

string

Yes

Account UUID

page

number

No

Page number (default: 1)

limit

number

No

Items per page (default: 50, max: 100)

startDate

string

No

Start date (ISO format)

endDate

string

No

End date (ISO format)

type

string

No

Transaction type filter

currency

string

No

Currency filter (USD/LRD)

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn-1",
        "type": "DEPOSIT",
        "amount": 1000.00,
        "currency": "USD",
        "description": "Cash deposit",
        "createdAt": "2025-01-15T10:30:00Z",
        "processedBy": "teller-name"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 125,
      "totalPages": 3
    }
  }
}

Money Transfers

Create Money Transfer

POST /api/money-transfers
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "senderAccountId": "sender-account-uuid",
  "recipientAccountId": "recipient-account-uuid",
  "amount": 500.00,
  "currency": "USD",
  "purpose": "Family support",
  "description": "Monthly transfer"
}

Response:

{
  "success": true,
  "data": {
    "transferId": "transfer-uuid",
    "reference": "TRF-2025-001234",
    "status": "COMPLETED",
    "senderTransaction": "txn-uuid-1",
    "recipientTransaction": "txn-uuid-2",
    "fee": 5.00,
    "exchangeRate": 1.0,
    "completedAt": "2025-01-15T10:35:00Z"
  }
}

👤 Customer Management

Get Customer Details

GET /api/customers/<customer-id>
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "id": "customer-uuid",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+231-77-123-4567",
    "accountNumber": "ACC-2025-001234",
    "accounts": [
      {
        "id": "account-uuid",
        "accountNumber": "ACC-2025-001234",
        "type": "SAVINGS",
        "status": "ACTIVE",
        "balanceUSD": 5000.00,
        "balanceLRD": 800000.00
      }
    ],
    "kyc": {
      "status": "VERIFIED",
      "verifiedAt": "2025-01-01T00:00:00Z"
    }
  }
}

Update Customer Information

PUT /api/customers/<customer-id>
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "email": "newemail@example.com",
  "phone": "+231-77-987-6543",
  "address": {
    "street": "123 Main St",
    "city": "Monrovia",
    "country": "Liberia"
  }
}

💰 Cash Management

Get Teller Cash Balance

GET /api/teller-cash/balance
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "tellerId": "teller-uuid",
    "sessionId": "session-uuid",
    "balances": {
      "USD": {
        "opening": 10000.00,
        "current": 8500.00,
        "transactions": -1500.00
      },
      "LRD": {
        "opening": 1600000.00,
        "current": 1450000.00,
        "transactions": -150000.00
      }
    },
    "lastUpdated": "2025-01-15T15:30:00Z"
  }
}

Update Cash Balance

POST /api/teller-cash/update
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "currency": "USD",
  "amount": -100.00,
  "type": "WITHDRAWAL",
  "description": "Customer withdrawal"
}

📊 Reports

Generate Transaction Report

POST /api/reports/transactions
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "startDate": "2025-01-01",
  "endDate": "2025-01-15",
  "currency": "USD",
  "format": "PDF",
  "filters": {
    "branchId": "branch-uuid",
    "tellerId": "teller-uuid",
    "transactionType": "DEPOSIT"
  }
}

Response:

{
  "success": true,
  "data": {
    "reportId": "report-uuid",
    "downloadUrl": "/api/reports/download/report-uuid",
    "generatedAt": "2025-01-15T16:00:00Z",
    "expiresAt": "2025-01-16T16:00:00Z"
  }
}

🔒 User Management

Create User

POST /api/users
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "username": "newuser",
  "email": "newuser@bank.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "TELLER",
  "departmentId": "dept-uuid",
  "branchId": "branch-uuid",
  "permissions": ["READ_TRANSACTION", "CREATE_TRANSACTION"]
}

📱 SMS Integration

Send SMS Notification

POST /api/sms/send
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "recipient": "+231-77-123-4567",
  "message": "Your transaction of $100.00 has been processed successfully.",
  "type": "TRANSACTION_CONFIRMATION",
  "customerId": "customer-uuid"
}

Get SMS Analytics

GET /api/sms-analytics/summary?startDate=2025-01-01&endDate=2025-01-15
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "totalSent": 1250,
    "delivered": 1180,
    "failed": 70,
    "deliveryRate": 94.4,
    "totalCost": 62.50,
    "breakdown": {
      "TRANSACTION_CONFIRMATION": 800,
      "ACCOUNT_ALERT": 300,
      "MARKETING": 150
    }
  }
}

🛡️ Approvals

Get Pending Approvals

GET /api/approvals/pending
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "approvals": [
      {
        "id": "approval-uuid",
        "type": "LARGE_TRANSACTION",
        "status": "PENDING",
        "requestedBy": "teller-name",
        "requestedAt": "2025-01-15T14:30:00Z",
        "details": {
          "transactionId": "txn-uuid",
          "amount": 15000.00,
          "currency": "USD",
          "reason": "Large cash withdrawal"
        }
      }
    ]
  }
}

Approve/Reject Request

POST /api/approvals/<approval-id>/decision
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "decision": "APPROVED",
  "comments": "Verified customer identity and documentation"
}

🚨 Error Codes

Code
Description
HTTP Status

UNAUTHORIZED

Invalid or missing authentication token

401

FORBIDDEN

Insufficient permissions for operation

403

ACCOUNT_NOT_FOUND

Account does not exist

404

INSUFFICIENT_BALANCE

Account balance too low

400

ACCOUNT_INACTIVE

Account is not active

400

TRANSACTION_LIMIT_EXCEEDED

Transaction exceeds daily limit

400

INVALID_CURRENCY

Unsupported currency specified

400

SYSTEM_ERROR

Internal server error

500

📋 Rate Limits

Endpoint Type
Rate Limit
Window

Authentication

5 requests

1 minute

Transactions

100 requests

1 minute

Reports

10 requests

1 minute

SMS

50 requests

1 minute

General

1000 requests

1 hour

🔧 Development Environment

Base URLs

  • Development: http://localhost:3001/api

  • Staging: https://staging-api.riswis.com/api

  • Production: https://api.riswis.com/api

Testing

# Example using curl
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"teller1","password":"Teller@123"}'

Postman Collection

Download the complete Postman collection: RISWIS API Collection

📞 Support

For API support:

  • Documentation Issues: Update this documentation

  • Bug Reports: Create GitHub issue

  • Feature Requests: Contact development team

Last updated: January 2025

PrevioustechnicalNextuser-guides

Last updated