Core Concepts

Idempotency

Every state-changing request (POST, PUT, PATCH, DELETE) requires an Idempotency-Key header — a UUIDv4 you generate per logical request. Retry the same request with the same key after a timeout and you get the original result back, never a duplicate charge.

The reservation pattern

When Prosoft Pay first sees a new Idempotency-Key, it reserves it before doing any work with the bank connector, then fills in the real response once a definitive outcome is known. This is what lets a payment survive a bank timeout safely: nothing is silently double-processed on retry, and nothing fabricates a cached response for a request that never actually completed.

Same key, same body

Returns the cached response from the original attempt — the request is not reprocessed, and no second bank call is made.

Same key, different body

Rejected with 409 conflict, code idempotency_key_conflict — the key was reused across two logically different requests. Generate a fresh key for a genuinely new request.

Same key, still in flight

If a previous attempt with the same key and body hasn't reached a definitive outcome yet — a genuinely concurrent duplicate, or a prior attempt left unresolved by a bank timeout — a retry is rejected with 409 conflict, code request_in_progress. Wait and retry with the same key rather than generating a new one; a reservation only clears automatically after 24 hours.

See Errors for the full error envelope and code taxonomy.