Glossary
Idempotency key
An idempotency key is a unique value, usually a UUID, that a client sends with a request that creates or changes something, so that repeating the same request after a timeout, a network error or a crash returns the same result instead of producing a duplicate. The server stores the key with the response for a period and, on a repeat, replays the stored response; a repeat with the same key but a different body is rejected. In payments it is what makes a retry safe.
Why payments need it
A merchant’s server sends a payout and the connection drops before the answer: did it go out? Without idempotency the only safe answer is to check and hope; with a key the merchant simply sends the same request again and gets the one result. The same protects payment creation, refunds and captures, and the platform’s own calls to providers that support keys.
Keys, references and webhooks
A merchant’s order reference identifies the purchase; the idempotency key identifies one attempt to call the API; the platform’s payment identifier identifies the resulting payment. Webhooks carry the payment identifier and the merchant’s reference, and a merchant should also treat webhook delivery as repeatable: the same event may arrive twice.
On the platform
Tranzify’s API uses the merchant’s reference as the guard against duplicates: a second request with a reference the merchant has already used is rejected with an error instead of creating another payment; the payment’s identifier and the reference travel in every webhook.
Updated: 2026-11-08