Bank Settlement System

A microservices-based financial transaction system that simulates how real-world payment networks process, capture, and settle payments.

Architecture Overview

flowchart TD
    A[Client / API Gateway] -->|HTTP/gRPC| B[Payment Service]
    B -->|ReserveFunds/Transfer| C[Accounts Service]
    B -->|PAYMENT_CAPTURED Event| D[Kafka Broker]
    D --> E[Settlement Service]
    E -->|Mark as PENDING → SETTLED| F[(Settlement DB)]
    C --> G[(Accounts DB)]
    B --> H[(Payments DB)]

Loading

Services Overview

Accounts Service

Handles account creation, balance management, and fund reservations (ReserveFunds and TransferFunds operations).

Payment Service

Handles CreatePaymentIntent and CapturePayment, integrates with Accounts Service, and emits Kafka events for settlements.

Settlement Service

Consumes PAYMENT_CAPTURED events, marks settlements as PENDING → SETTLED.

Payment Flow

sequenceDiagram
    participant C as Client
    participant P as Payment Service
    participant A as Accounts Service
    participant K as Kafka
    participant S as Settlement Service

    C->>P: CreatePaymentIntent
    P->>A: ReserveFunds (payer)
    A-->>P: Reserved
    C->>P: CapturePayment
    P->>A: TransferFunds (payer→payee)
    A-->>P: Success
    P-->>K: PAYMENT_CAPTURED Event
    K-->>S: Consume Event
    S->>S: Record Settlement (PENDING → SETTLED)

Loading

Key Non-Functional Features

• Built with Golang and Postgresql
• gRPC used for inter-service communication.
• Outbox Pattern–based event-driven communication over Kafka, enabling guaranteed asynchronous updates.
• Idempotency keys ensure repeat requests (like retries) do not duplicate transactions.
• Used Database transactions to ensure atomicity and consistency of financial operations.
• Compatible with container orchestration (Dockerized microservices).

Setup Instructions

git clone https://github.com/parasagrawal71/bank-settlement-system.git
cd bank-settlement-system
./start.sh
# To stop the servers: ./stop.sh

Folder Structure

bank-settlement-system/
│
├── services/
│   ├── accounts-service/
│   ├── payments-service/
│   └── settlement-service/
│
├── infra/
│   ├── kafka/
│   └── postgres/
│
└── shared/
    └── db/

API Usage Examples

Create accounts

grpcurl -plaintext -d '{"name":"Paras Agrawal","account_no":"10023","initial_balance":2000.50}' localhost:50051 accounts.AccountService/CreateAccount
grpcurl -plaintext -d '{"name":"Alice","account_no":"20012","initial_balance":1000}' localhost:50051 accounts.AccountService/CreateAccount

List accounts

grpcurl -plaintext -d '{}' localhost:50051 accounts.AccountService/ListAccounts

Create Payment Intent

grpcurl -plaintext -d '{"payer_id":"<payer_account_uuid>","payee_id":"<payee_account_uuid>","amount":100}' localhost:50052 payments.PaymentService/CreatePaymentIntent

Capture Payment

grpcurl -plaintext -d '{"reference_id": "<reference_id_from_response>"}' localhost:50052 payments.PaymentService/CapturePayment