Skip to content

docs / idempotency

Idempotency

All mutating endpoints (POST, PATCH) that initiate financial operations require an Idempotency-Key header. This lets you safely retry a request without risking duplicate payments.

http
POST /v1/payins HTTP/1.1
Authorization: Bearer sk_live_••••
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

How it works

  1. On the first request with a given key, Payve executes the operation and caches the response for 24 hours
  2. If the exact same key is sent again (same endpoint, same API key), the cached response is returned immediately with no side effects
  3. If the same key is sent with different parameters, the API returns 409 idempotency_conflict
json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key was already used with different request parameters.",
    "status": 409
  }
}

Generating keys

Use a UUID v4 for each unique operation:

ts
// TypeScript / Node
import { randomUUID } from 'crypto';
const idempotencyKey = randomUUID();
python
# Python
import uuid
idempotency_key = str(uuid.uuid4())
bash
# Shell
uuidgen

What counts as a duplicate

Two requests share an idempotency key if they have the same key value under the same API key against the same endpoint. Different endpoints never share keys even if the value is the same.

When to use new keys

Generate a new key when you genuinely intend a new operation — for example, if a customer re-submits a payment form after a failed attempt. Generate the same key only when you are retrying the exact same operation that may have timed out or failed transiently.

💡
Store idempotency keys in your database alongside each transaction so you can safely replay them if your own service crashes mid-request.