Idempotency Keys

A merchant sends POST /payments and the request times out.

Three different things could be true: the service never received it, the service received it and is still working, or the payment was created and only the response was lost.

The merchant cannot safely choose between "send again" and "do nothing." Sending again may charge twice. Doing nothing may abandon a payment that never started.

An idempotency key gives both attempts one logical identity.

An idempotency key is a caller-generated value that says, "These deliveries are attempts to perform the same logical operation."