Visa/Mastercard Global Payment Network.

# Real-Time Authorization Service
# Applies: Week 1 (Partitioning), Week 2 (Timeouts, Idempotency)

from dataclasses import dataclass
from typing import Optional
import asyncio
import time
from enum import Enum


class AuthDecision(Enum):
    APPROVED = "00"
    DECLINED_INSUFFICIENT_FUNDS = "51"
    DECLINED_EXPIRED_CARD = "54"
    DECLINED_FRAUD = "59"
    SYSTEM_ERROR = "96"
    ISSUER_UNAVAILABLE = "91"


@dataclass
class AuthorizationRequest:
    """ISO 8583-based authorization request."""
    message_type: str  # "0100" for auth request
    pan: str  # Primary Account Number (card number)
    amount: int  # In smallest currency unit (cents)
    currency_code: str  # "840" for USD
    merchant_id: str
    terminal_id: str
    mcc: str  # Merchant Category Code
    transaction_id: str  # Unique ID for idempotency
    timestamp: float


@dataclass
class AuthorizationResponse:
    """Authorization response with decision."""
    transaction_id: str
    decision: AuthDecision
    auth_code: Optional[str] = None
    risk_score: Optional[int] = None
    processing_time_ms: float = 0


class BINLookupService:
    """
    Ultra-fast BIN lookup using in-memory hash table.
    
    BIN (Bank Identification Number) is the first 6-8 digits of card.
    Used to route to correct issuing bank.
    
    Applies: Week 1, Day 1 - Hash partitioning for O(1) lookup
    """
    
    def __init__(self):
        # Pre-loaded hash map of BIN -> Issuer routing info
        # In production: the full BIN-range table, loaded at startup
        self._bin_table: dict[str, IssuerRoute] = {}
        self._load_bin_table()
    
    def _load_bin_table(self):
        """Load BIN table into memory at startup."""
        # Example: Load from database into memory
        # Real system has a very large number of entries
        pass
    
    def lookup(self, pan: str) -> Optional['IssuerRoute']:
        """
        O(1) lookup of issuer routing information.
        
        Takes < 1 microsecond with in-memory hash.
        """
        # Try 8-digit BIN first, then 6-digit
        bin_8 = pan[:8]
        bin_6 = pan[:6]
        
        return self._bin_table.get(bin_8) or self._bin_table.get(bin_6)


@dataclass
class IssuerRoute:
    """Routing information for an issuer."""
    issuer_id: str
    primary_endpoint: str
    backup_endpoint: str
    timeout_ms: int
    supports_standin: bool


class AuthorizationService:
    """
    Core authorization service achieving < 200ms latency.
    
    Key optimizations:
    1. WAL write overlapped with processing (not serialised)
    2. In-memory BIN lookup
    3. Replication/analytics persistence after response
    4. Pre-established connections to issuers
    
    Applies:
    - Week 1, Day 1: Partitioning (BIN-based routing)
    - Week 2, Day 1: Timeout management
    - Week 2, Day 2: Idempotency keys
    """
    
    def __init__(
        self,
        bin_service: BINLookupService,
        fraud_service: 'FraudDetectionService',
        issuer_gateway: 'IssuerGateway',
        standin_service: 'StandInService',
        wal: 'WriteAheadLog'
    ):
        self.bin_service = bin_service
        self.fraud_service = fraud_service
        self.issuer_gateway = issuer_gateway
        self.standin_service = standin_service
        self.wal = wal
        
        # Idempotency cache (Week 2, Day 2)
        self._idempotency_cache: dict[str, AuthorizationResponse] = {}
    
    async def authorize(
        self, 
        request: AuthorizationRequest
    ) -> AuthorizationResponse:
        """
        Process authorization request with strict latency SLA.
        
        Target: < 200ms for network processing portion.
        """
        start_time = time.monotonic()
        
        # Step 1: Check idempotency (< 0.1ms)
        # Prevents double-charging on retries
        cached = self._idempotency_cache.get(request.transaction_id)
        if cached:
            return cached
        
        # Step 2: Start the WAL write now so it overlaps BIN lookup,
        # fraud scoring and the issuer call; it is awaited before responding
        wal_future = asyncio.create_task(
            self.wal.append(request)
        )
        
        # Step 3: BIN lookup (< 0.001ms)
        route = self.bin_service.lookup(request.pan)
        if not route:
            return self._error_response(
                request, AuthDecision.SYSTEM_ERROR
            )
        
        # Step 4: Fraud scoring (< 1ms)
        # This happens in parallel with nothing else
        risk_score = await self.fraud_service.score(request)
        
        # Step 5: Route to issuer with timeout (variable, ~100-1000ms)
        try:
            response = await asyncio.wait_for(
                self.issuer_gateway.authorize(request, route, risk_score),
                timeout=route.timeout_ms / 1000.0
            )
        except asyncio.TimeoutError:
            # Issuer timeout - use stand-in processing
            if route.supports_standin:
                response = await self.standin_service.authorize(
                    request, risk_score
                )
            else:
                response = self._error_response(
                    request, AuthDecision.ISSUER_UNAVAILABLE
                )
        
        # Step 6: Calculate processing time
        processing_time = (time.monotonic() - start_time) * 1000
        response.processing_time_ms = processing_time
        
        # Step 7: Cache for idempotency (TTL: 24 hours)
        self._idempotency_cache[request.transaction_id] = response
        
        # Step 8: Ensure WAL write completed
        await wal_future
        
        return response
    
    def _error_response(
        self, 
        request: AuthorizationRequest,
        decision: AuthDecision
    ) -> AuthorizationResponse:
        return AuthorizationResponse(
            transaction_id=request.transaction_id,
            decision=decision
        )


