Software Requirements Specification
Wallet Module
WALLET
1. Introduction
1.1 Purpose
This document defines the software requirements for the Wallet module of the HR Management System. The Wallet module provides electronic wallet functionality for managing payments, deposits, withdrawals, and financial transactions within the recruitment platform.
1.2 Scope
The Wallet module manages electronic wallet operations including:
- Wallet Management: Create wallets, view balances, set PINs
- Deposits: Add funds via bank transfer, credit card, or e-wallet
- Withdrawals: Request and process fund withdrawals to bank accounts
- Payments: Pay for job postings, featured listings, and premium services
- Transfers: Transfer funds between user wallets
- Transactions: Complete transaction history and audit trail
1.3 Module Dependencies
| Module | Dependency Type | Description |
|---|
| AUTH | Hard | User authentication and JWT token validation |
| RECR | Soft | Job posting payments and recruitment services |
| LOG | Soft | Event logging for financial audit trail |
1.4 Definitions
| Term | Definition |
|---|
| SRS | Software Requirements Specification |
| FR | Functional Requirement |
| NFR | Non-Functional Requirement |
| UC | Use Case |
| DR | Data Requirement |
| IR | Integration Requirement |
| PG | Payment Gateway |
1.5 User Roles
| Role | Description | Key Permissions |
|---|
| User | All registered users (Candidate, HR, Employer) | View balance, deposit, withdraw, make payments, view transactions |
| Admin | System administrators | Approve withdrawals, freeze wallets, view all wallets, process payouts |
| Payment Gateway | External payment processors | Process payments, send webhooks, verify transactions |
2. Module Overview
2.1 Module Description
| Aspect | Value |
|---|
| Module Code | WALLET |
| Module Name | Electronic Wallet |
| Description | Electronic wallet for payments, deposits, withdrawals, and financial transactions |
| Database | wallet_db |
| Tables | wallet_wallets, wallet_transactions, wallet_payment_methods, wallet_payment_orders, wallet_payout_requests |
| Tech Stack | NestJS, Drizzle ORM, PostgreSQL, RabbitMQ |
2.2 Use Case Diagram
Figure 1: Wallet Use Case Diagram
3. Detailed Use Case Specifications
3.1 UC-01: View Wallet Balance
| Field | Description |
|---|
| Use Case ID | UC-01 |
| Name | View Wallet Balance |
| Actor | User (all roles) |
| Precondition | User is logged in |
| Postcondition | User views wallet balance and status |
| Trigger | User accesses wallet page |
Main Flow:
- User navigates to wallet page
- System validates JWT token
- System retrieves user_id from token
- System queries wallet_wallets table
- System returns wallet data (balance, currency, status)
- User views wallet balance
Alternative Flows:
- 3a. Invalid token: System returns 401 Unauthorized
- 4a. No wallet found: System returns 404, user sees empty state
Figure 2: UC-01 View Wallet Balance - Activity Diagram
Figure 3: UC-01 View Wallet Balance - Sequence Diagram
3.2 UC-02: Deposit Funds
| Field | Description |
|---|
| Use Case ID | UC-02 |
| Name | Deposit Funds |
| Actor | User |
| Precondition | User is logged in, wallet exists |
| Postcondition | Funds added to wallet balance |
| Trigger | User clicks "Deposit" button |
Main Flow:
- User selects deposit method (bank transfer, credit card, e-wallet)
- User enters deposit amount
- System validates amount (min/max limits)
- System creates wallet_transactions record (status: pending)
- System redirects to Payment Gateway
- User completes payment on Payment Gateway
- Payment Gateway sends webhook callback
- System updates transaction status (completed)
- System updates wallet balance
- User sees updated balance
Alternative Flows:
- 3a. Amount out of range: System returns validation error
- 7a. Payment failed: System updates transaction status (failed), user sees error
Figure 4: UC-02 Deposit Funds - Activity Diagram
Figure 5: UC-02 Deposit Funds - Sequence Diagram
3.3 UC-03: View Transaction History
| Field | Description |
|---|
| Use Case ID | UC-03 |
| Name | View Transaction History |
| Actor | User |
| Precondition | User is logged in, wallet has transactions |
| Postcondition | User views transaction history |
| Trigger | User accesses transaction history page |
Main Flow:
- User navigates to transaction history
- System retrieves transactions with filters (type, date range, status)
- System returns paginated transaction list
- User views transaction details
3.4 UC-04: Set Wallet PIN
| Field | Description |
|---|
| Use Case ID | UC-04 |
| Name | Set Wallet PIN |
| Actor | User |
| Precondition | User is logged in, wallet exists |
| Postcondition | Wallet PIN set for transaction authorization |
| Trigger | User clicks "Set PIN" or "Change PIN" |
Main Flow:
- User enters new PIN (6 digits)
- System validates PIN format
- System hashes PIN and stores in wallet_wallets
- System confirms PIN set successfully
3.5 UC-05: Add Payment Method
| Field | Description |
|---|
| Use Case ID | UC-05 |
| Name | Add Payment Method |
| Actor | User |
| Precondition | User is logged in, wallet exists |
| Postcondition | Payment method added to wallet |
| Trigger | User clicks "Add Payment Method" |
Main Flow:
- User selects payment method type (bank account, credit card, debit card, e-wallet)
- User enters account details
- System validates account details
- System saves payment method (is_verified: false)
- System initiates verification process
- Payment method verified and activated
3.6 UC-06: Request Withdrawal
| Field | Description |
|---|
| Use Case ID | UC-06 |
| Name | Request Withdrawal |
| Actor | User |
| Precondition | User is logged in, wallet has sufficient balance |
| Postcondition | Withdrawal request submitted for approval |
| Trigger | User clicks "Withdraw" |
Main Flow:
- User selects payment method for withdrawal
- User enters withdrawal amount
- System validates amount and checks limits
- System creates wallet_payout_requests record (status: pending)
- System freezes withdrawal amount in wallet
- System notifies admin for approval
- Admin reviews and approves request
- System processes payment to bank account
- System updates wallet balance
Alternative Flows:
- 3a. Amount exceeds balance: System returns error
- 3b. Daily/monthly limit exceeded: System returns limit error
- 7a. Admin rejects: System unfreezes amount, user notified
Figure 6: UC-06 Request Withdrawal - Activity Diagram
Figure 7: UC-06 Request Withdrawal - Sequence Diagram
3.7 UC-07: Transfer to Another Wallet
| Field | Description |
|---|
| Use Case ID | UC-07 |
| Name | Transfer to Another Wallet |
| Actor | User |
| Precondition | User is logged in, sufficient balance |
| Postcondition | Funds transferred to recipient wallet |
| Trigger | User clicks "Transfer" |
Main Flow:
- User enters recipient email or wallet ID
- System validates recipient exists
- User enters transfer amount
- System validates amount and balance
- User confirms with wallet PIN
- System deducts from sender wallet
- System credits to recipient wallet
- System creates transaction records for both wallets
3.8 UC-08: Pay for Job Posting
| Field | Description |
|---|
| Use Case ID | UC-08 |
| Name | Pay for Job Posting |
| Actor | Employer |
| Precondition | Employer is logged in, job created |
| Postcondition | Payment completed, job posting activated |
| Trigger | Employer submits job for payment |
Main Flow:
- Employer creates job posting
- System creates wallet_payment_orders record
- System checks wallet balance
- System prompts for wallet PIN
- Employer enters PIN
- System verifies PIN and deducts amount
- System updates payment order status (paid)
- System notifies RECR module to activate job
- Employer sees job posted successfully
Figure 8: UC-08 Pay for Job Posting - Activity Diagram
Figure 9: UC-08 Pay for Job Posting - Sequence Diagram
3.9 UC-09: Pay for Featured Job
| Field | Description |
|---|
| Use Case ID | UC-09 |
| Name | Pay for Featured Job |
| Actor | Employer |
| Precondition | Job is active |
| Postcondition | Job marked as featured |
| Trigger | Employer clicks "Feature Job" |
Main Flow:
- Employer selects job to feature
- System displays featured job pricing
- Employer confirms payment
- System processes payment from wallet
- System updates job status to featured
3.10 UC-10: Manage Payment Methods
| Field | Description |
|---|
| Use Case ID | UC-10 |
| Name | Manage Payment Methods |
| Actor | User |
| Precondition | User has payment methods |
| Postcondition | Payment methods updated |
| Trigger | User accesses payment methods page |
Main Flow:
- User views list of payment methods
- User can add new payment method
- User can set default payment method
- User can remove payment method
4. Functional Requirements
4.1 Wallet Management Requirements
| Req ID |
Module |
Requirement |
Use Case |
Priority |
Description |
| FR-001 |
WALLET |
Create Wallet |
UC-01 |
High |
System automatically creates a wallet when user registers |
| FR-002 |
WALLET |
View Wallet Balance |
UC-01 |
High |
Users can view their wallet balance and status |
| FR-003 |
WALLET |
Set Wallet PIN |
UC-04 |
High |
Users can set a 6-digit PIN for transaction authorization |
| FR-004 |
WALLET |
View Transaction History |
UC-03 |
High |
Users can view complete transaction history with filters |
| FR-005 |
WALLET |
Manage Payment Methods |
UC-05, UC-10 |
Medium |
Users can add, remove, and set default payment methods |
4.2 Transaction Requirements
| Req ID |
Module |
Requirement |
Use Case |
Priority |
Description |
| FR-006 |
WALLET |
Deposit Funds |
UC-02 |
High |
Users can deposit funds via bank transfer, credit card, or e-wallet |
| FR-007 |
WALLET |
Request Withdrawal |
UC-06 |
High |
Users can request withdrawals to bank accounts (admin approval required) |
| FR-008 |
WALLET |
Transfer Funds |
UC-07 |
Medium |
Users can transfer funds to other user wallets |
| FR-009 |
WALLET |
Transaction Audit Trail |
UC-03 |
High |
All transactions are logged with before/after balance |
| FR-010 |
WALLET |
Transaction Limits |
UC-02, UC-06 |
Medium |
System enforces daily and monthly transaction limits |
4.3 Payment Requirements
| Req ID |
Module |
Requirement |
Use Case |
Priority |
Description |
| FR-011 |
WALLET |
Pay for Job Posting |
UC-08 |
High |
Employers can pay for job postings using wallet balance |
| FR-012 |
WALLET |
Pay for Featured Job |
UC-09 |
Medium |
Employers can pay to feature their job listings |
| FR-013 |
WALLET |
Payment Orders |
UC-08, UC-09 |
High |
System creates payment orders for all financial transactions |
| FR-014 |
WALLET |
Refund Processing |
UC-06 |
Medium |
System can process refunds for cancelled services |
| FR-015 |
WALLET |
Admin Approval |
UC-06 |
High |
Admins can approve or reject withdrawal requests |
5. Data Model
5.1 Entity Relationship Diagram
Figure 10: Wallet ERD
5.2 Data Requirements
| Req ID |
Entity |
Description |
Related FR |
| DR-001 | wallet_wallets | User wallet accounts with balance and limits | FR-001, FR-002 |
| DR-002 | wallet_transactions | Complete transaction history with audit trail | FR-004, FR-009 |
| DR-003 | wallet_payment_methods | Linked bank accounts and payment cards | FR-005 |
| DR-004 | wallet_payment_orders | Payment orders for services | FR-011, FR-012, FR-013 |
| DR-005 | wallet_payout_requests | Withdrawal requests for admin approval | FR-007, FR-015 |
6. API Specification
6.1 Endpoint Summary
Wallet Endpoints (All Users)
| Method |
Path |
Description |
Requirement IDs |
| GET | /wallet/balance | View wallet balance | FR-002 |
| POST | /wallet/pin | Set or change wallet PIN | FR-003 |
| GET | /wallet/transactions | View transaction history | FR-004 |
| POST | /wallet/deposit | Deposit funds | FR-006 |
| POST | /wallet/withdraw | Request withdrawal | FR-007 |
| POST | /wallet/transfer | Transfer to another wallet | FR-008 |
| POST | /wallet/pay | Pay for service | FR-011, FR-012 |
Payment Methods Endpoints
| Method |
Path |
Description |
Requirement IDs |
| GET | /wallet/payment-methods | List payment methods | FR-005 |
| POST | /wallet/payment-methods | Add payment method | FR-005 |
| PATCH | /wallet/payment-methods/:id | Update payment method | FR-005 |
| DELETE | /wallet/payment-methods/:id | Remove payment method | FR-005 |
Admin Endpoints
| Method |
Path |
Description |
Requirement IDs |
| GET | /admin/wallet/payouts | List payout requests | FR-015 |
| PATCH | /admin/wallet/payouts/:id | Approve/reject payout | FR-015 |
| PATCH | /admin/wallet/wallets/:id/freeze | Freeze/unfreeze wallet | FR-015 |
| GET | /admin/wallet/wallets | List all wallets | FR-015 |
Webhook Endpoints
| Method |
Path |
Description |
Requirement IDs |
| POST | /webhooks/payment/callback | Payment Gateway callback | FR-006 |
7. Integration
7.1 Sequence Diagram
Figure 11: Wallet Integration Flow
7.2 Webhook Events
| Event | Direction | Protocol | Description |
|---|
| wallet.deposit.completed | Outbound | RabbitMQ | Triggered when deposit is completed |
| wallet.payment.completed | Outbound | RabbitMQ | Triggered when payment for service is completed |
| wallet.withdrawal.completed | Outbound | RabbitMQ | Triggered when withdrawal is processed |
| wallet.transfer.completed | Outbound | RabbitMQ | Triggered when transfer is completed |
| payment.callback.received | Inbound | Webhook | Payment Gateway sends payment status |
7.3 Integration with Recruitment Module
| Integration | Direction | Protocol | Description |
|---|
| Job Posting Payment | WALLET -> RECR | RabbitMQ | Notify RECR when job posting is paid |
| Featured Job Payment | WALLET -> RECR | RabbitMQ | Notify RECR when job is featured |
| Refund Request | RECR -> WALLET | RabbitMQ | Request refund for cancelled job |
8. Non-Functional Requirements
| Req ID |
Category |
Requirement |
Target |
| NFR-001 | Performance | API response time for balance queries | < 200ms (p95) |
| NFR-002 | Performance | Transaction processing time | < 1s |
| NFR-003 | Scalability | Support concurrent transactions | 1000+ concurrent users |
| NFR-004 | Availability | System uptime | 99.99% |
| NFR-005 | Security | Transaction authorization | PIN-based authentication |
| NFR-006 | Security | Data encryption | AES-256 for sensitive data |
| NFR-007 | Compliance | Financial audit trail | Complete transaction history with timestamps |
| NFR-008 | Data | Transaction retention | Minimum 7 years |
9. Requirements Traceability Matrix
| Req ID |
Requirement |
Role |
TDS Section |
DB Table |
API Endpoint |
| FR-001 | Create Wallet | System | 3.1 | wallet_wallets | POST /wallet (auto) |
| FR-002 | View Wallet Balance | User | 3.1 | wallet_wallets | GET /wallet/balance |
| FR-003 | Set Wallet PIN | User | 3.1 | wallet_wallets | POST /wallet/pin |
| FR-004 | View Transaction History | User | 3.2 | wallet_transactions | GET /wallet/transactions |
| FR-005 | Manage Payment Methods | User | 3.3 | wallet_payment_methods | GET/POST/PATCH/DELETE /wallet/payment-methods |
| FR-006 | Deposit Funds | User | 3.4 | wallet_transactions | POST /wallet/deposit |
| FR-007 | Request Withdrawal | User | 3.5 | wallet_payout_requests | POST /wallet/withdraw |
| FR-008 | Transfer Funds | User | 3.6 | wallet_transactions | POST /wallet/transfer |
| FR-009 | Transaction Audit Trail | System | 3.2 | wallet_transactions | - |
| FR-010 | Transaction Limits | System | 3.4, 3.5 | wallet_wallets | - |
| FR-011 | Pay for Job Posting | Employer | 3.7 | wallet_payment_orders | POST /wallet/pay |
| FR-012 | Pay for Featured Job | Employer | 3.7 | wallet_payment_orders | POST /wallet/pay |
| FR-013 | Payment Orders | System | 3.7 | wallet_payment_orders | - |
| FR-014 | Refund Processing | System | 3.2 | wallet_transactions | POST /wallet/refund |
| FR-015 | Admin Approval | Admin | 3.5 | wallet_payout_requests | PATCH /admin/wallet/payouts/:id |
