The duplicate payout problem

A timeout does not prove failure

Your application
      |
Send $500 payout
      |
Payout system creates payment
      |
Response is lost
      |
Your application sees timeout

If the application retries as a brand-new instruction, the recipient may get another $500.

Idempotency gives the instruction an identity

Pay Alex $500
Instruction ID: athlete_bonus_82719

If the same instruction arrives again with the same key, the payout system can return the existing result instead of creating another payment.

Use the business event

This does not help:

Attempt 1: key_123
Timeout
Attempt 2: key_456

The system sees two requests.

Use one stable identifier:

Business event: athlete_bonus_82719

Attempt 1: athlete_bonus_82719
Timeout
Attempt 2: athlete_bonus_82719

Idempotency is one layer

A clean data model should distinguish between the obligation, payout, attempts, and final result.

Obligation
$500 owed

Attempt 1
RTP
Failed

Attempt 2
ACH
Completed

Obligation
Satisfied

Human duplicates happen too

A file can be uploaded twice. Two teams can initiate the same payout. An operator can retry a payment that already completed. The same recipient can appear in two batches.

Useful controls can flag suspicious combinations such as the same recipient, amount, reference, and time period.

The rule

Before sending money again, answer one question:

Do we know the first payment did not happen?

If the answer is no, resolve the existing status first.