Idempotent Requests#

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

Using Idempotency Keys#

To perform an idempotent request, provide an Idempotency-Key header with a unique value:

curl https://api.casapay.com/v1/payment_intents \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Idempotency-Key: KG5LxwFBepaKHyUD" \
  -H "Content-Type: application/json" \
  -d '{"amount": 120000, "currency": "eur"}'

How It Works#

• An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.
• Keys are eligible to be removed from the system after they are at least 24 hours old.
• If a request is received with a previously used key, the API returns the original response for that request.
• If a request with the same key is in progress, the API returns a 409 Conflict error.

Generating Keys#

We recommend using V4 UUIDs or another random string with enough entropy to avoid collisions:

const { v4: uuidv4 } = require('uuid');

const idempotencyKey = uuidv4();
// e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890"