Idempotence

Un délai dépassé côté réseau ne vous dit rien sur ce que le serveur a fait. Rejouer un POST /transfers à l'aveugle peut payer deux fois un bénéficiaire. Une clé d'idempotence lève l'ambiguïté : le second appel renvoie la réponse du premier au lieu de refaire le travail.

L'en-tête

Envoyez Idempotency-Key sur la requête. Sans préfixe X-.

Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i...
Idempotency-Key: 8f14e45f-ceea-467a-9bd1-2c2bd7a1e0a4
Content-Type: application/json

Les clés sont rattachées au triplet (clé, équipe, environnement). La même chaîne utilisée en sandbox et en live correspond à deux clés indépendantes, et aucune autre équipe ne peut entrer en collision avec les vôtres.

Où ça fonctionne

Les deux protections se comportent de la même façon vues de l'extérieur, et diffèrent par la durée pendant laquelle elles se souviennent.

Les paiements et les transferts stockent la clé sur la ligne elle-même, sous une contrainte d'unicité. La protection n'expire jamais : rejouer cette clé dans un an renvoie toujours le paiement d'origine au lieu d'en créer un second. C'est aussi cette contrainte qui maintient la garantie en cas de concurrence : deux requêtes simultanées avec la même clé aboutissent à une seule ligne et à deux réponses identiques.

Tout le reste met la première réponse en cache pendant 24 heures. Passé ce délai, la clé est oubliée et le même appel crée une nouvelle ressource. C'est le bon compromis pour un client ou un lien de paiement, où un doublon est une gêne plutôt qu'une perte.

Rejouer une requête

Générez la clé une seule fois, au moment de l'intention métier, et réutilisez-la pour chaque tentative réseau de cette même intention.

curl https://api.wajub.com/transfers \
-H "Authorization: $WAJUB_API_KEY" \
-H "Idempotency-Key: payout-invoice-4172" \
-H "Content-Type: application/json" \
-d '{
  "amount": 100000,
  "currency": "XAF",
  "beneficiary": {
    "phone": "237670000000",
    "channel": "cm.mtn",
    "name": "Amina Nkeng"
  }
}'

Envoyez-la une seconde fois et vous recevez la première réponse, à l'octet près, avec le même id de transfert. Rien n'a été créé, aucun argent n'a bougé.

Réutiliser une clé avec un corps différent

Rejouer n'est sûr que s'il s'agit de la même requête. Si vous réutilisez une clé avec un payload différent, Wajub refuse au lieu de renvoyer en silence une ressource que vous n'avez pas demandée :

Sur POST /payments, la comparaison utilise un hash stocké sur le paiement : elle tient donc pendant toute la vie de l'enregistrement. Sur POST /transfers, le hash est mis en cache pendant 24 heures : passé ce délai, la clé renvoie toujours le transfert d'origine, elle cesse simplement de vérifier que les corps correspondent. Les transferts comparent amount, currency, beneficiary, description et reason.

Un en-tête mal formé arrive sous la forme du même 422 avec un autre message, The Idempotency-Key header format is invalid.

Concurrence

Deux requêtes qui partagent une clé sont traitées l'une après l'autre : la seconde attend jusqu'à dix secondes que la première se termine, puis lit son résultat. Vous n'avez jamais deux créations en cours pour une même clé, ni une ressource écrite à moitié.