Checklist per l'integrazione API di un casinò: cosa costruire, testare e monitorare prima del go-live

Ultima verifica 2026-10-09

Un'integrazione API di giochi da casinò si rompe sempre negli stessi punti: un addebito ritentato e incassato due volte, un rollback per una puntata mai vista, una valuta con tre decimali. Questa checklist attraversa ogni livello nell'ordine in cui lo incontra uno sviluppatore, indicando il guasto che ogni controllo previene.

Questa checklist per l’integrazione API di un casinò è per lo sviluppatore che ha in mano le chiavi API e una scadenza. Segue l’ordine in cui le cose si incontrano nella pratica: prima il contratto tra il vostro wallet e il provider, poi la lobby, poi il lancio, infine i test e la prima settimana online.

Ogni voce esiste perché senza di lei qualcosa si rompe. Spuntatele in un documento condiviso e girate quelle aperte al team di integrazione del fornitore sotto forma di domande.

0. Prima della prima riga di codice

• Avete la documentazione API completa, non un PDF commerciale: ogni endpoint, ogni codice di errore, payload di esempio.
• Conoscete il modello di wallet. Seamless (il provider chiama il vostro server a ogni puntata e vincita) o transfer (spostate i soldi su un saldo lato provider). Questa checklist dà per scontato il seamless, che è ciò che vende quasi ogni aggregatore.
• Credenziali e URL di callback di staging sono separati da quelli di produzione.
• La firma delle richieste è chiara: quale header, quale algoritmo (di solito HMAC-SHA256), quali campi sono firmati e in quale ordine.
• Conoscete gli indirizzi IP in uscita del provider, se vuole che li mettiate in allow-list.
• Avete un referente tecnico con nome e cognome e un canale che risponde nel giro di ore.

1. Callback del wallet

Il provider chiamerà il vostro server per quattro cose. Costruitele prima di tutto il resto.

• Saldo. Restituisce il saldo spendibile attuale del giocatore, nella sua valuta.
• Addebito (puntata). Sottrae la puntata se i fondi bastano e restituisce il nuovo saldo. I fondi insufficienti restituiscono il codice di errore documentato, non un 500.
• Accredito (vincita). Aggiunge la vincita. Un accredito a zero è valido e deve andare a buon fine; molti studi lo inviano per chiudere un round perso.
• Rollback (rimborso). Annulla uno specifico addebito precedente.
• Ogni risposta è firmata o validata come richiede la documentazione.
• Verificate la firma in ingresso a ogni chiamata e respingete quelle non valide con il codice documentato.
• Il vostro endpoint risponde ben dentro il timeout del provider. Il numero è nella documentazione. Se dice 3 secondi, puntate a meno di 300 ms al 99° percentile.
• Gli importi sono salvati come interi in unità minori o come decimali a virgola fissa. Mai come float.
• Addebito e accredito portano un ID round e un ID gioco. Salvateli entrambi.

Scenario. Un giocatore con una connessione mobile lenta fa uno spin. Il vostro addebito va a buon fine, ma la risposta impiega 4 secondi e il provider si arrende a 3. A quel punto il provider invia un rollback, o ritenta l’addebito, secondo le sue regole. Le sezioni 2 e 3 esistono per questo momento.

2. Idempotenza

• Nella tabella delle transazioni c’è un vincolo di unicità sull’ID transazione del provider.
• Un addebito o accredito ripetuto con lo stesso ID transazione non muove di nuovo denaro. Restituisce la risposta originale, con gli stessi valori di saldo.
• Una chiamata ripetuta con lo stesso ID ma un importo diverso viene respinta e registrata con un allarme ben visibile. È un bug del provider o un attacco.
• Variazioni di saldo e inserimento delle transazioni avvengono in un’unica transazione di database. Nessuna finestra in cui esiste l’una senza l’altra.
• Le chiamate concorrenti per lo stesso giocatore vengono serializzate (lock di riga o equivalente). Due addebiti simultanei da due schede di gioco aperte non devono passare entrambi su un saldo che ne copre uno solo.

3. Rollback

• Un rollback fa riferimento all’addebito che annulla. Cercatelo tramite l’ID transazione del provider.
• Rollback per un addebito mai ricevuto: registratelo come “tombstone” e restituite esito positivo (o il codice documentato). Se l’addebito arriva dopo, il tombstone vi impedisce di incassarlo.
• Un rollback per un addebito già annullato restituisce la risposta originale.
• Rollback di un addebito il cui round ha già una vincita: seguite la documentazione alla lettera. Alcuni provider lo vietano, altri si aspettano che annulliate entrambi.
• I rollback non portano mai un saldo in uno stato inspiegabile. Se potessero mandarlo in negativo, decidete la regola adesso e mettetela per iscritto.

4. Round e partite non concluse

