Idempotency

Every mutating endpoint (POST, PUT, PATCH, DELETE) accepts an Idempotency-Key header, letting you safely retry requests without risk of duplicate side-effects.

💡

Always send an idempotency key for actions that cost money — creating a card, issuing a transfer, or charging a wallet.

How it works

You attach a unique Idempotency-Key (we recommend UUID v4).
VaultsPay stores the key + response for 24 hours.
Any retry with the same key + same endpoint replays the original response instead of executing again.

Example

curl -X POST https://api.vaultspay.ae/v1/transfers \
  -H "Authorization: Bearer sk_test_yourApiKeyHere" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "from_account": "acc_01...", "to_account": "acc_02...", "amount": 5000, "currency": "AED" }'

Rules

Keys must be at most 64 ASCII characters.
Keys are scoped to your account — you can reuse the same UUID across endpoints.
Retrying with the same key but a different body returns 409 idempotency_key_in_use.
Keys expire after 24 hours — after that, the same key can be reused.

When you don’t need an idempotency key

GET requests (no side-effect).
Bulk actions like /v1/batch which have their own atomicity guarantees.

Pagination Rate Limits