# ISO8583 TCP/IP Message Sender - User Guide

This module provides comprehensive ISO8583 message creation and TCP/IP sending capabilities with both jPOS and custom implementations.

## 🚀 Quick Start

### 1. Run with Network Disabled (Default)
```bash
.\gradlew.bat :message-tester:run
```
This creates and displays ISO8583 messages without sending them over the network.

### 2. Enable TCP Sending
To actually send messages over TCP/IP:

1. Edit `NetworkConfig.java`
2. Set `ENABLE_NETWORK = true`
3. Configure your server details:
   ```java
   public static final String SERVER_IP = "your.server.com";
   public static final int SERVER_PORT = 8583;
   ```

### 3. Test with Mock Server
Start the mock payment server for testing:
```bash
# Terminal 1 - Start mock server
.\gradlew.bat :message-tester:run --args="com.morefun.tester.MockPaymentServer"

# Terminal 2 - Enable local testing
# Edit NetworkConfig.java:
# SERVER_IP = "localhost"
# ENABLE_NETWORK = true

# Then run the client
.\gradlew.bat :message-tester:run
```

## 🔧 Configuration Options

### NetworkConfig.java Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `ENABLE_NETWORK` | `false` | Enable actual TCP sending |
| `SERVER_IP` | `"demo.ctrmv.com"` | Target server IP |
| `SERVER_PORT` | `8583` | Target server port |
| `USE_SSL` | `false` | Enable SSL/TLS encryption |
| `CONNECTION_TIMEOUT` | `30000` | Connection timeout (ms) |
| `SHOW_RAW_MESSAGES` | `true` | Display hex dumps |
| `SIMULATE_RESPONSES` | `true` | Simulate responses on network failure |

### Advanced Settings
```java
// Backup server configuration
public static final String BACKUP_IP = "192.168.1.100";
public static final boolean ENABLE_BACKUP = false;

// Protocol settings
public static final String TPDU_HEADER = "6000782000";
public static final boolean USE_TPDU = true;

// SSL/TLS settings
public static final boolean USE_SSL = false;
```

## 📨 Message Types Supported

### Sale Transaction (MTI: 0200)
- **Purpose**: Process a sale/purchase transaction
- **Response**: 0210 (Sale Response)
- **Fields**: PAN, Amount, STAN, Terminal ID, Merchant ID, etc.

### Reversal Transaction (MTI: 0400)
- **Purpose**: Reverse a previous transaction
- **Response**: 0410 (Reversal Response)  
- **Fields**: Same as original transaction

## 🔍 Implementation Details

### jPOS Implementation
- Uses industry-standard jPOS library
- NACChannel for TCP communication
- ISO87B message packager
- Proper field handling and validation

### Simple Implementation
- Custom ISO8583 message builder
- Raw TCP socket communication
- Simplified field structure
- Educational/learning purpose

## 🧪 Testing Features

### 1. Connection Testing
```java
SimpleTCPClient.testConnection(host, port, timeout)
```

### 2. Message Debugging
- Hex dump display
- Field-by-field breakdown
- Raw message inspection

### 3. Error Simulation
- Network failure handling
- Response timeout testing
- Backup server fallback

### 4. Mock Server
- Simulates payment processor
- Handles multiple connections
- Generates realistic responses

## 🛡️ Security Considerations

### For Production Use:
1. **Enable SSL/TLS**: Set `USE_SSL = true`
2. **Certificate Validation**: Implement proper cert checking
3. **Message Encryption**: Add field-level encryption if required
4. **Authentication**: Implement proper authentication mechanisms
5. **Logging**: Add secure logging (mask sensitive data)

### Test Data:
- Default test card: `4111111111111111` (Visa test number)
- Test amounts: $15.00 (1500 cents)
- All test data is safe for development

## 📋 Common Use Cases

### 1. Development Testing
```java
// NetworkConfig.java
ENABLE_NETWORK = false;
SIMULATE_RESPONSES = true;
```

### 2. Integration Testing with Mock Server
```bash
# Start mock server
java -cp build/libs/message-tester.jar com.morefun.tester.MockPaymentServer 8583
```

### 3. Production Integration
```java
// NetworkConfig.java
ENABLE_NETWORK = true;
SERVER_IP = "production.processor.com";
USE_SSL = true;
SHOW_RAW_MESSAGES = false; // Security
```

## 🔧 Troubleshooting

### Connection Issues
1. Check firewall settings
2. Verify server IP and port
3. Test with telnet: `telnet server.com 8583`
4. Enable backup server if available

### Message Format Issues
1. Enable `SHOW_RAW_MESSAGES = true`
2. Compare with expected format
3. Check field lengths and padding
4. Validate TPDU headers

### SSL/TLS Issues
1. Check certificate validity
2. Verify SSL protocol version
3. Check cipher suites
4. Test with SSL disabled first

## 📚 Learning Resources

### Understanding ISO8583
- Field definitions and usage
- Message flow patterns
- Error handling procedures

### jPOS Documentation
- Official jPOS documentation
- Community examples and patterns
- Advanced configuration options

## 🎯 Next Steps

### Enhancements You Can Add:
1. **More Transaction Types**: Auth, Capture, Refund
2. **Enhanced Security**: Field encryption, MAC validation
3. **Database Integration**: Transaction logging and storage
4. **Load Testing**: Multi-threaded message sending
5. **Configuration UI**: Web interface for settings

### Real-World Integration:
1. Replace test data with real merchant information
2. Implement proper error handling and retry logic
3. Add transaction state management
4. Integrate with payment gateway APIs
5. Add monitoring and alerting

---

💡 **Tip**: Start with network disabled to understand message structure, then enable networking for actual testing.

🔒 **Security**: Never use test card numbers in production environments.

📞 **Support**: Check the codebase comments and method documentation for detailed usage examples.