Feloh-dotcom/mpesa-cloud-backend

# M-Pesa C2B Backend Integration with uniCenta POS ## Architecture Overview ``` Customer Phone → Till Number Payment ↓ Safaricom C2B API → HTTP POST (Confirmation) ↓ Spring Boot Backend → Save → MySQL ↓ Match Payment ↓ ↓ WebSocket Event → uniCenta POS ↓ Popup Update → Sale Completed ``` ## Project Structure ``` src/main/java/com/cloud/mpesa/ ├── MpesaBackendApplication.java # Spring Boot entry point ├── config/ │ └── SecurityConfig.java # Security configuration & CORS ├── controller/ │ ├── C2BConfirmationController.java # Main C2B payment endpoint │ ├── MpesaCallbackController.java # Legacy callback support │ └── HealthController.java # Health check endpoint ├── service/ │ ├── MpesaService.java # M-Pesa API integration │ └── PaymentService.java # Payment business logic ├── dto/ │ ├── C2BPaymentRequest.java # STK Push request DTO │ ├── C2BPaymentResponse.java # Response DTO │ ├── SafaricomCallbackRequest.java # Callback structure │ └── WebSocketNotification.java # WebSocket event DTO ├── entity/ │ └── PaymentEntity.java # Database entity (JPA) ├── model/ │ └── Payment.java # Payment model ├── repository/ │ └── PaymentRepository.java # Data access layer └── websocket/ ├── WebSocketConfig.java # WebSocket configuration └── PaymentWebSocketHandler.java # WebSocket message handler ``` ## Key Features Implemented ### 1. **C2B STK Push Initiation** (`/api/mpesa/c2b/initiate`) - Accept customer phone number, amount, and till number - Generate M-Pesa STK Push request - Customer receives prompt on phone to enter M-Pesa PIN - Request validated with Jakarta Validation ### 2. **Safaricom C2B Confirmation Callback** (`/api/mpesa/c2b/confirmation`) - Receives payment confirmation from Safaricom API - Extracts M-Pesa receipt number, phone, amount, date - Validates callback data integrity - Saves payment to My …