Une couche d'agrégation de fournisseurs de jeux pour votre propre backend de casino : sessions, callbacks de solde et historique des tours de jeu

Un opérateur qui construit son propre backend de casino et connecte des machines à sous, des jeux avec croupier en direct et des jeux de table issus de nombreux fournisseurs se retrouve avec autant de contrats d'intégration que de fournisseurs : des flux de lancement différents, des appels au portefeuille différents, des idées différentes de ce qu'est un tour de jeu. La couche d'agrégation les transforme en un seul contrat interne, si bien que le portefeuille, le lobby, les bonus, les limites et le reporting sont écrits une seule fois et que chaque fournisseur y est adapté.

Ce qui suit montre comment cette couche se découpe en général : ce qui reste chez le fournisseur, comment les sessions sont émises, comment les callbacks de solde survivent aux retries et aux rollbacks, comment les tours de jeu sont enregistrés quand ils se clôturent après la session, et comment le résultat est réconcilié avec les propres chiffres du fournisseur.

Ce qui relève de la couche et ce qui reste chez le fournisseur

Le fournisseur fait tourner le jeu : la génération de nombres aléatoires, les mathématiques du jeu, le client de jeu et sa certification par un laboratoire de test. L'opérateur garde tout ce qui touche au joueur et à l'argent : l'identité, le solde, les limites, les bonus, le lobby et les enregistrements que peuvent réclamer un régulateur ou un litige avec un joueur. La couche d'agrégation se place entre les deux et devrait être le seul code côté serveur à parler l'API de chaque fournisseur.

• Lancement : une URL de jeu ou un token pour un joueur, un jeu, une devise, une langue et un appareil, et un mode démo qui n'atteint jamais le portefeuille
• Portefeuille : les appels de solde, de débit, de crédit et de rollback de chaque fournisseur, auxquels on répond via un seul grand livre interne
• Tours de jeu : l'ID et l'état des tours de jeu de chaque fournisseur, y compris les tours de jeu à plusieurs mises et ceux qui se terminent tard
• Catalogue : les ID de jeux des fournisseurs, les catégories et les appareils pris en charge, mappés vers un seul lobby et filtrés selon les endroits où chaque jeu peut être proposé
• Bonus : des tours gratuits accordés via la propre interface de bonus d'un fournisseur lorsqu'il en a une, avec les gains enregistrés comme argent bonus
• Reporting : des totaux par fournisseur, sous la forme sur laquelle le fournisseur s'appuie pour facturer

Seamless wallet ou transfer wallet

Les fournisseurs se connectent à l'argent d'un opérateur de l'une des deux manières suivantes. Dans un seamless wallet, le solde reste chez l'opérateur, et le fournisseur appelle le portefeuille de l'opérateur pour chaque mise et chaque gain. Dans un transfer wallet, l'opérateur déplace de l'argent vers un solde tenu du côté du fournisseur avant le jeu, et ne le rapatrie que lorsqu'il le demande.

• Le seamless wallet garde un seul solde pour tous les jeux, si bien que les limites, les bonus et la vue qu'a le joueur de son argent restent cohérents, et il fait entrer la latence et la disponibilité du portefeuille de l'opérateur dans chaque spin
• Le transfer wallet isole le jeu vis-à-vis du portefeuille de l'opérateur et scinde le solde : l'argent qui se trouve dans une session chez un fournisseur n'est disponible nulle part ailleurs, et chaque transfert entrant et sortant est une écriture de plus à réconcilier
• Une couche qui prend en charge les deux a malgré tout un seul grand livre interne ; l'adaptateur de transfer wallet transforme le début et la fin d'une session en un débit et un crédit

La suite de cet article suppose un seamless wallet, car chaque mise et chaque gain y est un appel au portefeuille.

Sessions : l'opérateur émet le token

Le lancement d'un jeu commence du côté de l'opérateur. Le backend vérifie que ce joueur a le droit de jouer à ce jeu maintenant, ce qui couvre l'état du compte, l'auto-exclusion, les limites et la question de savoir si le jeu peut être proposé dans la juridiction du joueur. Il crée ensuite une session liée au joueur, au jeu et à la devise, et transmet un token opaque au fournisseur lors du lancement. Lorsque le serveur du fournisseur envoie un callback, ce token identifie à qui appartient le solde visé par l'appel.

