Integration

Idempotence

Une meme cle ne cree jamais deux transactions, meme en cas de coupure reseau ou de rejeu automatique.

Principe

Requete 1  ──▶  Idempotency-Key: order-123  ──▶  Paiement cree      201
Requete 2  ──▶  Idempotency-Key: order-123  ──▶  Meme paiement      201 (rejeu)
Requete 3  ──▶  Idempotency-Key: order-123  ──▶  Corps different    409

La cle est portee par le triplet (entreprise, environnement, cle) : deux marchands peuvent utiliser order-123 sans interference.

Utilisation

curl https://api.wanepay.com/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{ "amount": 10000, "currency": "XOF", "country": "TG",
        "payment_method": "mobile_money", "network": "tmoney" }'

Regles

L’en-tete est supporte sur toutes les creations : POST /v1/payments, /v1/payouts, /v1/refunds, /v1/payment-links, /v1/customers.
La cle est conservee 24 heures. Passe ce delai, elle est recyclee et une nouvelle transaction peut etre creee.
Une requete en echec libere sa cle : vous pouvez rejouer la meme cle avec une requete corrigee.
Une requete identique encore en cours de traitement renvoie idempotency_request_in_progress (409) : reessayez apres une courte attente.
L’en-tete Idempotent-Replayed: true signale une reponse memorisee.

Choisir une bonne cle

Utilisez un identifiant metier stable

L’identifiant de commande, de facture ou de session est ideal : il est stable entre les tentatives et unique par transaction attendue. Evitez les UUID generes a chaque appel — ils annulent tout benefice de l’idempotence.