Idempotency is a financial control, not API polish

The duplicate is not the edge case

A payment request can be repeated because a bank timed out, an operator retried, a queue redelivered, or two copies arrived at nearly the same moment. None of those events proves that the original payment failed. They prove only that the caller does not yet know the outcome.

That distinction changes the architecture. If a gateway begins its business work and checks for duplication later, two concurrent requests can both pass the check. A financial system needs to reserve the message identity before it performs the side effect.

Operating principleUnknown to the caller does not mean unprocessed by the system.

Insert first, then decide

SIPS Connect documents an insert-first approach: persist the inbound identity before processing, let database uniqueness arbitrate concurrency, and make every later decision from stored state. The database is not merely a record after the fact; it participates in the control.

The identity is layered. Message identifiers protect the transport conversation. Transaction identifiers protect the business movement. Message type matters because a status inquiry and a credit transfer can legitimately refer to the same transaction while representing different operations.

• Reserve MsgId and TxId within the correct message-type scope.
• Treat an in-process duplicate differently from a completed duplicate.
• Return the stored response when the original outcome is already known.
• Gate returns against the original transaction and prior return records.

Deterministic replay is the clean answer

A completed duplicate should not reconstruct a response from current conditions. It should replay the response already attached to the original processing decision. That preserves the historical contract even if configuration, participant status, or downstream availability has changed.

This is the deeper lesson: idempotency is not a single key in a cache. It is a state model, persistence policy, concurrency boundary, and response contract working together.