API

Gestion de l'IdempotentUuid

Voir en Markdown

Présentation

idempotentUuid est un identifiant unique que vous fournissez pour représenter une tentative de paiement. Il évite les doubles débits lorsque votre logiciel de caisse doit renvoyer la requête (timeout HTTP, problèmes réseau, double clic, redémarrage de l'application).

  • Il est accepté par les endpoints de paiement des API Local, Cloud et Android Intent
  • La vérification côté terminal décrite ci-dessous s'applique uniquement aux API Local et Android Intent

Utilisation par le terminal

Lorsqu'une requête de paiement contient un idempotentUuid :

  • Si une transaction existe déjà sur le terminal pour cet UUID (au cours des dernières 24 heures), le terminal renvoie cette transaction existante au lieu d'en créer une nouvelle
  • Si cette transaction est encore en cours, la requête s'y rattache : sur la Local API, la réponse est envoyée lorsque le paiement en cours est terminé ; sur l'Android Intent API, la transaction en cours est renvoyée telle quelle, sans champ status
  • Sinon, le terminal démarre un nouveau paiement et associe cet UUID à la transaction une fois le paiement terminé

Cloud API. Sur la Cloud API, le terminal ne recherche pas le idempotentUuid : le comportement décrit dans cette section n'est pas effectué par le terminal. Ne comptez pas sur le terminal pour dédupliquer les requêtes de paiement Cloud.

Si la transaction existante pour cet UUID a échoué (status: "ko"), l'envoi du même idempotentUuid renvoie le même échec. Pour réellement réessayer le paiement, générez un nouveau idempotentUuid.

Si vous ne fournissez pas de idempotentUuid, Yavin en génère un pour son propre usage. Cet UUID interne ne protège pas votre logiciel de caisse contre une double soumission.

La règle côté logiciel de caisse

1 tentative de paiement = 1 idempotentUuid

  • Nouvelles tentatives techniques d'une même tentative (timeout, nouvel essai automatique, redémarrage de l'application du logiciel de caisse) : réutilisez le même idempotentUuid
  • Une nouvelle tentative (vous décidez de « réessayer le paiement », généralement après un ko) : générez un nouveau idempotentUuid

Recommandations d'implémentation

  • Générez un UUID (v4) sur le logiciel de caisse lors de la création de la tentative, et conservez-le avec la commande/le panier jusqu'à la finalisation de la tentative
  • Lorsque vous rejouez la requête de paiement à cause d'un problème technique, envoyez exactement le même idempotentUuid
  • Ne réutilisez jamais un idempotentUuid pour une autre tentative, même pour le même montant ou le même panier
  • Après status: "ok" : la tentative est terminée, tout nouveau paiement doit utiliser un nouvel UUID
  • Après status: "ko" : pour réessayer, créez une nouvelle tentative avec un nouvel UUID

Exemple : nouvelle tentative après un timeout

Même requête, même idempotentUuid :

JSON
POST http://<LOCAL_IP>:16125/localapi/v4/payment
{
  "amount": 1000,
  "cartId": "ORDER-2026-000123",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": { "softwareName": "MyPOS", "softwareVersion": "4.7.0" }
}

Paiement en magasin : Local API

Paiement en magasin : Cloud API

Paiement en magasin : Android Intent API