EventCatalog | Entities

Overview

The Payment entity manages all payment transactions in the e-commerce system. It tracks payment details, status, and relationships with orders and customers, supporting various payment methods and refund scenarios.

Entity Properties

Name	Type	Required	Description
`paymentId`	`UUID`	Required	Unique identifier for the payment
`orderId`	`UUID`	Required	Order this payment is associated with
`customerId`	`UUID`	Required	Customer who made the payment
`amount`	`decimal`	Required	Payment amount
`currency`	`string`	Required	Currency code (e.g., USD, EUR, GBP)
`paymentMethod`	`string`	Required	Payment method used
`paymentMethodDetails`	`object`	Optional	Additional payment method specific details
`status`	`string`	Required	Current payment status
`transactionId`	`string`	Optional	External payment processor transaction ID
`gatewayResponse`	`object`	Optional	Raw response from payment gateway
`billingAddress`	`Address`	Required	Billing address for the payment
`processedAt`	`DateTime`	Optional	Date and time when payment was processed
`failureReason`	`string`	Optional	Reason for payment failure if applicable
`refunds`	`array`	Optional	Refunds associated with this payment
`createdAt`	`DateTime`	Required	Date and time when the payment record was created
`updatedAt`	`DateTime`	Optional	Date and time when the payment record was last updated

Relationships

Order: Each payment belongs to one Order (identified by orderId).
Customer: Each payment is made by one Customer (identified by customerId).
Address: Each payment has a billing Address (identified by billingAddress).
PaymentRefund: A payment can have multiple PaymentRefund entities for partial or full refunds.

Payment States

pending → processing → completed
    ↓         ↓           ↓
cancelled  failed    refunded/partially_refunded

Examples

Payment #1: $299.99 credit card payment for Order #12345, completed successfully.
Payment #2: $150.00 PayPal payment for Order #67890, failed due to insufficient funds.
Payment #3: $500.00 bank transfer, completed with $50.00 partial refund.

Business Rules

Payment amount must match the order total
Payment status transitions must follow valid state machine
Failed payments should include failure reason
Completed payments cannot be cancelled
Refunds cannot exceed the original payment amount
Payment method details are encrypted and PCI compliant
Transaction IDs from payment gateways must be stored for reconciliation

Payment (v1.0.0)