pos-system/microservices/services/merchant-service-net/docs/en/README.md

Merchant Service .NET 10

Service for managing Merchants (Shop Owners), Shops, and Merchant Staff for the GoodGo ecosystem.

Overview

Merchant Service provides management capabilities for:

• Merchant Management - Registration, verification, merchant (shop owner) management
• Shop Management - Create and manage stores (Online, Physical, Hybrid)
• Staff Management - Employee management, permissions for POS System
• Branch Management - Shop branch/location management
• POS Authentication - PIN authentication for POS devices
• Multi-category Support - Support for multiple business categories

Requirements

Requirement	Version
.NET SDK	10.0.101+
Docker	24.0+
PostgreSQL	15+

Quick Start

Run with Docker

cd deployments/local
docker-compose up -d

Run Local

cd services/merchant-service-net
dotnet restore
dotnet build
dotnet run --project src/MerchantService.API

Database Migrations

Requirements

# Install EF Core tools (one-time)
dotnet tool install --global dotnet-ef

Create Migration

# Create new migration
dotnet ef migrations add <MigrationName> \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API

Apply Migration

# Apply migrations to database
dotnet ef database update \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API

API Endpoints

Merchant Endpoints (/api/v1/merchants)

Method	Endpoint	Description	Auth
POST	/api/v1/merchants/register	Register as a Merchant	✅ User
GET	/api/v1/merchants/me	Get current Merchant info	✅ Merchant
PUT	/api/v1/merchants/me	Update Merchant info	✅ Merchant
POST	/api/v1/merchants/me/verify	Submit verification documents	✅ Merchant

Shop Endpoints (/api/v1/shops)

Method	Endpoint	Description	Auth
GET	/api/v1/shops	List Merchant's shops	✅ Merchant
POST	/api/v1/shops	Create new shop	✅ Merchant
GET	/api/v1/shops/{id}	Get shop by ID	✅ Merchant
PUT	/api/v1/shops/{id}	Update shop	✅ Merchant
DELETE	/api/v1/shops/{id}	Close shop	✅ Merchant
POST	/api/v1/shops/{id}/publish	Publish shop (visible to customers)	✅ Merchant
POST	/api/v1/shops/{id}/deactivate	Set shop inactive	✅ Merchant
GET	/api/v1/shops/slug/{slug}	Get shop by slug (public)	❌

Shop Branch Endpoints

Method	Endpoint	Description	Auth
GET	/api/v1/shops/{shopId}/branches	List branches	✅
POST	/api/v1/shops/{shopId}/branches	Create new branch	✅ Merchant
PUT	/api/v1/shops/{shopId}/branches/{id}	Update branch	✅ Merchant
DELETE	/api/v1/shops/{shopId}/branches/{id}	Delete branch	✅ Merchant
GET	/api/v1/shops/nearby	Find nearby shops	❌

Merchant Staff Endpoints

Method	Endpoint	Description	Auth
GET	/api/v1/merchants/me/staff	List staff	✅ Merchant
POST	/api/v1/merchants/me/staff/invite	Invite staff	✅ Merchant
PUT	/api/v1/merchants/me/staff/{id}	Update staff	✅ Merchant
DELETE	/api/v1/merchants/me/staff/{id}	Remove staff	✅ Merchant
POST	/api/v1/staff/accept-invite	Accept invitation	✅ User

POS Endpoints (/api/v1/pos)

Method	Endpoint	Description	Auth
POST	/api/v1/pos/auth/pin	POS login with PIN	✅ Staff
POST	/api/v1/pos/devices/register	Register POS device	✅ Staff
GET	/api/v1/pos/me	Get current Staff info	✅ Staff

Admin Merchant Endpoints (/api/v1/admin/merchants)

Method	Endpoint	Description	Auth
GET	/api/v1/admin/merchants	List all merchants (paginated)	✅ Admin
GET	/api/v1/admin/merchants/statistics	Merchant statistics	✅ Admin
GET	/api/v1/admin/merchants/{id}	Merchant details	✅ Admin
POST	/api/v1/admin/merchants/{id}/approve	Approve merchant	✅ Admin
POST	/api/v1/admin/merchants/{id}/reject	Reject merchant	✅ Admin
POST	/api/v1/admin/merchants/{id}/suspend	Suspend merchant	✅ Admin
POST	/api/v1/admin/merchants/{id}/reactivate	Reactivate merchant	✅ Admin
POST	/api/v1/admin/merchants/{id}/ban	Permanently ban merchant	✅ Admin

