Idempotency
A key per transaction makes retries safe.
Every payment and payout requires a unique idempotency_key, a UUID you generate. Send the same key twice and you get the original result back instead of a duplicate transaction.
How to use it#
- Generate a UUID and store it against your own order or payout record before you call the API.
- If the call times out or the connection drops, retry with the same key. You cannot double-charge a customer this way.
- Never reuse a key for a different transaction.
Same key, different body#
A repeat with the same key and the same request returns the original transaction. A repeat with the same key but a different body is a conflict and returns 409, because the key has already been committed to different values.
| You send | You get |
|---|---|
| New key | A new transaction, 202 Accepted |
| Same key, same body | The original transaction |
| Same key, different body | 409 idempotency conflict |
Practical rule: One key per business intent. Generate it once, persist it, reuse it for every retry of that same intent.
Scope and retention#
Use a fresh UUID v4 for every transaction, and never share one between a payment and a payout. Because a v4 UUID is globally unique, you never need to reason about whether the key space is per account or per endpoint: a key you generated will only ever match your own earlier request. Keys are retained for at least the 24-hour webhook retry window, so a same-key retry is safe for at least that long after the original.
Maly Tech Ltd. This guide is provided for information. Where it differs from your signed agreement, the agreement applies.