Skip to main content
The YuvexPay API supports idempotency keys to prevent duplicate operations when retrying failed requests.

​
How it works

Include an X-Idempotency-Key header with a unique string on any POST request that creates a resource: 
curl -X POST https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer ypt_..." \
  -H "X-Idempotency-Key: order-1234-v1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 49.90, "methods": ["PIX"]}'
If you send the same request with the same idempotency key, the API returns the original response instead of creating a duplicate.

​
Which endpoints require it

EndpointRequired
POST /v1/paymentsYes
POST /v1/payments/:id/refundYes
POST /v1/withdrawalsYes
POST /v1/productsYes
POST /v1/customersYes

​
Rules

  • Maximum length: 100 characters.
  • TTL: Idempotency keys are valid for 24 hours.
  • Payload check: If you reuse a key with a different request body, the API returns a 409 Conflict with error code IDEMPOTENCY_PAYLOAD_MISMATCH.
  • Concurrent requests: If a request with the same key is already being processed, the API returns a 409 Conflict with error code IDEMPOTENCY_CONFLICT.

​
Generating keys

Use a value that uniquely identifies the business operation, not just a random string: 
// Good: tied to the business entity
const key = `order-${orderId}-payment-v1`;

// Good: UUID for one-off operations
const key = crypto.randomUUID();

// Bad: timestamp alone (not unique enough)
const key = Date.now().toString();
Append a version suffix (e.g., -v1, -v2) to the key if you need to intentionally retry with different parameters.