Idempotency
Retry write operations without creating duplicate charges, payouts or refunds.
Networks fail in ambiguous ways: your client may time out after KyvoPay has already accepted the request. Idempotency makes a retry safe.
Choose a stable key
Derive idempotency_key from the business operation, such as order-842-payment. Generate it before the first attempt and reuse the exact same value for every retry of that operation.
Do not reuse keys for different operations
A new payment, refund or payout needs a new key. Reusing a key with a different payload can be rejected because the original result is bound to the original request.
Retry policy
Retry connection errors, timeouts, 429 and temporary 5xx responses with exponential backoff and jitter. Do not automatically retry validation errors or authentication failures.
Tip
Store the idempotency key next to your internal order and the KyvoPay public id. This makes recovery and auditing much easier.