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 ypk_test_..." \
-H "X-Idempotency-Key: order-1234-v1" \
-H "Content-Type: application/json" \
-d '{"amount": 49.90, "methods": ["PIX"]}'
Which endpoints require it
| Endpoint | Required |
|---|
POST /v1/payments | Yes |
POST /v1/payments/:id/refund | Yes |
POST /v1/withdrawals | Yes |
POST /v1/products | Yes |
POST /v1/customers | Yes |
Rules
- Maximum length: 100 characters.
- TTL: Idempotency keys are valid for 24 hours.
- Scope: Keys are scoped per company and environment. The same key can be used in sandbox and production without colliding — they’re separate keyspaces.
- 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.
- Replay: Once a request finishes (any 2xx/4xx status), subsequent retries with the same key return the original status code and body for the remainder of the 24h window.
Server errors (5xx) are not stored. Retrying with the same key after a 5xx will execute the request again, so the key remains safe for retries.
Generating keys
Use a value that uniquely identifies the business operation, not just a random string:
const key = `order-${orderId}-payment-v1`;
const key = crypto.randomUUID();
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.