• Un token identifie une session, pas un joueur pour toujours : il expire, et l'opérateur peut le révoquer lorsque le joueur s'auto-exclut ou atteint une limite en cours de jeu
• Les nouvelles mises exigent une session valide ; un gain lié à une mise déjà acceptée doit être crédité même si la session a pris fin entre-temps
• Un joueur peut avoir plusieurs sessions de jeu en même temps, si bien que les variations de solde sont sérialisées par compte, et non par session
• La devise est fixée pour la session ; un joueur qui change de devise en démarre une nouvelle
• Le jeu en mode démo reçoit un token que le portefeuille refuse d'office, si bien qu'un appel mal routé ne peut jamais toucher à de l'argent réel

Les documents publiés à l'intention des opérateurs le disent sans détour. L'API de portefeuille de Hub88 indique que la validité du token ne doit pas être vérifiée pour les gains et les rollbacks, puisqu'ils peuvent arriver après que la mise a été jouée. VeliGames indique que l'opérateur n'a pas le droit de rejeter le gain d'un tour de jeu, même si la session a expiré.

Callbacks de solde : chaque appel peut arriver deux fois

Tout appel entre deux serveurs peut tomber en timeout après que le travail a été effectué de l'autre côté. Le fournisseur ne peut pas distinguer un débit qui a échoué d'un débit dont la réponse s'est perdue, si bien qu'il répète l'appel ou annule la transaction. Le rôle du portefeuille est de rendre les deux sans risque.

Les documents d'intégration publiés montrent à quel point les répétitions sont persistantes. L'API de portefeuille opérateur de Hub88 considère une mise comme échouée lorsqu'elle ne reçoit pas de HTTP 200, génère un rollback et réessaie ce rollback jusqu'à 500 fois avec un backoff exponentiel. Gamomat réessaie deux fois une requête échouée, à 500 ms d'intervalle, puis lance un rollback et le réessaie à des intervalles croissants, d'une seconde à 30 minutes. Chez Tom Horn Gaming, le timeout du portefeuille est de 10 secondes, après quoi un rollback est envoyé automatiquement. Un portefeuille indisponible pendant quelques minutes retrouve à son retour une file de répétitions et de rollbacks, pas le silence.

• La clé d'idempotence est l'ID de transaction du fournisseur, cloisonné par fournisseur et par type d'appel, car deux fournisseurs peuvent émettre le même ID et certains envoient un rollback sous l'ID de la mise ; une contrainte d'unicité sur cette clé transforme un appel répété en lookup
• Un débit répété ne déplace jamais d'argent une seconde fois, et le même ID qui arrive avec un montant ou un tour de jeu différent est une erreur, pas une nouvelle mise
• Un débit verrouille la ligne du compte, vérifie les fonds et les limites et passe son écriture au grand livre dans une seule transaction courte, si bien que deux spins concurrents sur un même compte ne peuvent pas dépenser tous les deux le même argent
• Un rollback désigne la transaction qu'il annule : un débit appliqué est extourné une seule fois, et un rollback déjà traité renvoie son résultat stocké
• Un rollback portant sur une transaction que le portefeuille n'a jamais reçue est enregistré et reçoit en réponse le code documenté par le fournisseur, si bien qu'un original retardé qui arrive ensuite est refusé au lieu de faire payer au joueur une mise que le fournisseur a déjà annulée
• Les erreurs sont mappées vers les propres codes de chaque fournisseur, car les fournisseurs réagissent différemment à des fonds insuffisants, à une session expirée et à un échec générique : certains arrêtent le jeu, d'autres réessaient, d'autres annulent

La réponse attendue à une répétition n'est pas standard non plus. Hub88 exige que les requêtes portant le même ID de transaction ne soient pas traitées deux fois et que la réponse soit la même pour tous les doublons ; VeliGames demande une erreur avec HTTP status 409 et DUPLICATE_TRANSACTION ; Tom Horn Gaming a un code de résultat distinct pour une référence en double. L'adaptateur répond à chaque fournisseur sous la forme propre à celui-ci, et le grand livre sous-jacent reste le même.

Les fournisseurs énoncent cette règle dans leurs propres documents. L'API opérateur de St8 indique que lorsque l'opérateur reçoit, pour une annulation, un ID de transaction qu'il n'a pas traité auparavant, cet ID doit être enregistré afin d'empêcher qu'il ne soit traité plus tard. Tom Horn Gaming attend son code de résultat pour transaction inconnue lorsque le portefeuille n'a jamais traité le retrait auquel se rapporte un rollback.

