fix: reserve funds before async payment confirmation

[Fading-Dev]

Overview

This PR adds atomic reserve-before-confirmation handling to the payment workflow, ensuring pending high-value transactions cannot spend the same balance twice. Funds are reserved atomically at submission, released on terminal failure, and included in all available-balance calculations.

Related Issue

Closes #BA-092

Changes

🔒 Atomic Fund Reservation

• [MODIFY] BackendAcademy/src/common/transaction-manager.service.ts

  • Adds a transactional reservation primitive that locks funds atomically before any asynchronous payment confirmation is dispatched.
  • Guarantees reservation and payment creation commit or roll back in the same database transaction.

• [MODIFY] BackendAcademy/src/payments/payments.service.ts

  • Reserves funds synchronously at payment submission before handing off to async confirmation.
  • Releases reservations automatically on terminal failure (failed / cancelled).
  • Tracks pending reservations in available-balance calculations so reserved funds cannot be double-spent.

• [MODIFY] BackendAcademy/src/payments/payments.controller.ts

  • Returns reservation status in payment responses.
  • Rejects submissions when available balance (including pending reservations) is insufficient.

• [MODIFY] BackendAcademy/src/payments/payments.module.ts

  • Wires the transaction manager and reservation store into the payments module.

Verification Results

npm test -- BackendAcademy/src/payments
✅ 18/18 passed

Live acceptance check:
✅ Atomic reservation under concurrent high-value submissions
✅ Reserved funds released on terminal failure
✅ Available balance includes pending reservations
✅ No double-spend observed under parallel load

Acceptance Criteria	Status
Funds are reserved atomically	✅ Reservation + payment creation in single transaction (verified by concurrency test)
Released on terminal failure	✅ Sweeper releases reservations after failed/cancelled async confirmation
Included in available-balance calculations	✅ Available balance = total balance − reserved − spent

Closes #660

[drips-wave]

@Fading-Dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits