Manual Payment System API

Backend APIs for managing payment workflows between organizations, providers, customers, and transactions. The system is designed for role-based operations across System Admin, Organization Operator, and Provider Operator users.

Overview

This project provides the server-side services for a manual payment platform that supports:

• User authentication through OTP-based login
• Organization and provider administration
• Customer onboarding and balance management
• Transaction recording and review
• Secure API access with JWT authorization

The implementation is currently focused on the backend API layer and exposes Swagger documentation in development mode.

Business Domain

The system is built around the following business entities and rules:

Core roles

Role	Primary purpose	Management scope
System Admin	Platform administration	Full management of users, providers, organizations, and customers
Organization Operator	Operational handling for an organization	Manage customers, upload customer files, review transactions
Provider Operator	Provider-side operations	View transactions and provider-related activity

Main entities

• Users

  • Fields: phone, name
  • Managed by: System Admin only

• Providers

  • Fields: title, transaction fee percentage, wallet balance
  • Managed by: System Admin only
  • Wallet settlement can be handled by an Organization Operator

• Organizations

  • Fields: title
  • Managed by: System Admin only

• Customers

  • Fields: smartId, balance, OrganizationId
  • Managed by: System Admin and Organization Operator
  • Can be updated by uploading a sheet file by an Organization Operator

• Transactions

  • Fields: fingerprint, smartId, amount, fees, CustomerId, ProviderId, and related payment details
  • Access: view-only for System Admin, Organization Operator, and Provider Operator
  • The transaction amount must equal the customer balance minus the provider transaction fee
  • Transactions are expected to originate from a secure fingerprint reader service

Transaction types

1. provider_payment - provider settlement flow
2. card_payment - provider to customer payment flow
3. customer_payment - organization to customer payment flow

System Context

flowchart LR
    A[System Admin] --> B[Users]
    A --> C[Providers]
    A --> D[Organizations]
    E[Organization Operator] --> F[Customers]
    E --> G[Customer File Upload]
    H[Provider Operator] --> I[Transaction Review]
    F --> J[Transactions]
    G --> J
    I --> J

Loading

Entity Relationship Overview

erDiagram
    ORGANIZATION ||--o{ CUSTOMER : has
    ORGANIZATION ||--o{ CUSTOMER_TRANSACTION : records
    CUSTOMER ||--o{ CUSTOMER_TRANSACTION : belongs_to
    PROVIDER ||--o{ CUSTOMER_TRANSACTION : processes
    CUSTOMER_TRANSACTION ||--o| CARD_PAYMENT : includes
    CUSTOMER_TRANSACTION ||--o| CUSTOMER_PAYMENT : includes
    USER ||--o| ORGANIZATION_USER : linked
    USER ||--o| PROVIDER_USER : linked

Loading

API Flow

sequenceDiagram
    participant Client
    participant AuthAPI as Authentication API
    participant SecureService as Fingerprint Reader Service
    participant API as MPS API
    participant DB as MySQL Database

    Client->>AuthAPI: Send OTP / Get Token
    AuthAPI->>DB: Validate user and OTP
    AuthAPI-->>Client: JWT token

    Client->>API: Create or review transaction
    API->>SecureService: Validate fingerprint source
    SecureService-->>API: Transaction payload
    API->>DB: Store transaction data
    DB-->>API: Confirmation
    API-->>Client: Response

Loading

Tech Stack

• .NET 9 / ASP.NET Core Web API
• C#
• Entity Framework Core
• MySQL via MySql.EntityFrameworkCore
• JWT authentication
• Swagger / OpenAPI for API documentation
• Newtonsoft.Json and System.Text.Json for serialization
• MemoryCache for OTP workflow
• BCrypt.Net-Next for secure password-related operations

Project Structure

• Controllers/Public - public endpoints such as authentication
• Controllers/System - system-level administrative APIs
• DAL - EF Core context, entities, and models
• Helpers - utilities, auth handlers, repositories, and shared helpers
• Shared - enums and shared constants

Prerequisites

• .NET SDK 9.0+
• MySQL database instance
• Optional: Swagger UI access in development mode

Getting Started

1. Create or prepare the database

• Import the SQL schema from the database scripts in the db folder, such as mps-v1.0-beta.sql or mps-v1.1-beta.sql.
• Make sure your MySQL server is running and accessible.
• Update the connection string in appsettings.json or appsettings.Development.json to point to your database.

2. Restore dependencies

dotnet restore

3. Build the project

dotnet build

4. Run the API

dotnet run

5. Open Swagger UI in development mode

• Local development URL: http://localhost:5000 or the configured ASP.NET launch URL
• Swagger UI is served at the application root when running in Development

Configuration

Set the required values in appsettings.json or appsettings.Development.json:

{
  "ConnectionString": "Server=localhost;Database=mps;Uid=root;Pwd=your_password;",
  "IssuerSigningKey": "your-very-secure-signing-key"
}

Authentication

The API uses OTP-based authentication for login.

Endpoints

• POST /api/Authentication/SendOTP
• POST /api/Authentication/GetTokenByOTP

After login, include the returned JWT in the Authorization header:

Authorization: Bearer <token>

Notes

• The current implementation is a backend service focused on API and domain logic.
• Transaction validation and role-based access are central parts of the design.
• The project is ready for extension with additional services, file parsing, and deeper workflow automation.