Payment Processing

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/domain/entities/Payment.ts
• backend/src/application/use-cases/payment/ProcessPaymentUseCase.ts
• backend/src/infrastructure/services/StripeService.ts
• backend/src/interfaces/controllers/PaymentController.ts
• backend/src/application/dtos/PaymentDto.ts
• backend/src/domain/value-objects/Money.ts
• backend/src/infrastructure/database/prisma/schema.prisma
• backend/src/application/use-cases/payment/RefundPaymentUseCase.ts

Payment Processing handles the secure authorization and refunding of cleaning service transactions. The system integrates with Stripe to manage payment intents, ensuring funds are authorized before service delivery.

The system ensures that every payment is linked to a specific Booking and User. It uses a domain-driven approach to track the lifecycle of a transaction from PENDING to SUCCEEDED or REFUNDED.

Sources: backend/src/domain/entities/Payment.ts, backend/src/application/use-cases/payment/ProcessPaymentUseCase.ts

Core Components

The payment system consists of domain entities, use cases for orchestration, and infrastructure services for external provider communication.

Payment Entity

The Payment class represents the domain state. It maintains the link between a cleaning booking and the financial transaction. It encapsulates the transition of payment statuses and stores provider-specific IDs like paymentIntentId and refundId.

Sources: backend/src/domain/entities/Payment.ts:18-60

Stripe Service

StripeService acts as the infrastructure gateway. It handles direct communication with the Stripe API. If no secret key is provided in the configuration, the service operates in a mock mode, returning generated IDs for development.

Sources: backend/src/infrastructure/services/StripeService.ts:16-57

Data Model

The system uses a PostgreSQL database managed via Prisma. The Payment model includes fields for tracking the provider, currency, and audit timestamps.

Field	Type	Description
id	String (UUID)	Unique identifier for the payment record.
bookingId	String (UUID)	Relation to the unique booking being paid for.
userId	String (UUID)	The user who initiated the payment.
amount	Decimal (10, 2)	The monetary value of the transaction.
status	PaymentStatus	Current state (e.g., AUTHORIZED, SUCCEEDED).
provider	PaymentProvider	The gateway used (STRIPE or MANUAL).
paymentIntentId	String (Optional)	The external ID from the payment gateway.

Sources: backend/src/infrastructure/database/prisma/schema.prisma:122-136

Payment Execution Flow

When a user initiates a payment, the ProcessPaymentUseCase coordinates the validation, external authorization, and internal persistence.

The flow ensures that a Stripe Payment Intent is created with capture_method: 'manual' and confirm: true before the local database record is created.

Sources: backend/src/application/use-cases/payment/ProcessPaymentUseCase.ts:18-47, backend/src/infrastructure/services/StripeService.ts:31-40

Refund Logic

The RefundPaymentUseCase handles the reversal of successful transactions. It requires a valid paymentId and a reason string for audit purposes.

1. The system retrieves the existing Payment record by ID.
2. The StripeService initiates a refund against the stored paymentIntentId.
3. The Payment entity updates its status to REFUNDED via the markRefunded method.
4. The updated state, including the new refundId, is persisted to the database.

Sources: backend/src/application/use-cases/payment/RefundPaymentUseCase.ts:9-23, backend/src/domain/entities/Payment.ts:51-54

Validation and Security

The system uses Zod schemas to validate incoming payment requests at the controller level.

export const processPaymentSchema = z.object({
  bookingId: z.string().uuid(),
  userId: z.string().uuid(),
  amount: z.number().positive(),
  currency: z.string().length(3).default('USD'),
  paymentMethodId: z.string().min(3),
});

Sources: backend/src/application/dtos/PaymentDto.ts:3-9

The Money value object ensures that all financial calculations are consistent. It enforces non-negative amounts and handles currency matching to prevent invalid arithmetic operations.

Sources: backend/src/domain/value-objects/Money.ts:4-31

Summary

The Payment Processing module provides a structured way to handle financial transactions within AtlasCleanAI Enterprise. By separating the domain logic from the infrastructure implementation (Stripe), the system maintains a clean audit trail of all authorizations and refunds while ensuring data integrity through strict validation and value objects.