Les tours de jeu se clôturent à leur propre rythme

Un tour de jeu est l'unité de jeu du fournisseur, et il correspond rarement à une seule transaction. Un spin de machine à sous, c'est souvent un débit et un crédit, parfois envoyés en un seul appel. Le blackjack peut ajouter des débits pour un split ou un doublement. La roulette en direct prend les mises de nombreux joueurs pendant une fenêtre de mise et les règle toutes quand le résultat est connu. Les tours gratuits peuvent produire une série de gains qui vont ensemble.

• Stockez l'ID de tour de jeu du fournisseur avec chaque écriture au grand livre, et gardez l'état du tour de jeu séparément : ouvert, clôturé ou annulé
• Clôturez un tour de jeu sur le propre signal du fournisseur, un appel explicite de fin de tour de jeu ou un flag final là où l'API en a un, et sinon selon une règle documentée par fournisseur
• Laissez les tours de jeu survivre aux sessions : un joueur qui se déconnecte au milieu d'un tour de jeu en reçoit quand même le résultat, souvent longtemps après l'expiration du token de session
• Surveillez les tours de jeu ouverts par âge et par fournisseur ; un nombre croissant de tours de jeu ouverts depuis longtemps révèle une intégration cassée bien avant qu'un joueur ne se plaigne

C'est avec l'historique des tours de jeu que se tranche un litige avec un joueur. Conservez chaque écriture au grand livre avec le fournisseur, le jeu, le tour de jeu, les montants, le solde avant et après, et deux horodatages, celui du fournisseur et celui du portefeuille, et reliez-y les propres détails de tour de jeu du fournisseur là où son API les propose. Avec cela, une question sur l'argent d'un spin trouve sa réponse dans les enregistrements.

Les régulateurs fixent le minimum que cet historique doit couvrir. GLI-19, la norme de Gaming Laboratories International pour les systèmes de jeu interactif, exige une fonction de rappel de jeu pour le joueur, soit sous forme de reconstitution, soit par description. Les normes techniques relatives au jeu à distance de la Commission britannique des jeux d'argent (UK Gambling Commission) exigent au moins trois mois d'historique du compte et de jeu accessibles sans contacter le titulaire de la licence, et au moins 12 mois sur demande. La directive de l'Autorité maltaise des jeux (Malta Gaming Authority) sur la protection des joueurs donne au joueur accès à son historique de jeu sur les six mois immédiatement précédents.

Le croupier en direct transforme le portefeuille en rafale

Les machines à sous étalent la charge dans le temps, car chaque joueur lance ses spins à son propre rythme. Les tables avec croupier en direct synchronisent les joueurs : les mises de tous les joueurs d'une table arrivent dans les secondes qui précèdent la clôture des mises, et les gains de tous arrivent ensemble quand le résultat est connu. Une table populaire répète cela pour chaque joueur qui a misé.

• Gardez chaque transaction du portefeuille courte et limitée à un seul compte, pour que la rafale d'une table ne sérialise que les comptes de cette table
• Répondez au callback et faites le reste ensuite : le wagering des bonus, les points de fidélité et l'analytique lisent l'événement du grand livre après le commit, et non à l'intérieur de l'appel
• Testez en charge la rafale de résultats elle-même, dimensionnée pour la table la plus chargée attendue, pendant que les autres jeux continuent d'envoyer des mises

Un seul contrat interne, de nombreux adaptateurs

C'est dans les adaptateurs que vivent les différences entre fournisseurs, et ce devrait être le seul endroit où elles vivent. Chaque adaptateur gère :

• L'authentification des callbacks entrants, comme les signatures de requête ou les adresses sources autorisées, selon ce que spécifie le fournisseur
• Les formats de montant : des entiers à échelle fixe dans certaines API, des valeurs décimales dans d'autres, et les devises que prend en charge un fournisseur
• Le mapping des champs et des codes d'erreur vers le contrat interne
• L'import du catalogue de jeux et des paramètres de lancement
• Les tours gratuits via l'interface de bonus du fournisseur
• Les scénarios d'intégration du fournisseur, conservés ensuite comme tests de non-régression exécutés avant chaque release

