Make donation refund operations idempotent and safe under repeated requests

[grantfox-oss]

Context

The donation refund flow in src/services/donation.service.ts updates a donation to REFUNDED and decrements the campaign balance inside a transaction. Repeated refund requests or retries could create inconsistent state if the same refund action is triggered more than once.

Problem statement

Implement refund idempotency so that repeated refund requests do not cause inconsistent state or duplicate side effects.

Current behavior

• src/services/donation.service.ts allows a refund to be attempted whenever the donation is in a confirmed state and the caller is authorized.
• There is no explicit guard to ensure the refund operation is safely deduplicated if the same request is retried.

Required behavior

• Repeated refund requests for the same donation should be handled safely and consistently.
• The service should avoid double-decrementing campaign balances or applying duplicate refund state transitions.
• The behavior should be explicit and testable.

Constraints

• The change should preserve the existing donation refund API behavior.
• The solution should remain compatible with the current transaction flow.

Acceptance criteria

• Repeated refund requests for the same donation do not double-apply the refund.
• The campaign balance is decremented only once for a single refund operation.
• Unit tests cover duplicate refund requests and retry scenarios.

Out of scope

• Implementing a broader accounting or ledger system.
• Changing the donation refund API contract.

Hints and references

• Review the transaction boundaries in the donation confirmation and refund flow and how the service currently handles state changes.

[Victorjonah-prog]

Hi maintainer, I'd like to work on issue #144. I have experience with TypeScript, Prisma, and transactional service layers. I'll add an idempotency guard to the refund flow that checks the donation status before applying the refund, ensuring the campaign balance is decremented only once and repeated requests are safely deduplicated, with unit tests covering duplicate and retry scenarios. Ready to start immediately!

[Truphile]

Hi team, I’d love to take this on!

I am a software engineer focused on structural code quality, clean separations of concern, and deterministic error handling. I am ready to break down these requirements into a highly reliable, production-ready solution.

I will deliver:

Decoupled Architecture: Implement the core business logic using explicit boundaries, ensuring the solution remains modular, easy to audit, and free of hidden side effects.

Pipeline & Storage Sync: Cascade all necessary data-model updates smoothly across the API surface, background workers, and persistent data layers to maintain total state synchronization.

Component Resilience: Refactor or deploy intuitive user-facing elements that cleanly represent async transitions, edge-case states, and form validations.

Automated Regression Suite: Construct a matching matrix of unit and integration tests designed to aggressively exercise boundary conditions and ensure continuous CI pass marks.

Ready for assignment to drop a complete, highly polished PR immediately!

[Heazzy500]

Hello Maintainer, I'd like to work on this issue. I have experience with blockchain development and state management, and I can implement this. Please consider assigning it to me.

[grantfox-oss]

🦊 GrantFox — @Heazzy500 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #144)
2. Your PR will be reviewed by the aid-linkk maintainers

Good luck! Track your progress on GrantFox.