Idempotency keys in payment APIs

An idempotency key is a unique value you attach to a write request so that retrying it is safe. If the same key arrives twice, the server returns the original result instead of performing the action again.

The problem

Networks time out. Your request to create a payment may have succeeded on the server even though you never got the response. Retry blindly and you've paid twice. For money movement, that's unacceptable.

How the key fixes it

With an idempotency key, the retry carries the same key as the first attempt. The server recognizes it, and returns the same payment — never a second one. A different request body under an already-used key is a conflict, not a silent overwrite.

On DigitalTreasury

Every write on the API accepts an Idempotency-Key. Retry a timed-out payment order with the same key and you get the same order back — a timeout can never become a duplicate payment. See the API docs.