# Payment Processing System

A complete sample implementation of a real-time payment processing system using AtomIngest for credit card transaction ingestion with fraud detection and PCI compliance.

## Overview

This sample demonstrates:
- **Real-time processing**: Sub-100ms transaction validation
- **Fraud detection**: Real-time scoring and velocity checks
- **PCI compliance**: Card data tokenization and encryption
- **Risk management**: Transaction limits and merchant validation
- **Audit trails**: Complete transaction history for compliance

## Architecture

```
Credit Card         AtomIngest           Database
Transaction    →    Pipeline        →    PostgreSQL
                         ↓
                   Fraud Engine
                         ↓
                   Risk Assessment
```

## Features

### Security & Compliance
- ✅ PCI-DSS Level 1 compliant card data handling
- ✅ AES-256 encryption for sensitive data
- ✅ Card number tokenization
- ✅ Immutable audit trails
- ✅ Field-level access controls

### Fraud Detection
- ✅ Real-time velocity checks
- ✅ Merchant validation
- ✅ Geographic anomaly detection
- ✅ Pattern-based risk scoring
- ✅ Machine learning integration ready

### Performance
- ✅ Sub-100ms processing latency
- ✅ 10,000+ TPS throughput capability
- ✅ Horizontal scaling support
- ✅ Connection pooling
- ✅ Optimized batch processing

## Quick Start

### Prerequisites

```bash
# Python 3.12+
python --version

# Required packages
pip install -r requirements.txt

# PostgreSQL database (or SQLite for development)
createdb payment_processing
```

### Setup Database

```bash
# Run schema creation
psql payment_processing < schema.sql

# Verify tables created
psql payment_processing -c "\\dt"
```

### Run Sample Data

```bash
# Process sample transactions
atomingest run pipeline.yaml --input sample_data/transactions.csv

# Check results
psql payment_processing -c "SELECT COUNT(*) FROM transactions;"
```

## Configuration Files

### Pipeline Configuration (`pipeline.yaml`)

The main pipeline configuration with real-time processing, security, and fraud detection.

### Schema Definition (`schema.yaml`)

Complete data model including:
- Transaction details
- Security classifications
- Validation rules
- Business constraints

### Fraud Rules (`fraud_rules.yaml`)

Configurable fraud detection rules:
- Velocity checks
- Amount limits
- Geographic restrictions
- Merchant validation

## Sample Data

### `transactions.csv`
Realistic transaction data including:
- Normal transactions
- High-risk scenarios
- Edge cases
- Invalid data for testing

### `merchants.csv`
Merchant master data for validation

### `fraud_scenarios.csv`
Known fraud patterns for testing detection

## Testing

### Unit Tests
```bash
# Run all tests
pytest tests/

# Run specific test categories
pytest tests/test_fraud_detection.py -v
pytest tests/test_compliance.py -v
```

### Performance Tests
```bash
# Load testing
pytest tests/test_performance.py --benchmark

# Stress testing
python tests/stress_test.py --tps 10000 --duration 60
```

### Compliance Tests
```bash
# PCI compliance validation
pytest tests/test_pci_compliance.py -v

# Audit trail verification
pytest tests/test_audit.py -v
```

## Monitoring & Alerting

### Key Metrics
- Transaction processing rate (TPS)
- Average processing latency
- Fraud detection rate
- System error rate
- Database performance

### Alerts
- High fraud score transactions
- Processing latency > 100ms
- Failed transaction rate > 1%
- Database connection issues
- Security violations

## Deployment

### Development
```bash
# Local development setup
docker-compose up -d postgres
# Note: Redis integration planned for future versions
python -m atomingest.cli run pipeline.yaml --watch
```

### Production
```bash
# Kubernetes deployment
kubectl apply -f k8s/
```

### Environment Variables
```bash
# Database connection
export DB_HOST="postgres.internal"
export DB_PASSWORD="secure_password"

# Security
export ENCRYPTION_KEY="your_encryption_key"
export JWT_SECRET="jwt_signing_secret"

# External services
export FRAUD_SERVICE_URL="https://fraud-api.company.com"
export KMS_KEY_ID="arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
```

## Customization

### Adding New Fraud Rules

1. Edit `fraud_rules.yaml`:
```yaml
custom_rules:
  - name: "high_value_weekend"
    condition: "amount > 5000 AND weekend = true"
    risk_score: 0.8
    action: "flag_for_review"
```

2. Implement rule logic in `hooks/fraud_detection.py`

### Custom Validation

Add business-specific validation in `hooks/custom_validation.py`:

```python
def validate_merchant_category(transaction):
    """Custom merchant category validation"""
    mcc = transaction.get('merchant_category_code')
    restricted_mccs = ['6010', '6011']  # Money transfer

    if mcc in restricted_mccs:
        return ValidationResult(
            valid=False,
            error="Restricted merchant category",
            risk_score=0.9
        )

    return ValidationResult(valid=True)
```

## Troubleshooting

### Common Issues

**High Latency**
```bash
# Check database connections
EXPLAIN ANALYZE SELECT * FROM transactions WHERE timestamp > NOW() - INTERVAL '1 hour';

# Monitor connection pool
SELECT * FROM pg_stat_activity;
```

**Fraud False Positives**
```bash
# Review fraud rules effectiveness
SELECT rule_name, COUNT(*), AVG(risk_score)
FROM fraud_scores
GROUP BY rule_name;
```

**Data Quality Issues**
```bash
# Check validation failures
SELECT error_type, COUNT(*)
FROM validation_errors
WHERE created_at > NOW() - INTERVAL '1 day'
GROUP BY error_type;
```

## Security Considerations

### Card Data Protection
- Never log full card numbers
- Use tokenization for all storage
- Implement secure key management
- Regular key rotation

### Access Controls
- Role-based access to sensitive data
- API authentication and authorization
- Audit all data access
- Network security (VPC, encryption in transit)

### Compliance
- Regular PCI compliance scans
- Penetration testing
- Security awareness training
- Incident response procedures

## Support

For questions or issues:
1. Check the troubleshooting section
2. Review test cases for examples
3. Consult the [Fintech User Guide](../../docs/fintech_user_guide.md)
4. Open a GitHub issue with [payment-processing] tag