class WriteAheadLog:
    """
    Write-ahead log for transaction durability.
    
    Applies: Week 1 - WAL for durability before processing.
    
    Key insight: the WAL write starts as soon as the request
    arrives and overlaps the rest of the processing, but the
    response is sent only after it completes, so a crash can
    never lose an authorization we have already answered.
    """
    
    async def append(self, request: AuthorizationRequest) -> None:
        """
        Append request to WAL.
        
        In production: Write to local SSD with group commit
        for batching multiple transactions per fsync.
        """
        # Serialize and write to durable storage
        pass


# =============================================================================
# Network Layer: ISO 8583 Message Handling
# =============================================================================

class ISO8583Parser:
    """
    High-performance ISO 8583 message parser.
    
    In production, this might be implemented in:
    - C++ for CPU optimization
    - FPGA for hardware acceleration
    - Specialized network appliances
    
    Key fields in ISO 8583:
    - Field 2: Primary Account Number (PAN)
    - Field 3: Processing Code
    - Field 4: Transaction Amount
    - Field 11: System Trace Audit Number
    - Field 37: Retrieval Reference Number
    - Field 39: Response Code
    """
    
    @staticmethod
    def parse(raw_message: bytes) -> AuthorizationRequest:
        """
        Parse ISO 8583 message to internal format.
        
        Real implementation handles:
        - Multiple MTI versions (1987, 1993, 2003)
        - Network-specific variations
        - BCD vs ASCII encoding
        - Variable-length fields
        """
        # Parse MTI (Message Type Indicator)
        # Parse bitmap to know which fields present
        # Parse each field according to spec
        pass
    
    @staticmethod
    def serialize(response: AuthorizationResponse) -> bytes:
        """Serialize response to ISO 8583 format."""
        pass

# Real-Time Fraud Detection Service
# Applies: Week 1 (Data partitioning for velocity), Week 2 (Timeouts)

import asyncio
import time
import numpy as np
from typing import Dict, List
import redis.asyncio as redis
from dataclasses import dataclass


@dataclass
class FraudFeatures:
    """500+ features extracted for fraud scoring."""
    
    # Transaction features (from request)
    amount: float
    currency: str
    mcc: str
    entry_mode: str
    card_present: bool
    
    # Velocity features (from Redis)
    txn_count_1h: int
    txn_count_24h: int
    amount_sum_1h: float
    amount_sum_24h: float
    unique_merchants_24h: int
    unique_countries_24h: int
    
    # Behavioral features (computed)
    time_since_last_txn_seconds: float
    distance_from_last_txn_km: float
    amount_deviation_from_avg: float
    
    # Risk indicators
    is_high_risk_mcc: bool
    is_high_risk_country: bool
    card_age_days: int
    
    def to_vector(self) -> np.ndarray:
        """Convert to feature vector for model input."""
        # One-hot encode categorical features
        # Normalize numerical features
        # Return as numpy array
        pass


