Idempotency

Overview

Idempotency ensures that if you accidentally send the same request twice, we'll only process it once. This protects against duplicate transfers due to network issues or retries.

How It Works

1. Include a unique X-Idempotency-Key header with your request
2. We store the response for that key
3. If you send the same key again within 24 hours, we return the cached response

Best Practices

• Use UUID v4: Generate a unique UUID for each distinct operation
• Include in all mutating requests: Required for POST endpoints
• Store the key: Save the idempotency key with your records for debugging
• Don't reuse keys: Use a new key for each new operation

Example

# First request
curl -X POST "https://api.esca.finance/v1/virtual-account/transfer" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"currency": "NGN", "accountId": 12345, "amount": 10000, ...}'

# Response: 201 Created with transfer UUID

# Retry with same idempotency key (network issue, etc.)
curl -X POST "https://api.esca.finance/v1/virtual-account/transfer" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"currency": "NGN", "accountId": 12345, "amount": 10000, ...}'

# Response: Same 201 Created response (no duplicate transfer)