Gestion des joueurs et opérations de casino

Gérer les callbacks en double et les tentatives API

Une API peut envoyer une requête, attendre sans réponse, puis recommencer alors que la première opération a peut-être été enregistrée. Un agrégateur de jeux ou une file d'événements peut aussi remettre le même callback. Si la plateforme de casino interprète chaque livraison comme un nouveau débit, crédit, remboursement ou avantage, les écarts financiers deviennent réels. La livraison d'un message doit donc être distinguée de la transaction métier, avec un seul effet durable dans le grand livre de l'opérateur. Les fournisseurs ne partagent pas tous les mêmes identifiants, réponses aux doublons ou règles de relance. Ce guide présente un traitement authentifié et atomique, les réponses sûres, les événements hors ordre, le rapprochement et les tests indispensables. [1] [2] [4]

Plusieurs messages numériques identiques convergent vers un dispositif sécurisé qui n'inscrit qu'une opération dans le registre
Les messages peuvent revenir; l'effet financier ne doit pas être répété.
Sommaire

Pourquoi un même callback arrive-t-il plusieurs fois ?

L'émetteur peut perdre la réponse HTTP alors que le destinataire a terminé l'opération. Il réessaie, ou une file remet un message dont l'accusé de réception n'a pas été enregistré. La livraison au moins une fois autorise ces doublons; l'ordre n'est pas garanti par défaut. Un nouvel envoi ne prouve ni une fraude ni une seconde transaction métier. [4] [5]

Dans un casino, un débit, crédit ou retour de fonds ne doit pas être exécuté deux fois à cause de la livraison. L'effet métier, la réception du callback et la réponse HTTP ont des cycles indépendants. St8 et 7SoftTech utilisent des ID de transaction pour reconnaître les répétitions, avec des réponses et cas limites distincts. [1] [2]

Quels identifiants composent une clé d'idempotence ?

Distinguez l'ID de livraison, la source authentifiée, la transaction métier, le type d'opération, l'original éventuellement annulé et la manche de jeu. C'est l'identité métier prévue par le contrat qui doit empêcher les écritures répétées. Son périmètre peut inclure fournisseur et opérateur; des services sans lien peuvent réutiliser le même ID. [1] [2] [3]

IdentifiantFonctionRègle
Fournisseur / clientDéfinir l'espace de clésVérifier la source
ID transactionNommer le mouvementUnicité selon le contrat
Type d'opérationDébit, crédit, annulationRespecter le modèle API
ID événementNommer une livraisonPas toujours clé financière
ID d'origineRelier l'annulationValider la référence
Manche et joueurContexte métierNe remplace pas la transaction

Associez à la clé une empreinte stable du contenu et un état persistant. Le même ID avec un montant, une devise ou un joueur différent est un conflit à traiter selon le contrat, jamais une autorisation de nouvelle écriture. AWS décrit ce principe de même intention pour les relances d'API. [3] [4]

Que vérifier avant de traiter un doublon ?

Vérifiez d'abord la signature ou la preuve d'authentification exigée par le fournisseur, sur les octets attendus. Autorisez ensuite la source pour l'opérateur, le portefeuille, le joueur, la devise, l'action et la session concernés. Un ID connu envoyé par une source non authentifiée ne constitue pas une preuve d'exécution. OWASP décrit la sécurisation des webhooks avant déduplication. [1] [6]

  • Contrôler la signature, la fenêtre de validité et la protection anti-rejeu selon le protocole du fournisseur.
  • Associer le fournisseur authentifié au bon opérateur, joueur, portefeuille et devise.
  • Valider ID, précision du montant, action et référence à la transaction d'origine.
  • Comparer l'empreinte du message au contenu mémorisé avant de déclarer un doublon.

Conservez des ID, horodatages et empreintes utiles à l'audit, sans secrets ni données personnelles superflues. Ne renvoyez pas une confirmation positive à une requête falsifiée sous prétexte que son ID existe déjà. [2] [6]

