Idempotence

Évitez les doubles encaissements en rejouant la même clé d’idempotence.

Idempotency-Key: unique-stable-key-001

Où c’est obligatoire

  • POST /v1/payments
  • POST /v1/payments/:id/refunds
  • POST /api/public/payment-links/:token/pay (header ou body)
  • Paiements / remboursements session marchand (header ou body idempotencyKey)

Comportement

  • Portée : (store_id, environment, idempotency_key)
  • Même clé + même hash de requête → rejoue la réponse mise en cache
  • Même clé + hash différent → 409 IDEMPOTENCY_CONFLICT
  • Requête concurrente en cours → 409 IDEMPOTENCY_IN_PROGRESS
  • Sans merchantReference, AIFI PAY la déduit de la clé : un nouvel essai renvoie le même paiement
  • Référence déjà utilisée, par exemple par une tentative qui a échoué → 409 MERCHANT_REFERENCE_CONFLICT : recommencez avec une nouvelle clé