Design Idempotent Loan Payments and Investor Distribution

Design a simplified loan-payment system. A borrower makes a payment, and the system distributes that payment to investors. Money movement is performed by a third-party provider. Interest, fees, and the calculation of investor allocations are out of scope. Focus on the payment flow and idempotency, making the order of operations explicit. ### Constraints & Assumptions - Do not add interest or fee calculations. - Distribution is required, but determining how much each investor is entitled to receive is not part of the task. Clarify how the existing distribution instructions are supplied. - An external provider performs money movement; a local database transaction does not make a provider call atomic. - Provider idempotency, status-query, and notification capabilities must be confirmed rather than assumed. ### Clarifying Questions to Ask - Who supplies the investor amounts, and must they sum exactly to the borrower payment? - When is a borrower payment considered confirmed and available for distribution? - Does the provider support durable idempotency keys and lookup by a merchant reference? - What should happen when some investor transfers succeed and others fail? ### Part 1 — Accept and Process a Borrower Payment Show the ordered steps from a payment request through provider submission and confirmed outcome. Explain concurrent duplicate requests and a timeout after the provider may have accepted the payment. #### What This Part Should Cover - A stable logical payment identity, request validation, and a durable state record. - Binding an idempotency key to the meaning of the request. - The local-to-provider handoff and recovery after ambiguous outcomes. - Duplicate or out-of-order provider notifications. ### Part 2 — Distribute Confirmed Funds Explain how confirmed payments become investor transfers and how the system records and recovers partial completion without distributing the same amount twice. #### What This Part Should Cover - A stable transfer identity for each supplied distribution instruction. - State transitions that distinguish confirmed receipts, pending distributions, and completed transfers. - Safe retries, reconciliation, and visibility into partial failure. - Conservation of recorded amounts without introducing an allocation algorithm. ```hint A timeout is not proof that money failed to move. Trace the durable identifiers on both sides of every provider call. ``` ### What a Strong Answer Covers The answer should present a numbered flow with the database writes, provider calls, and acknowledgements in their actual order. It should distinguish request deduplication from effect deduplication, preserve the task's simplified scope, and explain what remains indeterminate when provider capabilities are insufficient. ### Follow-up Questions - What if the same idempotency key is reused with a different amount? - What if a provider notification arrives before the synchronous response? - How would you recover one failed investor transfer without repeating successful ones?