Banking API

This project is a clean, modular Banking API built with FastEndpoints, following the REPR pattern (Request, Endpoint, Response) — a modern, streamlined alternative to traditional MVC architecture. The API emphasizes clear separation of concerns and lightweight endpoint definition. It features role-based access control with three roles:

Customer – for account holders
Teller – for handling transactions
Admin – for managing accounts and system-level operations

The backend is powered by Event Sourcing, implemented with MartenDb, providing full traceability and consistency through immutable event logs.

UML use case diagram

Events and Projection

BankAccount (Read model)

Failed to fetch :(

GistUrl : https://gist.githubusercontent.com/basdidon/69f8c2f00ff92a9a19f2892941db6174/raw/5a82b8b2e360fa76c08534317f25ab1a2069c8fb/BankAccount.cs

Open

BankAccount.cs

This file defines the read model for a bank account. The BankAccount class represents the current state of a user's bank account. Key properties include:

Id : Unique identifier for the account (likely assigned by the event stream).
OwnerId : The user who owns the account.
AccountNumber : Human-readable identifier for the account (e.g., "123-456789-0").
Balance : Current balance of the account.
IsFrozen : Boolean flag indicating whether the account is frozen.

Events

These immutable event records represent actions that occur over time. They include:

AccountCreated: Fired when an account is opened.
MoneyDeposit,MoneyWithdraw: For deposit and withdrawal operations.
MoneySent,MoneyRecieved: For transferring money between accounts.
AccountFrozen,AccountUnfrozen: Change the account's status.
AccountClosed: Indicates that the account has been terminated.

Failed to fetch :(

GistUrl : https://gist.githubusercontent.com/basdidon/69f8c2f00ff92a9a19f2892941db6174/raw/5a82b8b2e360fa76c08534317f25ab1a2069c8fb/events.cs

Open

BankAccountProjection

Failed to fetch :(

GistUrl : https://gist.githubusercontent.com/basdidon/69f8c2f00ff92a9a19f2892941db6174/raw/e63f8ba016410fc9adcb69a7e28aef216a346a11/BankAccountProjection.cs

Open

This class maps events to changes in the BankAccount state using Marten's SingleStreamProjection<T>

Withdrawal

To prevent a Teller or Admin from arbitrarily withdrawing funds from an account owned by a regular user, additional logic is required. When a user intends to make a withdrawal, they must inform the Teller, who then sends a withdrawal request to the server. The server generates and sends a One-Time Password (OTP) to the user. The user provides the OTP to the Teller, who then submits a withdrawal confirmation request to complete the process.

Endpoints

Method	Endpoint	Description
GET	/accounts	List accounts
POST	/accounts	Create a new account
GET	/accounts/{accountId}	Get account by ID
GET	/accounts/{accountId}/transactions	Query all transactions by specific account
POST	/accounts/{accountId}/deposit	Deposit funds
POST	/accounts/{accountId}/withdraw	Initiate withdrawal (pending state)
POST	/withdrawal/{requestId}/confirm	Confirm withdrawal
POST	/accounts/{sourceAccountId}/transfer	Transfer funds
POST	/accounts/{accountId}/freeze	Freeze the account
POST	/accounts/{accountId}/unfreeze	Unfreeze the account

GET /accounts

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
userId	Claims	Guid	Yes	-	Represent user who send this request
ownerId	QueryParameter	Guid	No	-	For Teller and Admin to List accounts that owned by specific user
page	QueryParameter	int	No	1	Page number
pageSize	QueryParameter	int	No	20	Number of items per page

API Behaviors

Role	Condition	Response	Note
Customer	Provided ownerId	403 Forbidden	customer cannot access other's accounts
Customer	Not provided ownerId	200 Success	Return items owned by the current user
Teller or Admin	Provided ownerId	200 Success	Return accounts owned by that user
Teller or Admin	Not provided ownerId	200 Success	Return all accounts

POST /accounts

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
userId	Claims	Guid	Yes	-	Represent user who send this request
CustomerId	JsonBody	Guid	Yes	-	OwnerId of this account
initialBalance	JsonBody	decimal	No	0	initial balance of this account

API Behaviors

Role	Condition	Response	Note
Customer	Default	403 Forbidden
Teller or Admin	User is not exists	404 NotFound
	CustomerId is not in customer role	400 BadRequest	Cannot create account for non customer role
	InitialBalance less than 0	400 BadRequest	InitialBalance must greater than or equal to 0
	Default	201 Created

GET /accounts/{accountId}

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
userId	Claims	Guid	Yes	-	user who send this request
accountId	RouteParameter	Guid	Yes	-

API Behaviors

Role	Condition	Response
Customer	Account not exists	404 NotFound
	Account not owned by current user	403 Forbidden
	Default	200 Success
Teller or Admin	Account not exists	404 NotFound
Teller or Admin	Default	200 Success

GET /accounts/{accountId}/transactions

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
userId	Claims	Guid	Yes	-	user who send this request
accountId	RouteParameter	Guid	Yes	-
page	QueryParameter	int	No	1	Page number
pageSize	QueryParameter	int	No	20	Number of items per page

API Behaviors

Role	Condition	Response
Customer	Account not exists	404 NotFound
	Account not owned by current user	403 Forbidden
	Default	200 Success
Teller or Admin	Account not exists	404 NotFound
Teller or Admin	Default	200 Success

POST /accounts/{accountId}/deposit

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
accountId	RouteParameter	Guid	Yes	-	process account
userId	Claims	Guid	Yes	-	user who send this request
amount	JsonBody	decimal	Yes	-	deposit amount

API Behaviors

Role	Condition	Response
Customer	Default	403 Forbidden
Teller or Admin	Account not exists	404 NotFound
	Amount is less than or equal 0	400 BadRequest
	Account is frozen	403 Forbidden
	Default	200 Success

POST /accounts/{accountId}/withdraw

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
accountId	RouteParameter	Guid	Yes	-	process account
userId	Claims	Guid	Yes	-	user who send this request
amount	JsonBody	decimal	Yes	-	withdraw amount

API Behaviors

Role	Condition	Response
Customer	Default	403 Forbidden
Teller or Admin	Account not exists	404 NotFound
	Amount is less than or equal 0	400 BadRequest
	Account is frozen	403 Forbidden
	Default	200 Success

POST /withdrawal/{requestId}/confirm

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
requestId	RouteParameter	Guid	Yes	-	withdraw request id
userId	Claims	Guid	Yes	-	user who send this request
otp	JsonBody	string	Yes	-	one time password that sent to customer

API Behaviors

Role	Condition	Response
Customer	Default	403 Forbidden
Teller or Admin	Withdraw request not exists	404 NotFound
	Withdraw request is revocked	410 Gone
	Withdraw request is already process	409 Conflict
	Withdraw request has expired	410 Gone
	Retry attempts exceeded	403 Forbidden
	Provided mismatch OTP	400 BadRequest
	Account was not found	404 NotFound
	Account is frozen	403 Forbidden
	Insufficient fund	403 Forbidden
	Default	200 Success

POST /accounts/{sourceAccountId}/transfer

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
sourceAccountId	RouteParameter	Guid	Yes	-	The account from which funds will be transferred
userId	Claims	Guid	Yes	-	The user initiating the transfer
destinationAccountId	JsonBody	Guid	Yes	-	The account receiving the funds
amount	JsonBody	decimal	Yes	-	The amount of money to transfer

API Behaviors

Role	Condition	Response
Customer	source account or destination account is notfound	404 NotFound
	source account not belong to current user	403 Forbidden
	Insufficient fund	400 BadRequest
	source account or destination account is frozen	403 Forbidden
	Default	200 Success
Teller or Admin	Default	403 Forbidden

POST /accounts/{accountId}/freeze

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
accountId	RouteParameter	Guid	Yes	-	The account will be freeze
userId	Claims	Guid	Yes	-	The user who send this request

API Behaviors

Role	Condition	Response
Customer or Teller	Default	403 Forbidden
Admin	Account was not found	404 NotFound
	The account has already been frozen	409 Conflict
	Default	204 NoContent

POST /accounts/{accountId}/unfreeze

Request Parameters

Parameter	Source	Type	Required	Default	Desciption
accountId	RouteParameter	Guid	Yes	-	The account will be unfreeze
userId	Claims	Guid	Yes	-	The user who send this request

API Behaviors

Role	Condition	Response
Customer or Teller	Default	403 Forbidden
Admin	Account was not found	404 NotFound
	The account hasn't been frozen yet	409 Conflict
	Default	204 NoContent