Idempotency

Idempotency allows you to safely retry a request without the risk of performing the same operation twice. This is especially important for Payouts and Checkout Sessions where a network interruption might leave you unsure if the request was successful.

The Idempotency Key

To perform an idempotent request, provide an x-finovo-idempotency header containing a unique string (like a UUID) for that specific transaction.

If FinovoPay receives a second request with the same key, it will return the cached result of the original request instead of creating a new transaction.

Implementation Example

cURL Request with Idempotency

curl -X POST https://merchant.finovopay.com/v1/index.php \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "x-finovo-idempotency: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "withdraw",
    "amount": 5000,
    "bank_code": "058",
    "account_number": "0123456789"
  }'

Recommended Retry Strategy

Exponential Backoff

If a request fails due to a network error, wait 1s, then 2s, then 4s before retrying with the same key.

Key Expiration

FinovoPay stores idempotency keys for 24 hours. Requests made after this period with the same key will be treated as new requests.