Admin Shop Endpoints (/api/v1/admin/shops)

Method	Endpoint	Description	Auth
GET	/api/v1/admin/shops	List all shops (paginated)	✅ Admin
GET	/api/v1/admin/shops/{id}	Shop details	✅ Admin
POST	/api/v1/admin/shops/{id}/suspend	Suspend shop	✅ Admin
POST	/api/v1/admin/shops/{id}/reactivate	Reactivate shop	✅ Admin
POST	/api/v1/admin/shops/{id}/close	Permanently close shop	✅ Admin

Health Checks

Endpoint	Purpose
/health	Full health status
/health/live	Liveness check
/health/ready	Readiness check

Merchant Registration Flow

Step 1: Register as Merchant

curl -X POST http://localhost:5003/api/v1/merchants/register \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Saigon Coffee",
    "type": "Company",
    "taxId": "0123456789",
    "businessLicenseNumber": "BL-2024-001"
  }'

Response:

{
  "success": true,
  "data": {
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Saigon Coffee",
    "status": "PendingApproval"
  }
}

Step 2: Wait for Admin Approval

Admin will review and approve the merchant. After approval:

• Role Merchant will be assigned to the user in IAM Service
• Status changes to Active

Step 3: Create Shop

curl -X POST http://localhost:5003/api/v1/shops \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saigon Coffee - District 1",
    "slug": "saigon-coffee-d1",
    "type": "Hybrid",
    "category": "FoodBeverage",
    "phone": "0901234567",
    "email": "d1@saigoncoffee.vn"
  }'

Step 4: Add Branch (For physical stores)

curl -X POST http://localhost:5003/api/v1/shops/{shopId}/branches \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Le Loi Branch",
    "street": "123 Le Loi Street",
    "district": "District 1",
    "city": "Ho Chi Minh City",
    "latitude": 10.7769,
    "longitude": 106.7009
  }'

Step 5: Invite Staff

curl -X POST http://localhost:5003/api/v1/merchants/me/staff/invite \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "staff@example.com",
    "role": "Cashier",
    "shopId": "shop-uuid",
    "branchId": "branch-uuid"
  }'

Configuration

Environment Variables

Variable	Description	Default
ASPNETCORE_ENVIRONMENT	Environment	Development
DATABASE_URL	PostgreSQL connection	-
Jwt__Authority	IAM Service URL	http://iam-service-net:8080
IamService__BaseUrl	IAM Service base URL	-
WalletService__BaseUrl	Wallet Service base URL	-

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=merchant;Username=postgres;Password=postgres"
  },
  "Jwt": {
    "Authority": "http://localhost:5001"
  },
  "IamService": {
    "BaseUrl": "http://localhost:5001"
  },
  "WalletService": {
    "BaseUrl": "http://localhost:5004"
  }
}

Integration with Other Services

IAM Service

• Validate User token
• Assign Merchant/MerchantStaff roles
• Get Organization hierarchy

Wallet Service

• Merchant settlement
• Commission calculation
• Balance check

Membership Service

• Customer visit tracking → Add EXP
• Member level → Special discount at shop

Chat Service

• Shop support channel
• Staff-Customer conversation

Gift Voucher Service (Planned)

• Create voucher campaigns
• Voucher redemption at shop

Testing

# Unit tests
dotnet test tests/MerchantService.UnitTests

# Functional tests
dotnet test tests/MerchantService.FunctionalTests

Deployment

Docker Build

docker build -t goodgo/merchant-service:latest .
docker run -p 5003:8080 --env-file .env goodgo/merchant-service:latest

Kubernetes

See deployments/kubernetes/merchant-service.yaml

Swagger UI

After running the service, access Swagger UI at:

• Local: http://localhost:5003/swagger
• Docker: http://localhost/api/v1/merchants/swagger

Resources

• Clean Architecture Documentation
• API Design Skill
• CQRS Pattern Skill