PaymentHistoryManager

Records and queries subscription payment history with txHash-based idempotency.

Purpose

PaymentHistoryManager provides a persistent record of all payments associated with subscriptions. It supports recording payments idempotently (duplicate txHash returns { recorded: false }), querying payment history with cursor-based pagination, and looking up payments by transaction hash.

This manager is primarily called by SubscriptionManager and PlanChangeManager during subscription creation, renewal, and upgrade flows. It also supports promo code discount tracking by storing promo code, discount amount, and original amount fields on payment records.

Edge Cases & Error Handling

• Duplicate txHash inserts are detected via explicit SELECT before INSERT (not UNIQUE constraint), returning { recorded: false }
• deletePaymentByTxHash is used for rollback scenarios and silently succeeds if no matching record exists
• Payment amounts stored as strings to preserve decimal precision

See Also

• SubscriptionManager
• PlanChangeManager