pos-system/services/wallet-service-net/docs/en

Wallet Service .NET

EN: Wallet and Point Account management service for GoodGo Platform.
VI: Dịch vụ quản lý Ví và Tài khoản Điểm cho GoodGo Platform.

Overview

The Wallet Service provides comprehensive wallet and loyalty points management with:

• Wallet Management - Create, deposit, withdraw, transfer funds
• Escrow Module - Hold, commit, and release funds (for Promotion Service)
• Point Account - Earn, spend, and track loyalty points
• Transaction History - Full audit trail of all transactions
• Multi-Currency Support - Default VND with currency support
• Domain-Driven Design - Clean Architecture with CQRS pattern

Tech Stack

Component	Technology
Framework	.NET 10
Database	PostgreSQL (EF Core)
CQRS	MediatR
Validation	FluentValidation
API Docs	Swagger/OpenAPI
Logging	Serilog

Prerequisites

# Check .NET version
dotnet --version  # Should be 10.0.x

Quick Start

1. Configure Environment

cp .env.example .env
# Edit .env with your database connection

2. Run with Docker

cd deployments/local
docker-compose up wallet-service -d

3. Run Locally

cd services/wallet-service-net
dotnet restore
dotnet build
dotnet run --project src/WalletService.API

API Endpoints

Wallet APIs

Method	Endpoint	Description
POST	/api/v1/wallets	Create new wallet
GET	/api/v1/wallets/me	Get current user's wallet
GET	/api/v1/wallets/{id}	Get wallet by ID
POST	/api/v1/wallets/deposit	Deposit funds
POST	/api/v1/wallets/withdraw	Withdraw funds
POST	/api/v1/wallets/transfer	Transfer between wallets
POST	/api/v1/wallets/{id}/freeze	Freeze wallet
POST	/api/v1/wallets/{id}/unfreeze	Unfreeze wallet
GET	/api/v1/wallets/transactions	Get transaction history

Escrow APIs (New)

Method	Endpoint	Description
POST	/api/v1/wallets/{walletId}/holds	Create a hold
POST	/api/v1/wallets/{walletId}/holds/{holdId}/execute	Execute/Commit hold (deduct funds)
POST	/api/v1/wallets/{walletId}/holds/{holdId}/release	Release hold (return funds)
POST	/api/v1/wallets/{walletId}/holds/{holdId}/cancel	Cancel hold
GET	/api/v1/wallets/{walletId}/holds/{holdId}	Get hold details

Points APIs

Method	Endpoint	Description
GET	/api/v1/points/me	Get current user's points
POST	/api/v1/points/earn	Earn points
POST	/api/v1/points/spend	Spend points
GET	/api/v1/points/transactions	Get point transactions

Health Endpoints

Endpoint	Purpose
/health	Full health status
/health/live	Liveness probe (K8s)
/health/ready	Readiness probe (K8s)

Project Structure

wallet-service-net/
├── src/
│   ├── WalletService.API/           # API Layer
│   │   ├── Controllers/             # REST endpoints
│   │   └── Application/             # Commands & Queries
│   │       ├── Commands/            # Write operations
│   │       └── Queries/             # Read operations
│   │
│   ├── WalletService.Domain/        # Domain Layer 
│   │   ├── AggregatesModel/
│   │   │   ├── WalletAggregate/     # Wallet, Transaction, Money
│   │   │   └── PointAccountAggregate/  # Points, PointTransaction
│   │   ├── Events/                  # Domain events
│   │   └── Exceptions/              # Domain exceptions
│   │
│   └── WalletService.Infrastructure/  # Infrastructure Layer
│       ├── EntityConfigurations/    # EF Core mappings
│       ├── Repositories/            # Data access
│       └── WalletServiceContext.cs  # DbContext
│
├── tests/
│   ├── WalletService.UnitTests/     # Domain & Logic tests
│   └── WalletService.FunctionalTests/  # API integration tests
│
├── docs/
│   ├── en/                          # English docs
│   └── vi/                          # Vietnamese docs
│
└── Dockerfile

Domain Model

Wallet Aggregate

// Create wallet
var wallet = new Wallet(userId, "VND");

// Deposit funds
wallet.Deposit(new Money(1000000m, "VND"), "Salary", "REF001");

// Withdraw funds  
wallet.Withdraw(new Money(500000m, "VND"), "Shopping", "REF002");

// Freeze/Unfreeze
wallet.Freeze();
wallet.Unfreeze();

// Escrow
var hold = wallet.Hold(100000m, CurrencyType.VND, "CAMPAIGN", campaignId, "Hold for campaign");
wallet.ExecuteHold(hold.Id, 50000m, "ORDER123"); // Commit 50k
wallet.ReleaseHold(hold.Id, 50000m); // Return 50k
wallet.CancelHold(hold.Id); // Cancel remaining

Point Account Aggregate

// Create account
var account = new PointAccount(userId);

// Earn points
account.EarnPoints(100, "ORDER001", "Purchase reward", expiresAt);

// Spend points
account.SpendPoints(50, "ORDER002", "Redeem discount");

// Adjust points (admin)
account.AdjustPoints(10, "ADMIN", "Bonus adjustment");

Testing

# Run all tests
dotnet test

# Run with coverage
dotnet test /p:CollectCoverage=true

# Unit tests only
dotnet test tests/WalletService.UnitTests

# Functional tests only
dotnet test tests/WalletService.FunctionalTests

Test Results

• 23 tests total
• 20 unit tests (Wallet, PointAccount domain)
• 3 functional tests (Health endpoints)

Configuration

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection	Yes
ASPNETCORE_ENVIRONMENT	Environment	No (default: Development)
JWT_AUTHORITY	JWT issuer URL	Yes (for auth)

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=wallet_db;Username=postgres;Password=postgres"
  },
  "Jwt": {
    "Authority": "http://localhost:5001",
    "Issuer": "http://localhost:5001"
  }
}

Database Migrations

# Create migration
dotnet ef migrations add InitialCreate \
  --project src/WalletService.Infrastructure \
  --startup-project src/WalletService.API

# Apply migration
dotnet ef database update \
  --project src/WalletService.Infrastructure \
  --startup-project src/WalletService.API

Deployment

Docker Build

docker build -t goodgo/wallet-service:latest .

Docker Compose

Service is registered in deployments/local/docker-compose.yml with Traefik routing.

Resources

• Architecture Documentation
• GoodGo Platform Docs
• eShopOnContainers Reference

License

Proprietary - GoodGo Platform