class VelocityService:
    """
    Track card-level velocity using Redis.
    
    Applies: Week 1, Day 4 - Hot key handling
    
    Challenge: Popular cards (corporate cards) can be hot keys.
    Solution: Use Redis Cluster with card-hash-based sharding.
    """
    
    def __init__(self, redis_cluster: redis.RedisCluster):
        self.redis = redis_cluster
    
    async def get_velocity(self, pan_hash: str) -> Dict[str, any]:
        """
        Get velocity metrics for a card.
        
        Uses Redis sorted sets for time-windowed counting.
        All operations are O(log N) or better.
        """
        pipe = self.redis.pipeline()
        now = time.time()
        
        # Key structure: velocity:{pan_hash}:{metric}
        base_key = f"velocity:{pan_hash}"
        
        # Count transactions in last hour
        pipe.zcount(f"{base_key}:txns", now - 3600, now)
        
        # Count transactions in last 24 hours
        pipe.zcount(f"{base_key}:txns", now - 86400, now)
        
        # Amounts in last hour (member = "ts:amount", score = ts)
        pipe.zrangebyscore(
            f"{base_key}:amounts", 
            now - 3600, 
            now
        )
        
        # Unique merchants in last 24 hours
        pipe.zcount(f"{base_key}:merchants", now - 86400, now)
        
        # Last transaction location
        pipe.get(f"{base_key}:last_location")
        
        results = await pipe.execute()
        
        return {
            "txn_count_1h": results[0],
            "txn_count_24h": results[1],
            "amount_sum_1h": sum(float(m.split(":")[1]) for m in results[2]),
            "unique_merchants_24h": results[3],
            "last_location": results[4]
        }
    
    async def record_transaction(
        self, 
        pan_hash: str,
        amount: float,
        merchant_id: str,
        location: str
    ) -> None:
        """
        Record transaction for future velocity checks.
        
        Uses async fire-and-forget to not block auth response.
        """
        pipe = self.redis.pipeline()
        now = time.time()
        base_key = f"velocity:{pan_hash}"
        
        # Add to transaction count
        pipe.zadd(f"{base_key}:txns", {str(now): now})
        
        # Add amount (scored by time so windows and cleanup work)
        pipe.zadd(f"{base_key}:amounts", {f"{now}:{amount}": now})
        
        # Add merchant
        pipe.zadd(f"{base_key}:merchants", {merchant_id: now})
        
        # Update last location
        pipe.set(f"{base_key}:last_location", location)
        
        # Expire old data (48 hour window for cleanup)
        for key_suffix in ["txns", "amounts", "merchants"]:
            pipe.zremrangebyscore(
                f"{base_key}:{key_suffix}", 
                0, 
                now - 172800
            )
        
        await pipe.execute()