Quel est le parcours complet d'un callback fiable ?

Après authentification, le service recherche ou réserve la clé métier unique, compare les paramètres, applique le mouvement autorisé et conserve le résultat dans la même opération durable de base de données. Une répétition identique retrouve cette décision au lieu de modifier encore le portefeuille. Les cas dont l'issue est incertaine vont au rapprochement. [1] [4] [6]

  1. Authentifier le callback, son fournisseur et le joueur interne autorisé.
  2. Construire la clé métier prévue et vérifier les références d'annulation.
  3. Trouver ou réserver atomiquement l'opération, comptabiliser une seule fois et stocker l'issue.
  4. Répondre selon le fournisseur ou rapprocher le cas ambigu sans créer d'autre mouvement.
Schéma de trois colonnes : callback authentifié et ID métier, inscription comptable atomique, doublon reconnu et rapprochement
Plusieurs tentatives de livraison peuvent désigner la même transaction durable.

Le commit de la base et la réponse HTTP ne constituent généralement pas une seule transaction atomique entre systèmes. Il faut donc gérer le cas où l'écriture est achevée, mais la réponse est perdue : le fournisseur relancera alors un mouvement pourtant enregistré. [4] [7]

Comment garantir une seule écriture financière en base ?

Imposez une contrainte d'unicité réelle sur la clé métier et réalisez la réception, l'effet portefeuille et la conservation de l'issue sous une frontière transactionnelle adaptée. Un SELECT suivi plus tard d'un UPDATE ne protège pas des accès concurrents : deux workers peuvent observer simultanément une clé absente. L'unicité et les verrous doivent être garantis par la base. [3] [4]

État rencontréAction sûreScénario à tester
Clé nouvelleÉcrire et conserver une foisDeux premiers appels concurrents
Terminée, même contenuRestituer l'issueAucun second crédit
En coursAttendre ou rapprocherWorkers concurrents
Même clé, contenu différentRejeter le conflitMontant ou joueur modifié
Annulée avant commitRelancer sous contrôleCrash après réservation

Une boîte de réception d'événements durable est utile, mais l'événement reçu n'est pas la preuve d'une écriture financière. Conservez état de transaction, référence comptable et résultat immuable. Selon le fournisseur, l'annulation possède sa propre identité ou modifie l'opération liée. [1] [3]

Quelle réponse donner à un doublon ou à un conflit ?

Pour un doublon authentifié et déjà traité durablement, renvoyez l'issue initiale ou le code précis demandé par le fournisseur. Il n'existe pas de règle universelle imposant HTTP 200, 409 ou un code JSON identique. St8, 7SoftTech et GR8 Tech ont des contrats de réponse différents. [1] [2] [3]

  1. Garder une règle de réponse stable pour le même ID et la même opération métier.
  2. Refuser le même ID avec une devise, un montant, un joueur ou une action contradictoire.
  3. Après un commit dont la réponse est perdue, restituer la décision sans autre mouvement.
  4. Distinguer rejet métier définitif et panne technique transitoire pour arrêter ou relancer.

N'utilisez pas un ancien solde si le partenaire attend le solde actuel, et n'inventez pas de code de doublon. Vérifiez les règles exactes de répétition, d'annulation et de rejet. Le seul fait d'utiliser POST ne rend pas une relance automatique sûre. [2] [3] [7]

Quand relancer, attendre ou arrêter les requêtes ?

La décision dépend du contrat d'idempotence et de la nature du problème. Un timeout ou une erreur serveur temporaire peut laisser l'issue de la première tentative inconnue. Une signature invalide, un message mal formé ou un refus métier final ne doit pas être répété indéfiniment. Prévoyez des essais bornés, un délai croissant avec jitter et un chemin de rapprochement. [4] [6] [7]

SituationAction préférableMotif
Timeout après envoiConsulter ou réessayer le même IDCommit inconnu
Erreur 5xx / limite temporaireRéessayer de façon bornéeIncident transitoire
Signature invalideRejeter et alerterSource non authentifiée
Refus métier définitifArrêter selon le contratRelance sans effet positif
Accusé perdu après commitRestituer l'issue conservéeÉviter un nouveau débit