Le contrat interne reste réduit : ouvrir une session, lire le solde, débiter, créditer, débiter et créditer en un seul appel, payer sans mise, faire un rollback, clôturer un tour de jeu, et un ensemble fixe d'erreurs que le portefeuille peut renvoyer. Un nouveau fournisseur, c'est alors un adaptateur et une suite de tests, rarement une modification du portefeuille.

Réconciliation : le rapport du fournisseur est un second grand livre

Chaque fournisseur tient son propre enregistrement de chaque tour de jeu et facture l'opérateur à partir de celui-ci. Le grand livre de la couche d'agrégation, c'est le même argent vu du côté de l'opérateur. Réconciliez les deux chaque jour, selon la limite de journée et le fuseau horaire de chaque fournisseur, par fournisseur, par devise et par jeu :

• Les totaux d'abord : les mises, les gains et l'écart entre les deux sur la journée
• Puis les transactions : les écritures qui n'existent que d'un seul côté, et les montants qui diffèrent
• Résolvez chaque écart à l'aide de l'historique des tours de jeu, et suivez le nombre d'écarts comme un chiffre qui devrait rester proche de zéro plutôt que comme un travail de correction mené discrètement

La durée pendant laquelle ces preuves doivent être conservées fait partie de l'intégration. Hub88 demande que chaque ID de transaction soit stocké des deux côtés pendant au moins quatre mois à des fins de réconciliation, et l'API opérateur de Gamomat renvoie des données de réconciliation pour une plage de dates ou pour un seul tour de jeu.

Ce qu'il faut mesurer avant que le premier fournisseur ne passe en production

• La latence des callbacks par fournisseur et par type d'appel, au p99 plutôt qu'en moyenne
• Les appels répétés, et les ID répétés qui arrivent avec un payload différent
• Les rollbacks, et les rollbacks portant sur des transactions que le portefeuille n'a jamais reçues
• Les tours de jeu ouverts par âge
• Les débits refusés par motif : fonds, limites, session ou erreur
• Les écarts de réconciliation quotidiens par fournisseur

Quelles sociétés construisent des couches d'agrégation de fournisseurs de jeux pour les opérateurs ?

La question appelle trois types de réponse, et ils vendent des choses différentes. Les agrégateurs et les éditeurs de plateformes louent leur couche à l'opérateur : un seul contrat, de nombreux fournisseurs, leurs conditions commerciales. Les plateformes clé en main et en marque blanche incluent la couche dans une plateforme qui appartient au prestataire. Les prestataires d'ingénierie construisent la couche dans le backend de l'opérateur, et l'opérateur signe lui-même ses contrats avec les fournisseurs.

Quel que soit le type d'acteur auquel vous vous adressez, ces questions montrent si une équipe a déjà construit cela :

• Que fait le portefeuille d'un rollback portant sur une transaction qu'il n'a jamais reçue ?
• Comment empêche-t-on les ID de transaction de deux fournisseurs d'entrer en collision ?
• Comment un tour de jeu qui se clôture après sa session est-il enregistré et montré au joueur ?
• Quels fournisseurs ont-ils intégrés via un seamless wallet, et lesquels via des transferts ?
• Comment mènent-ils la réconciliation avec les rapports des fournisseurs, et à quoi ressemble un écart quotidien normal ?
• À qui appartiennent le code des adaptateurs et le contrat interne quand le travail prend fin, et quelles parties restent des composants réutilisables du prestataire ?

Une réponse qui reste générale sur les deux premières signifie que les cas limites seraient découverts en production.

Est-ce qu'amBrain intègre des fournisseurs de jeux pour les opérateurs de casino ?

amBrain est une société de développement logiciel spécialisée dans les plateformes de trading, les matching engines, les systèmes de real-time bidding et l'ingénierie de plateformes de casino. amBrain développe des logiciels depuis 2019.

En iGaming, les chiffres qu'amBrain publie comme mesurés sont ceux de 500+ intégrations de fournisseurs tiers et de 12 opérateurs en production.

amBrain travaille en trois formats : la prestation complète, une équipe dédiée ou des ingénieurs intégrés à votre équipe. Le client conserve la pleine propriété du produit et du code, à l'exception des composants réutilisables d'amBrain.

Cet article explique comment fonctionne une couche d'agrégation ; ce n'est pas une étude de cas, et il ne nomme aucun client.

La première décision n'est donc pas de savoir quels fournisseurs signer. C'est le contrat interne auquel chaque fournisseur sera adapté, mis par écrit avec ses cas d'erreur avant que le premier adaptateur n'existe.