class FraudDetectionService:
    """
    Real-time fraud scoring in < 1ms.
    
    Applies:
    - Week 1, Day 4: Hot key handling for velocity
    - Week 2, Day 1: Strict timeout management
    
    Key optimizations:
    1. Pre-loaded model weights in memory
    2. Batch inference when possible
    3. Feature computation parallelized
    4. Redis cluster for velocity data
    """
    
    def __init__(
        self,
        velocity_service: VelocityService,
        model: 'FraudModel'
    ):
        self.velocity = velocity_service
        self.model = model
        
        # Pre-compute static risk indicators
        self._high_risk_mccs = self._load_high_risk_mccs()
        self._high_risk_countries = self._load_high_risk_countries()
    
    async def score(self, request: AuthorizationRequest) -> int:
        """
        Score transaction for fraud risk.
        
        Returns: Risk score 0-99
        
        Target latency: < 1ms
        """
        # Hash PAN for privacy and consistent sharding
        pan_hash = self._hash_pan(request.pan)
        
        # Get velocity features (Redis, < 0.3ms)
        velocity = await self.velocity.get_velocity(pan_hash)
        
        # Extract all features (< 0.2ms)
        features = self._extract_features(request, velocity)
        
        # Run model inference (< 0.5ms)
        score = self.model.predict(features.to_vector())
        
        # Fire-and-forget: Record this transaction for future velocity
        asyncio.create_task(
            self.velocity.record_transaction(
                pan_hash,
                request.amount,
                request.merchant_id,
                self._get_location(request)
            )
        )
        
        return int(score * 99)
    
    def _extract_features(
        self, 
        request: AuthorizationRequest,
        velocity: Dict
    ) -> FraudFeatures:
        """Extract features from request and velocity data."""
        
        # Compute geographic distance if we have last location
        distance_km = 0.0
        if velocity.get("last_location"):
            distance_km = self._calculate_distance(
                velocity["last_location"],
                self._get_location(request)
            )
        
        return FraudFeatures(
            amount=request.amount / 100.0,  # Convert cents to dollars
            currency=request.currency_code,
            mcc=request.mcc,
            entry_mode="chip",  # From request
            card_present=True,  # From request
            txn_count_1h=velocity.get("txn_count_1h", 0),
            txn_count_24h=velocity.get("txn_count_24h", 0),
            amount_sum_1h=velocity.get("amount_sum_1h", 0.0),
            amount_sum_24h=velocity.get("amount_sum_24h", 0.0),
            unique_merchants_24h=velocity.get("unique_merchants_24h", 0),
            unique_countries_24h=1,  # Computed from history
            time_since_last_txn_seconds=0.0,  # Computed
            distance_from_last_txn_km=distance_km,
            amount_deviation_from_avg=0.0,  # Computed
            is_high_risk_mcc=request.mcc in self._high_risk_mccs,
            is_high_risk_country=False,  # From merchant location
            card_age_days=365  # From card data
        )
    
    def _hash_pan(self, pan: str) -> str:
        """Hash PAN for privacy-preserving velocity lookup."""
        import hashlib
        return hashlib.sha256(pan.encode()).hexdigest()[:16]
    
    def _load_high_risk_mccs(self) -> set:
        """Load high-risk merchant category codes."""
        return {
            "5912",  # Drug stores
            "5944",  # Jewelry stores
            "5999",  # Misc retail
            "7995",  # Gambling
        }
    
    def _load_high_risk_countries(self) -> set:
        """Load high-risk countries."""
        return set()  # Configured per issuer


class FraudModel:
    """
    Pre-trained neural network for fraud scoring.
    
    In production:
    - Trained on billions of transactions
    - Updated weekly with new fraud patterns
    - A/B tested before deployment
    - Multiple model versions for different card types
    """
    
    def __init__(self, model_path: str):
        # Load pre-trained model weights
        # Could be TensorFlow, PyTorch, or ONNX
        self.weights = self._load_weights(model_path)
    
    def predict(self, features: np.ndarray) -> float:
        """
        Run inference on feature vector.
        
        Returns: Probability of fraud (0.0 to 1.0)
        
        In production, this might use:
        - TensorRT for GPU acceleration
        - ONNX Runtime for CPU optimization
        - Custom inference engine
        """
        # Simple neural network forward pass
        # Real implementation is much more sophisticated
        return 0.1  # Placeholder
    
    def _load_weights(self, path: str):
        """Load model weights from file."""
        pass

# Multi-Data-Center Routing and Failover
# Applies: Week 1, Day 2 - Replication Trade-offs

from dataclasses import dataclass
from typing import List, Optional
from enum import Enum
import asyncio


class DataCenterStatus(Enum):
    HEALTHY = "healthy"
    DEGRADED = "degraded"
    OFFLINE = "offline"


@dataclass
class DataCenter:
    """Data center configuration and health."""
    id: str
    region: str
    primary_for_regions: List[str]
    status: DataCenterStatus
    latency_ms: float
    capacity_pct: float


