Skip to content

Wallet Service API

💳

A comprehensive digital wallet and financial transactions REST API built with Java, Spring Boot, and PostgreSQL. Manages user wallets, balances, fund transfers, transactions, and ledger operations.

Features

Feature Description Icon
Wallet Management Create and manage user digital wallets 💰
Balance Tracking Real-time balance updates and history 📊
Fund Transfers Transfer funds between wallets and accounts 💸
Transaction Ledger Immutable transaction history with audit trail 📜
Multi-Currency Support Support transactions in multiple currencies 💱
Reconciliation Verify wallet balances and identify discrepancies ✓
Multi-Tenant Support Isolate wallets per tenant 🏢

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(WalletController)
    B --> C[WalletService]
    C --> D[TransactionService]
    C --> E[BalanceService]
    D --> F[WalletRepository]
    D --> G[TransactionRepository]
    E --> H[LedgerRepository]
    F --> I[(PostgreSQL)]
    G --> I
    H --> I
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Note: Real API endpoints to be provided and included here.

Method Endpoint Description Notes/Parameters
POST /api/v1/wallets Create wallet tenantId header, wallet type
GET /api/v1/wallets/{id} Get wallet details
POST /api/v1/transfers Transfer funds between wallets From/to wallet ID, amount
GET /api/v1/wallets/{id}/balance Get current balance

Sequence: Transfer Funds Between Wallets

sequenceDiagram
    participant U as User
    participant API as WalletController
    participant W as WalletService
    participant T as TransactionService
    participant B as BalanceService
    participant Repo as WalletRepository
    U->>API: POST /transfers (fromWallet, toWallet, amount)
    API->>W: validate transfer
    W->>B: check source balance
    B-->>W: balance sufficient
    W->>Repo: begin transaction
    Repo-->>W: transaction started
    W->>T: create transfer transaction
    T->>Repo: save transaction
    Repo-->>T: saved
    T->>B: update balances
    B-->>T: balances updated
    T->>Repo: commit transaction
    Repo-->>T: committed
    T-->>W: transfer complete
    W-->>API: TransferResponse
    API-->>U: 201 Created + transfer details
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    wallets {
        UUID id PK
        UUID user_id
        UUID tenant_id
        VARCHAR wallet_type
        DECIMAL current_balance
        VARCHAR currency
        VARCHAR status
        TIMESTAMP created
        TIMESTAMP updated
    }

    transactions {
        UUID id PK
        UUID wallet_id FK
        VARCHAR transaction_type
        DECIMAL amount
        DECIMAL balance_after
        VARCHAR status
        TEXT description
        TIMESTAMP created
        TIMESTAMP updated
    }

    transfers {
        UUID id PK
        UUID tenant_id
        UUID source_wallet_id FK
        UUID destination_wallet_id FK
        DECIMAL amount
        VARCHAR currency
        VARCHAR status
        TIMESTAMP created
        TIMESTAMP updated
    }

    ledger_entries {
        UUID id PK
        UUID transaction_id FK
        VARCHAR entry_type
        DECIMAL amount
        TIMESTAMP recorded_at
    }

    wallets ||--o{ transactions : "has"
    wallets ||--o{ transfers : "source"
    wallets ||--o{ transfers : "destination"
    transactions ||--o{ ledger_entries : "creates"
Hold "Alt" / "Option" to enable pan & zoom

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle

Setup

git clone https://github.com/Olanna-tech/wallet-service-java.git
cd wallet-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Configuration

Set the following environment variables in application.yml: 

wallet:
  default-currency: USD
  transaction-confirmation-required: false
  daily-transfer-limit: 100000
  monthly-transfer-limit: 500000
  enable-p2p-transfers: true
  ledger-retention-months: 36

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact