Idempotency

Safely retry POST requests without creating duplicates.

Network glitches happen. To make POST requests safe to retry, EzPays supports idempotency keys on every endpoint that creates or mutates a resource.

How it works

1. Generate a unique key per logical operation. A UUIDv4 is fine.
2. Send it in the Idempotency-Key header.
3. Retry the request as many times as you like — the API guarantees the operation runs at most once.

KEY=$(uuidgen)
 
curl -X POST https://api.ezpays.app/api/public/v1/payment-links \
  -H "Authorization: Bearer ezp_live_..." \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "creditor_id": "cr_123", "amount": "12500", "currency": "USD" }'

If the same Idempotency-Key is presented again within 24 hours with the same body, the original response is replayed — including the same status code, body, and resource ID.

Conflicts

Reusing an idempotency key with a different request body returns:

HTTP/1.1 409 Conflict
Content-Type: application/json
 
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was previously used with a different request body.",
    "request_id": "req_..."
  }
}

This protects you from accidental key collisions across different operations.

Where it applies

Every POST endpoint accepts (and benefits from) an Idempotency-Key. It is ignored on GET, DELETE, and PATCH because those are already idempotent at the protocol level.

Generating keys

A common pattern is to derive the key from your domain identifier — e.g. paymentlink:invoice:1042 — so retries from any source converge on the same key.