class GlobalRouter:
    """
    Route requests to optimal data center.
    
    Applies: Week 1, Day 2 - Replication and failover
    
    Routing priorities:
    1. Geographic proximity (latency)
    2. Data center health
    3. Load balancing
    4. Regulatory requirements (data residency)
    """
    
    def __init__(self):
        self.data_centers: Dict[str, DataCenter] = {}
        self._health_check_interval = 1.0  # seconds
    
    def select_data_center(
        self, 
        source_region: str,
        transaction_type: str
    ) -> DataCenter:
        """
        Select optimal data center for processing.
        
        Returns primary DC for region if healthy,
        otherwise fails over to backup.
        """
        # Get primary DC for this region
        primary = self._get_primary_for_region(source_region)
        
        if primary and primary.status == DataCenterStatus.HEALTHY:
            return primary
        
        # Primary unhealthy - find backup
        backup = self._get_backup_for_region(source_region)
        
        if backup and backup.status == DataCenterStatus.HEALTHY:
            return backup
        
        # All regional DCs down - use global fallback
        return self._get_any_healthy_dc()
    
    def _get_primary_for_region(self, region: str) -> Optional[DataCenter]:
        """Get primary DC for a region."""
        for dc in self.data_centers.values():
            if region in dc.primary_for_regions:
                return dc
        return None


class TransactionReplicator:
    """
    Replicate transactions across data centers.
    
    Applies: Week 1, Day 2 - Sync vs Async replication
    
    Strategy:
    - Authorization state: Sync within region (strong consistency)
    - Transaction log: Async across regions (eventual consistency)
    - WAL replication ensures no data loss on DC failure
    """
    
    def __init__(
        self,
        local_dc: str,
        peer_dcs: List[str]
    ):
        self.local_dc = local_dc
        self.peer_dcs = peer_dcs
    
    async def replicate_auth(
        self, 
        transaction: AuthorizationRequest,
        response: AuthorizationResponse
    ) -> None:
        """
        Replicate authorization to peer DCs.
        
        Sync replication to regional peer (for hot standby).
        Async replication to other regions (for DR).
        """
        # Sync replicate to regional peer
        regional_peer = self._get_regional_peer()
        if regional_peer:
            await self._sync_replicate(regional_peer, transaction, response)
        
        # Async replicate to other regions
        for dc in self.peer_dcs:
            if dc != regional_peer:
                asyncio.create_task(
                    self._async_replicate(dc, transaction, response)
                )
    
    async def _sync_replicate(
        self, 
        dc: str, 
        transaction: AuthorizationRequest,
        response: AuthorizationResponse
    ) -> None:
        """
        Synchronous replication - wait for acknowledgment.
        
        Used for regional failover capability.
        Timeout: 50ms (if peer is slow, continue anyway)
        """
        try:
            await asyncio.wait_for(
                self._send_to_dc(dc, transaction, response),
                timeout=0.05
            )
        except asyncio.TimeoutError:
            # Log but don't fail the auth
            # Regional peer will catch up from WAL
            pass
    
    async def _async_replicate(
        self, 
        dc: str,
        transaction: AuthorizationRequest, 
        response: AuthorizationResponse
    ) -> None:
        """
        Asynchronous replication - fire and forget.
        
        Used for cross-region disaster recovery.
        Will be caught up from WAL if this fails.
        """
        try:
            await self._send_to_dc(dc, transaction, response)
        except Exception as e:
            # Log error - cross-region replication will recover
            pass


class DataCenterFailover:
    """
    Handle data center failover scenarios.
    
    Applies: Week 2, Day 3 - Circuit breakers
    
    Failover scenarios:
    1. Network partition between DCs
    2. Complete DC outage
    3. Degraded performance (slow responses)
    """
    
    def __init__(self):
        self._dc_health: Dict[str, CircuitBreaker] = {}
    
    async def check_dc_health(self, dc_id: str) -> DataCenterStatus:
        """
        Check health of a data center.
        
        Uses circuit breaker pattern to avoid
        cascading failures.
        """
        breaker = self._dc_health.get(dc_id)
        
        if breaker and breaker.is_open:
            return DataCenterStatus.OFFLINE
        
        try:
            # Send health check
            latency = await self._ping_dc(dc_id)
            
            if latency > 100:  # ms
                return DataCenterStatus.DEGRADED
            
            return DataCenterStatus.HEALTHY
            
        except Exception:
            # Record failure
            if breaker:
                breaker.record_failure()
            return DataCenterStatus.OFFLINE

# Clearing and Settlement Service
# Applies: Week 3 (Messaging, Batch Processing)

