Product API Portefeuille unique ou portefeuille de transfert
Portefeuille unique ou portefeuille de transfert
Une comparaison technique des deux modèles de wallet utilisés pour relier le solde joueur d'un opérateur à une API de jeux de casino : qui détient l'argent, quels appels traversent le réseau pendant une mise, comment les incidents sont rattrapés et ce que vous devez construire de votre côté.
En bref
| Aspect | Portefeuille unique | Portefeuille de transfert |
|---|---|---|
| Garde du solde | Votre base de données détient le seul solde. Le fournisseur ne conserve jamais les fonds des joueurs. | Le fournisseur garde un solde de jeu séparé. Les fonds entrent et sortent par des appels de transfert. |
| Appels pendant une mise | Chaque mise et chaque gain déclenchent un callback serveur à serveur vers vous (balance, debit, credit, rollback). | Aucun. Le jeu tourne sur le solde côté fournisseur. Les appels n'ont lieu qu'aux transferts entrants et sortants. |
| Disponibilité requise | Vos endpoints wallet doivent répondre à chaque callback, normalement en quelques centaines de millisecondes. S'ils sont indisponibles, le jeu s'arrête. | Requise uniquement pour les transferts. Les tours continuent si votre système est brièvement hors ligne. |
| Modèle de cohérence | Votre registre est la source de vérité en temps réel. Seuls les tours de jeu demandent un rapprochement, pas les soldes. | Deux registres qui ne concordent qu'aux transferts. Demande un rapprochement au niveau des transferts. |
| Reprise après incident | Les timeouts se règlent par des relances idempotentes et des appels de rollback indexés par ID de transaction. | Les transferts sont en deux phases : en attente, puis succès ou échec. Une requête de statut tranche les résultats inconnus. |
| Effort d'intégration | Plus élevé. Vous construisez et exploitez un service de callback à faible latence, avec idempotence et registre. | Plus faible. Vous appelez trois ou quatre endpoints REST, sans trafic entrant à sécuriser ni à dimensionner. |
| Expérience joueur | Un seul solde, pas d'étape de transfert. Idéal pour les bonus, le jeu multi-produits et l'affichage du solde en direct. | Les fonds sont transférés avant le jeu et récupérés après. Cela ajoute un court délai et un risque de solde bloqué si le joueur quitte en cours de session. |
| Profil type | Opérateurs disposant de leur propre wallet ou plateforme et d'un contrôle strict des fonds et des promotions. | Opérateurs qui veulent un lancement rapide ou n'ont pas de service wallet en temps réel. |
Portefeuille unique (seamless)
Dans le modèle portefeuille unique (seamless), votre système est le wallet. Quand un joueur mise, l'API SSG appelle votre endpoint de callback, vous modifiez le solde dans votre propre registre et vous répondez avec le nouveau solde. Aucun fonds ne quitte jamais votre base de données.
Flux d'appels
- Lancement : votre backend demande à SSG une URL de jeu avec un ID joueur et un jeton de session.
- Mise : pour chaque tour, SSG appelle debit avec un txId unique. Vous vérifiez les fonds, écrivez la ligne du registre et renvoyez le nouveau solde.
- Gain : SSG appelle credit avec le gain (qui peut être nul) pour le même tour.
- Incident : si un appel expire, SSG relance avec le même txId, puis envoie rollback une fois la limite de relances atteinte.
Méthodes de callback (illustratif)
| Méthode | Rôle | Champs clés | Idempotent |
|---|---|---|---|
balance | Renvoyer le solde actuel du joueur. | playerId, currency | Oui (lecture seule) |
debit | Placer une mise : soustraire le montant. | playerId, txId, roundId, gameId, amount, currency | Par txId |
credit | Régler un gain : ajouter le montant. | playerId, txId, roundId, amount, currency | Par txId |
rollback | Annuler un debit ou un credit précédent après une erreur. | txId, refTxId | Par txId |
Exemple de requête debit
{
"method": "debit",
"playerId": "p_839201",
"txId": "tx_20261007_000184",
"roundId": "r_77f3a1",
"gameId": "slots_fruit_01",
"currency": "MYR",
"amount": "2.50",
"ts": 1791338577,
"sign": "hex(HMAC-SHA256(secret, canonical))"
}Exemple de réponse
{
"status": "OK",
"txId": "tx_20261007_000184",
"balance": "97.50",
"currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
// DUPLICATE_TX (return original result), INTERNAL_ERRORRègles que votre service wallet doit respecter
- Idempotence
- Un debit ou credit répété avec le même txId doit renvoyer le résultat initial sans déplacer l'argent une seconde fois. Imposez-le avec un index unique sur txId.
- Écriture atomique du registre
- Vérifiez le solde, insérez la ligne du registre et mettez à jour le solde dans une seule transaction de base de données, pour que deux mises simultanées ne puissent jamais créer de découvert.
- Rollback avant debit
- Un rollback peut arriver pour un txId jamais vu, parce que le debit initial a expiré. Stockez une marque (tombstone) pour qu'un debit tardif avec ce txId soit rejeté.
- Budget de latence
- Visez un p99 sous 500 ms réseau compris. Limitez le chemin du callback à une lecture indexée et une écriture, et sortez-en les requêtes de reporting.
- Format monétaire
- Traitez les montants comme des chaînes décimales ou des unités mineures entières. N'utilisez jamais de virgule flottante et validez la devise par rapport au compte joueur.
- Bonus et free spins
- Un free spin est un debit de 0 suivi d'un credit du gain. Séparez les soldes promotionnels du solde réel dans votre registre.
- Sécurité
- Vérifiez une signature HMAC-SHA256 sur la requête canonique, rejetez les horodatages périmés, mettez les IP sources SSG en liste blanche et exigez TLS 1.2 ou supérieur.
- Rapprochement
- Comparez par roundId les rapports quotidiens des tours SSG avec votre registre. Les écarts signalent des callbacks ou rollbacks manqués.
Portefeuille de transfert
Dans le modèle portefeuille de transfert, le fournisseur garde un solde de jeu pour chaque joueur. Votre backend transfère les fonds avant le jeu et les récupère ensuite. Pendant le jeu, aucun callback n'arrive sur votre système : seuls des appels REST sortants sont nécessaires.
Flux d'appels
- Transfert entrant : votre backend appelle transferIn avec un txId unique et le montant. Le résultat est PENDING ou SUCCESS.
- Jeu : lancez la partie. Toutes les mises et tous les gains modifient le solde côté fournisseur, sans callback vers vous.
- Transfert sortant : quand le joueur part, appelez transferOut pour la totalité du solde et recréditez-le dans votre registre sur SUCCESS.
- Résultat inconnu : si un appel de transfert expire, interrogez getTransferStatus avec le même txId avant toute autre action.
Méthodes API (illustratif)
| Méthode | Rôle | Champs clés | Idempotent |
|---|---|---|---|
transferIn | Transférer des fonds de votre wallet vers le solde de jeu du joueur. | playerId, txId, amount, currency | Par txId |
transferOut | Ramener des fonds du solde de jeu vers votre wallet. | playerId, txId, amount | all | Par txId |
getBalance | Lire le solde de jeu du joueur. | playerId | Oui (lecture seule) |
getTransferStatus | Renvoyer PENDING, SUCCESS ou FAILED pour un txId. | txId | Oui (lecture seule) |
Règles que votre backend doit respecter
- Un txId par intention
- Générez le txId avant le premier appel et réutilisez-le à chaque relance. Ne créez jamais de nouveau txId tant que le statut du précédent n'est pas connu.
- Débitez d'abord votre registre
- Pour un transfert entrant, réservez le montant dans votre registre avant d'appeler SSG, puis confirmez-le ou libérez-le quand le statut est définitif.
- Récupérer les soldes bloqués
- Lancez une tâche qui repère les joueurs ayant un solde de jeu sans session active, puis le transfère en sortie. Cela couvre les joueurs qui ferment le navigateur en cours de session.
- Mises et rapports
- Comme vous ne voyez aucune mise en direct, calculez le chiffre d'affaires, les conditions de mise des bonus et les limites de risque à partir des rapports de tours récupérés chez SSG, pas des callbacks.
- Rapprochement
- Rapprochez chaque transfert entrant et sortant des enregistrements SSG par txId, et alertez sur tout PENDING plus ancien que votre timeout.
- Sécurité
- Signez les requêtes en HMAC-SHA256, appelez uniquement via TLS 1.2 ou supérieur, gardez les clés API dans un coffre de secrets et limitez les serveurs autorisés à appeler SSG.
Scénarios d'incident
| Scénario | Portefeuille unique | Portefeuille de transfert |
|---|---|---|
| Timeout réseau | Pendant une mise, SSG relance le même txId, puis envoie rollback après la limite de relances. Vous devez être idempotent. | Seuls les transferts sont concernés. Interrogez getTransferStatus avec le même txId, puis agissez. |
| Votre système est indisponible | Les joueurs ne peuvent ni lancer ni poursuivre de tours. Les tours ouverts sont annulés. | Les joueurs continuent avec leur solde de jeu existant. Les nouveaux transferts sont bloqués. |
| Requête en double | Renvoyer la réponse stockée pour ce txId sans rien modifier. | Renvoyer le résultat stocké pour ce txId sans rien modifier. |
| Le joueur se déconnecte en plein tour | Le tour se termine chez le fournisseur et le credit est envoyé normalement. | Le tour se termine et les fonds restent sur le solde de jeu jusqu'à un transfert sortant ou la tâche de récupération. |
| Écart de solde | En général un callback ou un rollback manqué. Détecté en comparant les rapports de tours par roundId. | En général un transfert bloqué ou en attente. Détecté en comparant les transferts par txId. |
Lequel choisir
Choisissez le portefeuille unique si
- Vous exploitez déjà un service wallet ou registre en temps réel.
- Vous avez besoin d'un solde unique pour les paris sportifs, le casino et les promotions.
- Vous avez besoin des mises en direct pour le risque, les conditions de bonus ou les limites de jeu responsable.
- Votre équipe peut exploiter un service à faible latence et haute disponibilité.
Choisissez le portefeuille de transfert si
- Vous voulez lancer vite avec le moins de développement possible.
- Vous n'avez pas encore de service wallet en temps réel.
- Vous préférez uniquement des appels sortants, sans callback public à sécuriser.
- De courtes fenêtres de solde bloqué sont acceptables et vous pouvez exécuter une tâche de récupération.
Beaucoup d'opérateurs démarrent en portefeuille de transfert pour lancer, puis passent au portefeuille unique quand leur propre service wallet est prêt. Demandez-nous comment la bascule est organisée.
Checklist d'intégration
- Index unique sur txId et handlers idempotents pour chaque appel qui déplace de l'argent
- Vérification de signature HMAC, tolérance d'horodatage et liste blanche d'IP
- Montants en décimal sûr et validation de la devise
- Tests de timeout, relance et rollback en sandbox, y compris une relance tardive
- Tâche de rapprochement quotidienne par roundId (unique) ou txId (transfert)
- Supervision et alertes : latence des callbacks, taux d'erreur, transferts en attente, soldes bloqués
Parler à un ingénieur intégration
Nous pouvons guider vos ingénieurs dans la sandbox et vous aider à choisir le modèle adapté à votre plateforme. Intégration garantie en moins de sept jours.
Écrire aux ventes Discuter sur Telegram Retour à Product API
sales@ssggaming.com