Séparez la file automatique de relance des interventions humaines. Les équipes doivent savoir quand une répétition est permise, quand il faut interroger le statut et quand escalader. Ne changez pas l'ID métier pour forcer une transaction incertaine à passer une seconde fois. [3] [4]

Que faire si les événements arrivent dans le désordre ?

Une file peut changer l'ordre des événements; une annulation peut arriver avant le débit qu'elle vise. Certains contrats imposent de conserver une marque de révocation afin que le débit initial reçu plus tard ne soit jamais exécuté. D'autres fournisseurs utilisent des états différents. Il serait dangereux d'appliquer les codes particuliers d'un fournisseur à toutes les API. [1] [2] [5]

  • Conserver la référence d'origine et l'état métier, pas seulement l'heure de réception.
  • Documenter les transitions autorisées entre débit, crédit, annulation et correction pour chaque fournisseur.
  • Créer une marque durable d'annulation anticipée lorsque le contrat le prévoit.
  • Mettre les références non résolues en rapprochement, sans inventer de mouvements.

L'ordre d'arrivée ne définit pas l'ordre métier. Ne triez pas les mouvements uniquement selon l'horodatage distant. Identité de transaction, dépendances entre opérations et source comptable faisant autorité doivent guider la décision. [2] [5]

Comment rapprocher les relances après une panne ?

Un callback peut être reçu mais échouer avant la comptabilisation, ou être comptabilisé tout en perdant son accusé. Suivez séparément la livraison technique et l'écriture réelle. Rapprochez les clés incertaines du grand livre de l'opérateur et des données fournisseur, avec une procédure explicite en cas de conflit. Actualiser simplement le solde affiché ne suffit pas. [1] [3] [4]

  • Mesurer essais, doublons reconnus, signatures refusées, écarts de payload et file de rapprochement par fournisseur.
  • Alerter sur timeouts fréquents, opérations bloquées, annulations anticipées et écarts comptables.
  • Limiter la relance manuelle aux personnes autorisées avec ID d'origine et motif audité.
  • Comparer le grand livre et les relevés fournisseur avant toute écriture compensatrice.
  • Conserver le registre de déduplication assez longtemps pour les délais contractuels de relance et de litige.

Évitez de transmettre données de paiement ou personnelles brutes aux outils d'analytique générale. Les identifiants sûrs, empreintes, dates, changements d'état et interventions permettent l'audit avec des accès restreints. Affichez séparément le nombre de doublons livrés et les écarts financiers réels. [4] [6]

Quels tests d'acceptation prouvent la sécurité des relances ?

Un pari et un gain traités correctement une fois ne démontrent pas la résistance aux relances. Les essais doivent couvrir IDs répétés, payloads contradictoires, workers simultanés, réponses perdues, annulations et messages tardifs selon les règles du partenaire. 7SoftTech documente des scénarios de certification pour bet, win et cancel répétés. [2]

  1. Exécuter un débit ou crédit, renvoyer le même callback signé et vérifier une seule écriture.
  2. Renvoyer l'ID avec un autre montant, joueur ou devise et vérifier le refus contrôlé.
  3. Mettre deux livraisons en concurrence, simuler la perte du reply après commit et relire l'issue.
  4. Livrer une annulation avant son origine et contrôler la transition prévue par le fournisseur.
  5. Simuler indisponibilité et retards, puis rapprocher grand livre et traces d'audit.

Avant production, validez avec chaque partenaire les réponses, le périmètre des clés, la durée des relances et les règles de reversal. L'objectif n'est pas d'empêcher toute livraison répétée, mais d'obtenir une seule bonne conséquence financière pour chaque opération autorisée, malgré les délais et erreurs de réseau. [1] [3] [4]

Sources et ressources complémentaires

Visionneuse de schéma