from dataclasses import dataclass
from typing import List, Dict
from decimal import Decimal
from datetime import datetime, date
import asyncio


@dataclass
class ClearingRecord:
    """Clearing record submitted by acquirer."""
    transaction_id: str
    authorization_code: str
    pan_hash: str
    amount: Decimal
    currency: str
    merchant_id: str
    mcc: str
    acquirer_bin: str
    issuer_bin: str
    transaction_date: date
    clearing_date: date


@dataclass
class InterchangeFee:
    """Calculated interchange fee."""
    transaction_id: str
    rate: Decimal  # Percentage
    fixed_fee: Decimal  # Fixed amount
    total_fee: Decimal
    fee_category: str


@dataclass
class SettlementPosition:
    """Net settlement position for a bank."""
    bank_id: str
    net_amount: Decimal  # Positive = receives, Negative = pays
    transaction_count: int
    interchange_received: Decimal
    interchange_paid: Decimal


class ClearingService:
    """
    Process clearing files and prepare settlement.
    
    Applies: Week 3, Day 1 - Batch vs Stream processing
    
    This is primarily batch processing:
    - Runs daily after clearing cutoff
    - Processes millions of records
    - Must be idempotent (can re-run safely)
    """
    
    def __init__(
        self,
        interchange_calculator: 'InterchangeCalculator',
        settlement_service: 'SettlementService'
    ):
        self.interchange = interchange_calculator
        self.settlement = settlement_service
    
    async def process_clearing_batch(
        self, 
        clearing_records: List[ClearingRecord]
    ) -> List[SettlementPosition]:
        """
        Process a batch of clearing records.
        
        Steps:
        1. Validate each record against authorization
        2. Calculate interchange fees
        3. Net positions across all banks
        4. Generate settlement file
        """
        # Group by acquirer and issuer
        by_acquirer: Dict[str, List[ClearingRecord]] = {}
        by_issuer: Dict[str, List[ClearingRecord]] = {}
        
        for record in clearing_records:
            # Validate against authorization
            if not await self._validate_against_auth(record):
                continue
            
            # Calculate interchange
            fee = self.interchange.calculate(record)
            
            # Add to acquirer's batch
            if record.acquirer_bin not in by_acquirer:
                by_acquirer[record.acquirer_bin] = []
            by_acquirer[record.acquirer_bin].append(record)
            
            # Add to issuer's batch
            if record.issuer_bin not in by_issuer:
                by_issuer[record.issuer_bin] = []
            by_issuer[record.issuer_bin].append(record)
        
        # Calculate net positions
        positions = self._calculate_net_positions(
            by_acquirer, by_issuer
        )
        
        # Send to settlement
        await self.settlement.initiate_settlement(positions)
        
        return positions
    
    async def _validate_against_auth(
        self, 
        record: ClearingRecord
    ) -> bool:
        """
        Validate clearing record matches authorization.
        
        Checks:
        - Authorization exists
        - Amounts match (within tolerance)
        - Not already cleared
        - Within clearing window
        """
        # Look up original authorization
        # Compare amounts (allow small differences for tips)
        # Ensure not duplicate
        return True
    
    def _calculate_net_positions(
        self,
        by_acquirer: Dict[str, List[ClearingRecord]],
        by_issuer: Dict[str, List[ClearingRecord]]
    ) -> List[SettlementPosition]:
        """
        Calculate net settlement position for each bank.
        
        Issuers: pay the transaction amounts minus interchange
                 (they bill their cardholders for the full amount)
        Acquirers: receive the amounts minus interchange, then pay
                   their merchants (minus the acquirer's own fees)
        
        Net it all together so each bank has single debit/credit.
        """
        positions: Dict[str, SettlementPosition] = {}
        
        # Process acquirer side (they receive amount minus interchange)
        for acquirer_bin, records in by_acquirer.items():
            total_amount = sum(r.amount for r in records)
            total_interchange = sum(
                self.interchange.calculate(r).total_fee 
                for r in records
            )
            if acquirer_bin not in positions:
                positions[acquirer_bin] = SettlementPosition(
                    bank_id=acquirer_bin,
                    net_amount=Decimal(0),
                    transaction_count=0,
                    interchange_received=Decimal(0),
                    interchange_paid=Decimal(0)
                )
            positions[acquirer_bin].net_amount += (
                total_amount - total_interchange
            )
            positions[acquirer_bin].interchange_paid += total_interchange
            positions[acquirer_bin].transaction_count += len(records)
        
        # Process issuer side (they pay the transaction amounts)
        for issuer_bin, records in by_issuer.items():
            total_amount = sum(r.amount for r in records)
            total_interchange = sum(
                self.interchange.calculate(r).total_fee 
                for r in records
            )
            
            if issuer_bin not in positions:
                positions[issuer_bin] = SettlementPosition(
                    bank_id=issuer_bin,
                    net_amount=Decimal(0),
                    transaction_count=0,
                    interchange_received=Decimal(0),
                    interchange_paid=Decimal(0)
                )
            
            # Issuer pays: amount minus the interchange it keeps
            positions[issuer_bin].net_amount -= (
                total_amount - total_interchange
            )
            positions[issuer_bin].interchange_received += total_interchange
        
        return list(positions.values())


