Idempotency

Your server sends a payout. The connection drops before the response arrives. Did it go through? If your code simply retries and the first attempt did succeed, someone gets paid twice.

The fix is an idempotency key: an id you choose for the operation and send with every attempt. The server remembers it. A repeat of the same key returns the original result instead of doing the work again.

The pattern

1. Create your own payout record first, and save its id.
2. Send that id as the idempotency key.
3. On a timeout or a server error, retry with the same key.
4. You get either the payout that was already created, or a new one if the first attempt never arrived. Never both.

On Valtu

POST /v1/transfers and POST /v1/wallets are idempotent by externalId. The same request again returns the original object. Reusing an externalId with different details, such as another amount or destination, returns 409 DUPLICATE instead of guessing. Batches require an externalId on every payout. GET requests are always safe to retry. More in never pay twice.