• Riuscite a vedere quali round sono aperti (addebito ricevuto, nessun accredito di chiusura).
• Sapete come il provider chiude i round rimasti appesi: accredito automatico dopo un timeout, uno strumento manuale o un ticket al supporto.
• Le vincite da bonus e free round sono etichettate, così la vostra logica bonus le tratta diversamente dalle vincite in denaro.
• Il vostro back office mostra lo storico completo dei round per giocatore: ogni chiamata, ogni risposta, con orario.

5. Valute

• Ogni giocatore ha una sola valuta fissa, impostata alla registrazione, inviata al lancio e ripetuta in ogni callback.
• Verificate che la valuta della callback coincida con quella del giocatore e respingete le discrepanze.
• I decimali sono corretti per ciascuna valuta. Quasi tutte le valute fiat ne usano due, alcune zero, altre tre. Le crypto possono usarne otto o più; concordate con il fornitore la precisione usata nelle chiamate.
• Ogni gioco che mostrate supporta davvero la valuta in cui lo mostrate. Uno studio può supportare EUR e USD ma non BDT o ETB.
• I limiti di puntata per valuta hanno senso. Una puntata minima piccola in EUR può risultare strana in IDR o enorme in BTC.
• Valuta di visualizzazione e valuta di liquidazione non si confondono nei report.

6. Sincronizzazione della lista giochi

• La lista dei giochi viene scaricata dall’API a intervalli regolari, almeno una volta al giorno, e salvata in locale.
• I giochi disattivati o rimossi spariscono dalla lobby alla sincronizzazione successiva, non il trimestre successivo.
• Se fate curation, i giochi nuovi entrano in uno stato di revisione, non direttamente in lobby.
• Salvate l’ID stabile del gioco fornito dal provider, non il nome. I nomi cambiano.
• Le immagini sono in cache sul vostro lato o servite in un formato adatto al mobile.
• Ogni gioco porta con sé categoria, studio, dispositivi e valute supportati, così i filtri della lobby non mentono.
• Gli studi disattivati per un mercato vengono filtrati dalle vostre regole, non lasciati al caso.

7. URL di lancio

• Il lancio in denaro reale passa un token di sessione a breve scadenza legato al giocatore. Mai una password o un ID riutilizzabile.
• La scadenza del token è gestita: una scheda vecchia mostra un messaggio chiaro, non un frame rotto.
• Lingua, valuta, tipo di dispositivo e URL di ritorno alla lobby sono impostati al lancio.
• Dove il gioco lo supporta viene passato un URL di deposito o di cassa, così “fondi insufficienti” porta da qualche parte.
• Il gioco si apre correttamente sia in un iframe sia in una nuova finestra. Alcuni studi bloccano gli iframe su certi domini o browser.
• I lanci in modalità demo, se previsti, non toccano mai il wallet reale. Testatelo in modo esplicito.
• Il tempo dal clic al primo frame è misurato su uno smartphone di fascia media in 4G. Oltre i 5 secondi si perdono giocatori.

8. Test

• Un giocatore di test per ogni valuta che supporterete.
• Un round completo per tipo di gioco: slot, tavolo live, crash, gioco da tavolo, virtuale.
• Guasti forzati: il vostro server restituisce un timeout, un 500, un codice di fondi insufficienti. Osservate cosa fa poi il provider.
• Chiamate doppie rilanciate a mano: addebito due volte, accredito due volte, rollback due volte.
• Chiamate fuori ordine: rollback prima dell’addebito, accredito dopo il rollback.
• Due schede, stesso giocatore, spin in contemporanea.
• Scadenza della sessione a metà partita.
• Una vincita grossa e una vincita a zero.
• Il vostro report di riconciliazione coincide con quello del provider per il periodo di test, al centesimo.

9. Go-live

• Chiavi e URL di callback di produzione sostituiti, staging disattivato per i giocatori reali.
• Monitoraggio su latenza delle callback, tasso di errore e firme non valide, con allarmi che arrivano a una persona, non a una dashboard che nessuno apre.
• Job di riconciliazione giornaliero: i vostri totali per gioco e per valuta contro quelli del provider.
• Nei modelli prepagati, un avviso di credito basso ben sopra lo zero, e qualcuno che possa ricaricare anche di domenica.
• Un interruttore di emergenza per gioco e per studio nel vostro back office.
• Canale di supporto del fornitore e contatto di escalation scritti nel vostro runbook.

10. I primi sette giorni

• Controllate la riconciliazione ogni mattina.
• Esaminate tutte le callback respinte e i round aperti.
• Tenete d’occhio gli errori di lancio per studio; un solo studio problematico può affossare una lobby.
• Chiedete al fornitore i suoi log degli errori e confrontateli con i vostri.

Un team piccolo che lancia un brand crypto può completare questa lista in una settimana, se la documentazione del fornitore è solida. Se è scarna, la lista diventa anche un buon test del fornitore: contate su quante voci avete dovuto fare domande. La classifica dei seamless wallet e la pagina sugli aggregatori per nuovi operatori valutano i fornitori proprio su questo tipo di lavoro di integrazione.