class InterchangeCalculator:
    """
    Calculate interchange fees based on transaction characteristics.
    
    Interchange varies by:
    - Card type (credit, debit, premium, corporate)
    - Merchant category code
    - Transaction type (card present, CNP, recurring)
    - Geographic factors
    """
    
    def __init__(self):
        # Load interchange rate tables
        # Visa and Mastercard publish these twice yearly
        self._rate_tables = self._load_rate_tables()
    
    def calculate(self, record: ClearingRecord) -> InterchangeFee:
        """Calculate interchange fee for a transaction."""
        
        # Look up rate based on characteristics
        rate_info = self._lookup_rate(
            card_type=self._get_card_type(record.pan_hash),
            mcc=record.mcc,
            card_present=True,  # Derived from clearing data
            transaction_type="purchase"
        )
        
        # Calculate fee
        percentage_fee = record.amount * rate_info["rate"]
        fixed_fee = Decimal(rate_info["fixed"])
        total = percentage_fee + fixed_fee
        
        return InterchangeFee(
            transaction_id=record.transaction_id,
            rate=rate_info["rate"],
            fixed_fee=fixed_fee,
            total_fee=total,
            fee_category=rate_info["category"]
        )
    
    def _lookup_rate(
        self,
        card_type: str,
        mcc: str,
        card_present: bool,
        transaction_type: str
    ) -> Dict:
        """Look up interchange rate from tables."""
        # Complex logic based on Visa/Mastercard published rates
        # Example rates:
        return {
            "rate": Decimal("0.0185"),  # 1.85%
            "fixed": Decimal("0.10"),   # 10 cents
            "category": "standard_credit_purchase"
        }
    
    def _load_rate_tables(self) -> Dict:
        """Load interchange rate tables."""
        # Published by Visa and Mastercard
        return {}


class SettlementService:
    """
    Execute settlement between banks.
    
    Settlement happens via:
    - Fedwire (US domestic)
    - SWIFT (International)
    - Central bank systems
    """
    
    async def initiate_settlement(
        self, 
        positions: List[SettlementPosition]
    ) -> None:
        """
        Initiate settlement transfers.
        
        Process:
        1. Send debit instructions to banks that owe
        2. Wait for funds to arrive in clearing account
        3. Send credit instructions to banks that receive
        """
        # Banks that owe (negative position)
        debits = [p for p in positions if p.net_amount < 0]
        
        # Banks that receive (positive position)
        credits = [p for p in positions if p.net_amount > 0]
        
        # Request debits first
        for position in debits:
            await self._request_debit(
                position.bank_id, 
                abs(position.net_amount)
            )
        
        # Wait for funds to arrive (usually within hour)
        await self._wait_for_funds()
        
        # Send credits
        for position in credits:
            await self._send_credit(
                position.bank_id,
                position.net_amount
            )
    
    async def _request_debit(
        self, 
        bank_id: str, 
        amount: Decimal
    ) -> None:
        """Request debit from bank via Fedwire."""
        # Send Fedwire 1031 drawdown request
        pass
    
    async def _send_credit(
        self, 
        bank_id: str,
        amount: Decimal
    ) -> None:
        """Send credit to bank via Fedwire."""
        # Send Fedwire funds transfer
        pass