PayLens - A lens into every step of a card transaction

🧠 Overview

Deep Transaction Simulator is a production-quality educational system designed to simulate the complete lifecycle of a credit card transaction — from card input to issuer decision — with full transparency into data structures, message formats, and transformation layers.

Unlike typical demos, this system prioritizes:

Conceptual correctness over superficial visuals
Deterministic execution over randomness
Inspectability at every stage of the transaction

This is not a mock UI — it is a transaction debugger for payment systems.

🎯 Objective

To build a system that explains, step-by-step, what actually happens during a credit card transaction, including:

Data structuring (PAN, EMV)
Message construction (ISO 8583)
Encryption transformations
Network routing simulation
Issuer-side decision logic

🧠 Core Philosophy

Depth over scale → Simulate one transaction extremely well
Deterministic and reproducible → Same input → same output
No external APIs → Fully self-contained system
Explainability-first design → Every step is inspectable
Separation of computation and visualization

⚙️ Architecture

🔷 Single Runtime Architecture

This project uses a unified TypeScript fullstack architecture, meaning:

No backend/frontend separation
No network calls between layers
Entire simulation runs in-memory
UI directly interacts with the simulation engine

React UI
   ↓
Simulation Engine (Pure Functions)
   ↓
State + Event Logs

🧩 Core Layers

1. UI Layer (React)

Visualization of transaction flow
Inspectors for ISO fields, TLV data, encryption
Playback controls (step, play, reset)

2. Simulation Engine (Core Logic)

State machine (transaction lifecycle)
ISO 8583 message builder
EMV TLV generator/parser
Encryption simulator
Network routing simulation
Issuer decision engine

3. Data Models Layer

Strongly typed structures for:
- ISO messages
- TLV data
- Transaction state
- Event logs

🚀 Tech Stack

Core

TypeScript — unified language across system
React (Vite) — fast frontend runtime
Zustand — lightweight state management

Visualization

React Flow — network graph simulation
Custom components / D3 (optional) — data visualizations

Runtime

Fully client-side (can be deployed as static app)
Optional: Node runtime (for CLI simulation)

🔁 Transaction Flow

Card Input
→ Data Structuring
→ ISO Message Construction
→ Encryption Layer
→ Network Routing (Terminal → Acquirer → Network → Issuer)
→ Issuer Decision
→ Response Propagation

🧩 Core Functional Components

🟦 1. Card Data Layer

Simulates realistic card input:

PAN (generated using Luhn algorithm)
Expiry date
CVV
Optional cardholder data

🟨 2. EMV TLV Layer

Implements Tag-Length-Value (TLV) format used in chip transactions.

Example Structure

Tag: 9F26
Length: 08
Value: A1B2C3D4E5F6A7B8

Supports:

Nested TLV structures
Decoding and visualization
Field-level inspection

🟦 3. ISO 8583 Message Layer

Constructs structured transaction messages.

Key Fields

MTI: 0100 (Authorization Request)
Field 2: PAN
Field 4: Amount
Field 7: Transmission Time
Field 11: STAN
Field 41: Terminal ID
Field 55: EMV TLV data

Important Design Choice

ISO messages are stored as:

Structured objects (not raw strings)
Serialized only when needed

🔐 4. Encryption Layer (Simulated)

Philosophy

The goal is to teach encryption, not implement production-grade cryptography.

Transformation Flow

Raw Data → Pseudo Encryption → Transport Wrapping

Implementation Strategy

Lightweight deterministic transformation (XOR-based + encoding)
Visual representation of:
- Data obfuscation
- Block transformations
Optional advanced view:
- AES concepts (SubBytes, ShiftRows, etc.)

Example

pseudoEncrypt(data) → encoded string

Key Insight

Encryption is shown as:

A data transformation step
Not a security system

🌐 5. Network Simulation Layer

Models the payment ecosystem:

Terminal
Acquirer
Network
Issuer

Behavior

Each node:
- Receives message
- Logs state
- Forwards message
Full routing path is tracked

Key Design Principle

Network latency is simulated in UI — not in computation

🧠 6. Issuer Decision Engine

A rule-based system that evaluates transactions.

Example Rules

Balance validation
CVV match
Basic fraud detection

Output

APPROVED
or
DECLINED (with reasons)

Design

Fully deterministic
Explainable decision output
Rule-level visibility

🔁 State Machine (Core Engine)

The system is driven by an explicit state machine.

States

INIT
→ CARD_CAPTURED
→ DATA_STRUCTURED
→ ISO_BUILT
→ ENCRYPTED
→ ROUTED
→ AUTHORIZED
→ COMPLETED

Key Properties

Pure function transitions
No hidden side effects
Fully replayable

Transition Model

nextState = transition(currentState)

📊 Data Models

ISO Message

type ISOMessage = {
  mti: string;
  bitmap: string;
  fields: {
    2?: string;
    4?: number;
    7?: string;
    11?: string;
    41?: string;
    55?: TLVData;
  };
};

TLV Structure

type TLV = {
  tag: string;
  length: number;
  value: string | TLV[];
};

Transaction State

type TransactionState = {
  id: string;
  currentStep: Step;
  history: StepLog[];

  rawCardData: CardData;
  isoMessage?: ISOMessage;
  encryptedPayload?: string;

  routingPath: Node[];
  decision?: IssuerDecision;
};

Event Log (Critical Component)

type StepLog = {
  step: string;
  timestamp: number;
  input: any;
  output: any;
  explanation: string;
};

🎨 UI/UX Design

Main Layout

Playback Controls (Play / Step / Reset)
Network Flow Visualization
Step Timeline
Data Inspector Panel

Core UI Components

🔹 Flow Visualization

Animated movement across nodes
Real-time state updates

🔹 ISO Inspector

Expandable fields
Human-readable formatting

🔹 TLV Decoder

Nested structure visualization
Tag-level inspection

🔹 Encryption View

Raw vs encrypted comparison
Step-by-step transformation

⚡ Performance Strategy

1. No Network Overhead

All operations are in-memory.

2. Pure Functions

Simulation logic is synchronous and deterministic.

3. UI-Driven Timing

No delays in engine
Animations handled by UI layer

4. Efficient State Updates

Zustand store slices
Avoid deep re-renders

5. Optional Optimization

Web Workers for heavy computation (if needed)

🔒 Constraints

No real card data
No payment gateway integration
No real encryption protocols
Fully simulated environment

🎓 Learning Outcomes

Users will understand:

Structure of ISO 8583 messages
EMV TLV data encoding
Where encryption occurs in payment flows
Roles of:
- Terminal
- Acquirer
- Network
- Issuer
Decision-making logic in transaction authorization

⚠️ Design Principles (Strict)

Do not treat ISO as raw strings
Do not hide intermediate states
Do not mix UI with business logic
Do not simulate unnecessary real-world complexity
Always log transformations

🚀 Final Vision

This system is not just a simulator.

It is:

A deterministic, inspectable transaction engine that makes invisible payment flows visible.

If built correctly, it becomes:

A teaching tool
A debugging framework
A conceptual reference for fintech systems

🧭 Future Extensions

Transaction replay system
Side-by-side comparison
Fraud scenario simulations
Latency toggles
Multi-transaction batching

🏁 Summary

Deep Transaction Simulator is designed to bridge the gap between:

“I know payments exist” and “I understand exactly how they work internally.”

Name		Name	Last commit message	Last commit date
docs		docs
public		public
scripts		scripts
src		src
.gitignore		.gitignore
Readme.md		Readme.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation