Overview
The Trips service is the heart of the Masar Eagle platform, handling all trip-related operations including on-demand bookings, company bookings, public trips, payments, wallet management, and reviews. It integrates with Moyasar for payment processing and uses Hangfire for background jobs.Trips service location:
src/services/Trips/Trips.Api/Program.csCore Responsibilities
- Trip Management: Create, track, start, complete, and cancel trips
- Booking System: Handle passenger bookings, driver assignments, and booking lifecycle
- Payment Processing: Integrate with Moyasar for credit card and Apple Pay payments
- Wallet Operations: Manage driver, passenger, and company wallet balances and transactions
- Reviews & Ratings: Collect and manage driver, passenger, and company reviews
- Public Trips: Shared ride functionality for company-operated routes
- Company Bookings: Corporate trip management for business clients
- Bank Transfers: Handle withdrawal requests and bank account management
- Statistics & Reports: Generate financial summaries and trip statistics
- Background Jobs: Trip reminders, auto-cancellation, and notifications
Technology Stack
- ASP.NET Core Minimal APIs: High-performance endpoint definitions
- MediatR: CQRS pattern for commands and queries
- Entity Framework Core: Database access
- PostgreSQL: Primary database
- Hangfire: Background job scheduling and processing
- Wolverine: Message bus for inter-service communication
- RabbitMQ: Event distribution
- Moyasar SDK: Payment gateway integration
- FluentValidation: Request validation
- Response Compression: Brotli and Gzip
Program.cs Configuration
Program.cs
API Endpoints Overview
Trip Endpoints
Driver Trips
Driver Trips
GET /api/drivers/{driverId}/trips- List driver’s tripsGET /api/drivers/{driverId}/trips/{tripId}- Get trip detailsPOST /api/drivers/{driverId}/trips- Create new tripPUT /api/drivers/{driverId}/trips/{tripId}/start- Start tripPUT /api/drivers/{driverId}/trips/{tripId}/complete- Complete tripPUT /api/drivers/{driverId}/trips/{tripId}/cancel- Cancel trip
Passenger Trips
Passenger Trips
GET /api/passengers/{passengerId}/trips- List passenger’s tripsGET /api/passengers/{passengerId}/trips/{tripId}- Get trip details
Company Trips
Company Trips
GET /api/companies/{companyId}/trips- List company tripsGET /api/companies/{companyId}/trips/{tripId}- Trip detailsGET /api/companies/{companyId}/trips/{tripId}/ledger- Financial ledgerGET /api/trips/companies/{companyId}/trips- Alternative endpoint
Admin Trip Management
Admin Trip Management
GET /api/admin/trips- List all tripsGET /api/admin/trips/{tripId}- Get trip detailsGET /api/admin/trips/{tripId}/ledger- View trip ledgerGET /api/admin/trips/{tripId}/requests- View booking requestsPOST /api/admin/trips/{tripId}/requests/{requestId}/accept- Accept requestPOST /api/admin/trips/{tripId}/requests/{requestId}/reject- Reject requestPOST /api/admin/trips/{tripId}/cancel- Cancel tripGET /api/admin/trips/cancellations- List cancellations
Trip Replacement
Trip Replacement
GET /api/admin/trips/{tripId}/replacement-options- Get replacement optionsGET /api/admin/trips/{tripId}/available-drivers- List available driversPOST /api/admin/trips/{tripId}/replace-with-trip- Replace with another tripPOST /api/admin/trips/{tripId}/replace-with-driver- Assign different driver
Search & Discovery
Search & Discovery
GET /api/trips/search/unified- Unified search for tripsGET /api/company-trips/search- Search company trips
Booking Endpoints
Passenger Bookings
Passenger Bookings
POST /api/bookings- Create bookingGET /api/bookings/{bookingId}- Get booking detailsPOST /api/bookings/{bookingId}/cancel- Cancel bookingPOST /api/bookings/{bookingId}/verify-payment- Verify Moyasar paymentGET /api/drivers/{driverId}/bookings- List driver bookings
Company Bookings
Company Bookings
POST /api/company-bookings- Create company bookingGET /api/companies/{companyId}/bookings- List company bookingsPOST /api/companies/{companyId}/bookings/{bookingId}/cancel- CancelPOST /api/company-bookings/{bookingId}/unassign-driver- Unassign driverPOST /api/company-bookings/{bookingId}/unassign-vehicle- Unassign vehiclePOST /api/drivers/{driverId}/company-bookings/{bookingId}/start- StartPOST /api/drivers/{driverId}/company-bookings/{bookingId}/complete- Complete
Public Trip Bookings
Public Trip Bookings
POST /api/public-trips/{tripId}/book- Book seat on public tripGET /api/public-trips/{tripId}- Get public trip detailsGET /api/passengers/{passengerId}/public-trip-bookings- List bookingsPOST /api/passengers/{passengerId}/public-trip-bookings/{bookingId}/cancel- CancelPOST /api/company-public-trips/bookings/{bookingId}/verify-payment- Verify payment
Wallet Endpoints
Driver Wallets
Driver Wallets
GET /api/drivers/{driverId}/wallet- Get wallet balanceGET /api/drivers/{driverId}/wallet/exists- Check if wallet existsGET /api/drivers/{driverId}/wallet/transactions- Transaction historyGET /api/drivers/{driverId}/wallets- Multi-currency walletsPOST /api/admin/drivers/{driverId}/wallet/deposit- Admin depositPOST /api/admin/drivers/{driverId}/wallet/withdraw- Admin withdrawalGET /api/admin/wallets/drivers- List all driver wallets
Passenger Wallets
Passenger Wallets
GET /api/passengers/{passengerId}/wallet- Get wallet balanceGET /api/passengers/{passengerId}/wallet/exists- Check if wallet existsGET /api/passengers/{passengerId}/wallet/transactions- Transaction historyGET /api/passengers/{passengerId}/wallets- Multi-currency walletsPOST /api/admin/passengers/{passengerId}/wallet/deposit- Admin depositGET /api/admin/wallets/passengers- List all passenger wallets
Company Wallets
Company Wallets
GET /api/trips/companies/{companyId}/wallets- List company walletsGET /api/trips/companies/{companyId}/wallet/{currency}- Get wallet by currencyGET /api/trips/companies/{companyId}/wallet/{currency}/transactions- TransactionsPOST /api/admin/companies/{companyId}/wallet/deposit- Admin depositPOST /api/admin/companies/{companyId}/wallet/withdraw- Admin withdrawalGET /api/admin/wallets/companies- List all company wallets
Wallet Top-Up
Wallet Top-Up
POST /api/wallet/top-up/bank-transfer- Request top-up via bank transferPOST /api/wallets/topup/verify- Verify Moyasar payment for top-upPOST /api/admin/wallet-top-up/{transferId}/approve- Approve transferPOST /api/admin/wallet-top-up/{transferId}/reject- Reject transfer
Payment & Bank Transfer Endpoints
Bank Accounts
Bank Accounts
GET /api/bank-accounts- Public list of bank accounts for depositsGET /api/admin/bank-accounts- Admin view of bank accountsPOST /api/admin/bank-accounts- Add bank accountPUT /api/admin/bank-accounts/{id}- Update bank accountDELETE /api/admin/bank-accounts/{id}- Remove bank accountGET /api/companies/{companyId}/bank-accounts- Company bank accounts
Bank Transfers
Bank Transfers
GET /api/admin/bank-transfers/pending- Pending transfer requestsPOST /api/admin/bank-transfers/{transferId}/approve- Approve transferPOST /api/admin/bank-transfers/{transferId}/reject- Reject transferPOST /api/admin/bank-transfers/{transferId}/convert-to-cash- Convert to cash
Review Endpoints
Driver Reviews
Driver Reviews
POST /api/trips/{tripId}/driver-review- Submit driver reviewGET /api/drivers/{driverId}/reviews- List driver reviewsGET /api/drivers/reviews/{reviewId}- Get review detailsGET /api/admin/driver-reviews- Admin view of driver reviews
Passenger Reviews
Passenger Reviews
POST /api/trips/{tripId}/passenger-review- Submit passenger reviewGET /api/passengers/{passengerId}/reviews- List passenger reviewsGET /api/passengers/reviews/{reviewId}- Get review detailsGET /api/admin/passenger-reviews- Admin view of passenger reviews
Company Reviews
Company Reviews
POST /api/trips/{tripId}/company-review- Submit company reviewGET /api/companies/{companyId}/reviews- List company reviewsGET /api/companies/reviews/{reviewId}- Get review details
Statistics & Reports
Dashboard
Dashboard
GET /api/admin/dashboard/financial-summary- Financial overviewGET /api/companies/{companyId}/dashboard- Company dashboard
Statistics
Statistics
GET /api/admin/statistics/trips- Trip statisticsGET /api/admin/statistics/revenue- Revenue statisticsGET /api/admin/statistics/users- User statistics
Reports
Reports
GET /api/admin/reports/trips- Trip reportsGET /api/admin/reports/financial- Financial reportsGET /api/companies/{companyId}/reports- Company-specific reports
Usage Tracking
Usage Tracking
GET /api/vehicle-usage- Vehicle usage statisticsGET /api/user-usage- User activity tracking
Payment Integration (Moyasar)
The service integrates with Moyasar payment gateway for three user types:Configuration
appsettings.json
Payment Flow
- Create Booking: Client creates a booking
- Get Payment ID: Service returns Moyasar payment ID
- Client Completes Payment: Mobile app handles Moyasar payment UI
- Verify Payment: Client calls verify endpoint
- Confirm Booking: Service confirms booking and updates wallet
Payment Verification
Background Jobs (Hangfire)
The service runs several background jobs:Trip Reminders
Sends notifications to drivers and passengers before trip start time:appsettings.json
Auto-Cancel Overdue Trips
Automatically cancels trips that haven’t started after their scheduled time:appsettings.json
Hangfire Dashboard
Access the Hangfire dashboard at:- Scheduled jobs
- Processing jobs
- Failed jobs
- Job history and statistics
Wallet Operations
The service implements a comprehensive wallet system:Wallet Types
- Driver Wallets: Earnings from completed trips
- Passenger Wallets: Pre-paid balance for bookings
- Company Wallets: Corporate account balance
Transaction Types
Credit: Add fundsDebit: Remove fundsTripEarning: Payment from completed tripBookingPayment: Payment for bookingCommission: Platform commissionRefund: Cancelled booking refundWithdrawal: Bank transfer withdrawalDeposit: Top-up deposit
Multi-Currency Support
Each user can have multiple wallets in different currencies (SAR, USD, etc.).Message Bus Events
Published Events:TripCreatedTripStartedTripCompletedTripCancelledBookingCreatedBookingAcceptedBookingRejectedPaymentReceived- Notification events (sent to Notifications service)
DriverCreated- Initialize driver dataDriverUpdated- Sync driver informationCompanyCreated- Initialize company dataVehicleCreated- Register vehicle for trips
Swagger Documentation
The service includes comprehensive Swagger documentation:Related Services
Users Service
Provides user data and validation
Notifications Service
Sends trip and booking notifications
Gateway
Routes trip-related requests
Identity Service
Authenticates API requests