Documentazione di Steamworks
Guida all'implementazione delle microtransazioni

Introduzione

Grazie al suo sistema di pagamento in gioco, Steam vuole fornire agli sviluppatori un modo semplice per vendere ogni genere di articolo agli utenti, senza che questi debbano mai abbandonare il gioco. La scelta degli articoli da vendere è lasciata completamente al commerciante. Può trattarsi di oggetti di gioco come armi o munizioni, valuta di gioco come oro o monete, o addirittura vestiti per il personaggio del giocatore. Puoi rendere disponibili tutti gli oggetti che desideri all'interno del gioco, scegliendo di venderli singolarmente o in pacchetti. Steam non applica restrizioni a ciò che è consentito vendere o alla modalità di vendita, né preclude l'uso di qualunque altro meccanismo impiegato nel tuo gioco per la vendita degli oggetti. Lo scopo è quello di portare nel gioco l'esperienza di pagamento con cui l'utente ha già acquisito familiarità dalla piattaforma di Steam, consentendo così ai giocatori di utilizzare in modo semplice i fondi del Portafoglio di Steam per acquistare i tuoi prodotti. Utilizzando questo tipo di integrazione, il tuo gioco avrà accesso immediato ai nuovi utenti di Steam e ai metodi di pagamenti che vengono aggiunti.

Grazie a questo sistema, l'acquisto è completamente sotto il tuo controllo. Una richiesta d'acquisto andata a buon fine comporterà l'addebito dell'importo corretto all'utente e la ricezione di una notifica immediata sull'esito positivo dell'evento. Quando un acquisto viene approvato, spetta a te assegnare e gestire gli oggetti. Ad esempio, se un oggetto è associato a un periodo di validità, dovrà essere il tuo sistema a stabilire per quanto tempo sarà disponibile.

Oltre agli acquisti in gioco, il sistema mette a disposizione funzionalità aggiuntive che i tuoi sistemi di contabilità e assistenza possono sfruttare:
  1. Puoi ricevere una notifica se i pagamenti non vanno a buon fine.
  2. Puoi emettere rimborsi e richiedere lo stato delle transazioni tramite il servizio web.
  3. Avrai accesso a rapporti dettagliati nella pagina delle statistiche sul sito dei partner di Steamworks, con dati in tempo reale sulla vendita di oggetti e giochi.

Pratiche consigliate per gli acquisti in gioco

Se hai intenzione di offrire la funzionalità degli acquisti nel tuo gioco su Steam, di seguito puoi trovare alcuni suggerimenti, pratiche consigliate e risorse per iniziare. Che siano Free-to-Play o a pagamento, tutti i titoli che offrono acquisti in gioco presentano elementi comuni da considerare durante la preparazione del prodotto al rilascio su Steam.

Per suggerimenti sulle economie di gioco e le pratiche consigliate, consulta la seguente documentazione: Microtransazioni (acquisti in gioco).

Come funziona il sistema di pagamento

Il sistema di pagamento è la combinazione del processo di acquisto implementato nel tuo gioco, del servizio web di fatturazione di Steam e di una procedura di approvazione del cliente.

Il processo di acquisto segue le fasi indicate di seguito. L'utente avvia e termina l'acquisto senza mai uscire dal gioco.
  1. Quando un utente desidera acquistare un oggetto nel gioco, questo invierà una richiesta di acquisto al tuo server dedicato. Tale server può essere qualsiasi entità che eroga il servizio di gestione delle richieste di acquisto per il tuo gioco, come un server web o un sistema di autenticazione. Il server dovrà comunicare via HTTP con i server di fatturazione di Steam, a cui potrà richiedere anche il Paese, la lingua e la valuta dell'utente. Puoi utilizzare questi dati per regolare il prezzo in base alle esigenze.
  2. Il tuo server degli acquisti inizializza quindi una transazione di pagamento per conto del client al servizio web di Steam. La richiesta HTTP è sicura e utilizza il metodo POST. I contenuti della richiesta includono i metadati dell'utente e la descrizione e il costo di ogni oggetto che l'utente desidera acquistare.
  3. Al momento della ricezione della richiesta, Steam attiverà automaticamente l'Overlay e mostrerà all'utente una finestra con l'elenco di tutti gli oggetti, il relativo costo e un pulsante per confermare o autorizzare la transazione. Se l'utente non dispone di denaro sufficiente nel suo account di Steam, l'Overlay lo guiderà attraverso una procedura per l'aggiunta di fondi. L'Overlay di Steam gestisce la raccolta di tutte le informazioni di fatturazione dell'utente. Al termine dell'operazione, l'utente riceverà una notifica indicante che l'acquisto è stato autorizzato o negato. Il gioco deve essere registrato per ricevere la callback della notifica e inoltrare l'esito al server degli acquisti.
  4. Il server degli acquisti riceve la notifica ed effettua una chiamata a FinalizeTxn per completare l'operazione. Se l'operazione di acquisto è andata a buon fine, all'utente verrà addebitato l'importo e il gioco potrà procedere all'assegnazione dell'oggetto.

In alternativa, puoi optare per un'integrazione su browser per i giochi le cui opzioni di acquisto sono disponibili tramite una pagina web o se desideri offrire Steam come metodo di pagamento direttamente sul tuo sito web. In questo caso, il processo di acquisto segue le fasi indicate di seguito:
  1. L'utente desidera acquistare un articolo nel gioco o sul tuo sito web. Se si tratta di un acquisto in gioco, sarà necessario aprire la tua pagina web su un browser.
  2. Il server degli acquisti inizializza una transazione web per conto dell'utente sotto forma di richiesta HTTP sicura che utilizza il metodo POST. In caso di esito positivo, verrà restituito un URL unico di Steam a cui reindirizzare la sessione del browser dell'utente e da cui sarà possibile autorizzare la transazione. In questa fase, specifica anche un URL di ritorno a cui reindirizzare l'utente al completamento dell'autorizzazione.
  3. Quando l'utente viene reindirizzato al tuo sito, il server degli acquisti richiederà lo stato della transazione. Se l'autorizzazione è andata a buon fine, potrai acquisire i fondi con una chiamata a FinalizeTxn.

Stabilire una connessione

Prerequisiti

Crea innanzitutto una chiave dell'API web da editore. Puoi trovare le istruzioni nella seguente documentazione: Autenticazione attraverso le chiavi dell'API web. Questa chiave è inclusa in tutte le richieste al server web e viene utilizzata per autenticarle. La chiave deve essere inviata insieme ad ogni richiesta tramite il seguente parametro: key=<inserisci qui la tua chiave>.

Archiviazione dell'ordine

Archivia ogni ordine nel sistema per poterlo visualizzare in futuro. Utilizza un ID unico a 64 bit per identificare le transazioni su Steam.

Invio delle richieste

Tutte le richieste devono essere inviate utilizzando i metodi GET o POST del protocollo HTTP 1.1 tramite una connessione TLS sicura. Il "Content-Type" deve essere "application/x-www-form-urlencoded&quot e i parametri POST devono trovarsi nel corpo della richiesta nel formato standard di codifica degli URL per i moduli. Il testo deve essere inviato nel formato UTF-8.

Le richieste passano attraverso l'URI di base:
https://partner.steam-api.com/ISteamMicroTxn/*

Alcuni comandi restituiscono un esito positivo o negativo. In caso di esito negativo, alla risposta verranno aggiunti anche un codice di errore e una descrizione. Questi parametri non saranno presenti in caso di esito positivo.

Le risposte vengono inviate in formato JSON per impostazione predefinita. È possibile richiedere le risposte in formato XML aggiungendo il parametro "format=xml" alla richiesta.
Nota: è necessario implementare una soluzione JSON o XML flessibile che consenta l'invio e la restituzione dei parametri in ordine arbitrario.

Test dell'integrazione

Steam mette a disposizione degli sviluppatori una sandbox per il test dell'integrazione. La sandbox consente l'invio di tutte le richieste disponibili nell'API senza intaccare i fondi nel Portafoglio di Steam del tester.

La sandbox è accessibile tramite un URI di base diverso:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Processo di integrazione

Acquisti in gioco


Questa sezione è dedicata ai titoli con un negozio integrato che consente agli utenti di effettuare un acquisto senza dover uscire dal gioco.
  • Fase 1
    Il tuo gioco deve includere l'API di Steamworks. Ciò significa che il prodotto deve contenere un file di intestazione, essere collegato a un file LIB e integrare una DLL. Per ulteriori dettagli, consulta la seguente documentazione: Introduzione all'API di Steamworks. Prima di procedere, assicurati di inizializzare correttamente l'API di Steamworks!
  • Fase 2
    L'utente sceglie di acquistare uno o più oggetti all'interno del tuo gioco. Una volta identificati tali oggetti, il gioco raccoglie alcuni metadati dell'utente:
    • ID di Steam: questo numero a 64 bit identifica in modo univoco l'utente all'interno del sistema di Steam.
    • Codice nazionale: il codice nazionale ISO 3166 indica la posizione dell'utente al momento dell'acquisto. Utilizza questo codice per determinare il prezzo da applicare.
    • Codice valuta: il codice ISO 4217 della valuta con cui l'utente effettuerà l'acquisto.
    • Codice della lingua del gioco nel client: il codice ISO 639-1 della lingua usata dal gioco nel client di Steam.

    L'ID di Steam e la lingua possono essere ottenuti tramite le seguenti chiamate all'API di Steamworks:

    Per ottenere il Paese e la valuta dell'utente, effettua una richiesta all'API web ISteamMicroTxn/GetUserInfo passando l'ID di Steam dell'utente come parametro.

    I metadati dell'utente devono essere raggruppati e inviati al server degli acquisti insieme a tutti gli altri dati di acquisto.
  • Fase 3
    Il server degli acquisti inizializza una richiesta di acquisto per conto dell'utente tramite il servizio web di Steam. Utilizza il metodo ISteamMicroTxn/InitTxn descritto più avanti in questo documento. La richiesta deve includere i seguenti dati:
    • ID dell'ordine: un numero unico a 64 bit assegnato all'acquisto. Questo numero rappresenta la chiave della transazione e viene usato per risalire alla transazione nel sistema di Steam.
    • ID di Steam: l'ID dell'utente ricevuto dal client di Steam durante la fase 3.
    • AppID: l'identificatore unico del tuo gioco di Steam.
    • Lingua: il codice ISO 639-1 della lingua in cui sono elencati i tuoi oggetti.
    • Valuta: il codice ISO 4217 della valuta in cui sono elencati i prezzi. Se questo codice non corrisponde a quello della valuta dell'utente fornito durante la fase 2, l'importo sarà convertito automaticamente applicando i tassi di mercato correnti. Steam presenterà all'utente il prezzo convertito nella sua valuta locale, richiedendo l'approvazione. Per offrire un'esperienza migliore, è consigliabile definire un prezzo specifico per ogni valuta che ritieni possa essere utilizzata dagli utenti.
    • Un elenco di uno o più oggetti che l'utente desidera acquistare. Ogni oggetto deve essere accompagnato dai seguenti dati:
      • ID dell'oggetto: l'identificatore a 32 bit dell'oggetto.
      • Quantità: il numero di oggetti di questo tipo nella transazione.
      • Importo: l'importo (in centesimi) da addebitare all'utente per questo oggetto. Per alcune valute, il prezzo deve essere indicato in valori interi. Per ulteriori informazioni, consulta la seguente documentazione: Valute supportate. Se la quantità è maggiore di uno, questo valore rappresenta l'importo totale da addebitare (importo = quantità * costo dell'oggetto).
      • Descrizione dell'oggetto: una descrizione testuale dell'oggetto che viene mostrata all'utente quando gli sarà richiesto di autorizzare la transazione. Puoi scegliere di mostrare la traduzione di questa descrizione in base al codice della lingua indicato dal client di Steam.
      • Categoria dell'oggetto: una descrizione testuale facoltativa della categoria a cui appartiene questo oggetto. Questo valore è utilizzato per raggruppare i dati di vendita nei rapporti di Steam e non viene mai mostrato all'utente.

    Se la transazione viene accettata da Steam, il client riceverà automaticamente una notifica per autorizzare l'acquisto. Se viene restituito un errore, sarà necessario risolvere il problema e inviare una nuova transazione di acquisto.
  • Fase 4
    Se il processo di ISteamMicroTxn/InitTxn va a buon fine, l'utente riceverà una notifica in gioco tramite l'Overlay di Steam con la richiesta di autorizzazione della transazione. I dettagli della transazione vengono mostrati utilizzando le descrizioni degli oggetti fornite dalla richiesta di acquisto. L'utente può quindi autorizzare la transazione. Se l'utente non dispone di denaro sufficiente nel suo account, Steam lo guiderà automaticamente attraverso una procedura per l'aggiunta di fondi. Al termine dell'operazione, il gioco riceverà una notifica indicante che la transazione è stata autorizzata o rifiutata.

    Il gioco dovrà registrare un handler per la callback ISteamUser::MicroTxnAuthorizationResponse_t affinché possa ricevere la notifica dell'evento di autorizzazione (o di rifiuto). Il risultato della callback include l'appID, l'ID dell'ordine e lo stato di autorizzazione della transazione. Il gioco può inviare questo risultato al server degli acquisti per procedere alla finalizzazione della transazione. Per ulteriori dettagli, consulta la documentazione sulle Callback.
  • Fase 5
    Il server degli acquisti utilizza il comando ISteamMicroTxn/FinalizeTxn dell'API web per completare la transazione con i seguenti parametri:
    • ID dell'ordine: l'ID dell'ordine creato per avviare la transazione.
    • AppID: l'identificatore unico del tuo gioco di Steam.

    Un esito positivo indica che l'acquisto è stato autorizzato e che l'utente deve quindi ricevere gli oggetti. Un esito negativo, corredato da un messaggio di errore, indica che l'acquisto non è andato a buon fine.
  • Fase 6
    Il tuo server di acquisto dovrà chiamare regolarmente l'API ISteamMicroTxn/GetReport per ricevere notifiche riguardo allo stato di liquidazione delle transazioni. Dovresti chiamare questa API almeno una volta al giorno per riconciliare gli aggiornamenti relativi alle liquidazioni, ma non è una cattiva idea chiamare questa API ogni minuto per garantire che i tuoi server siano sempre aggiornati con eventuali aggiornamenti delle transazioni.

    A tua discrezione puoi rimborsare le transazioni dei clienti usando l'API ISteamMicroTxn/RefundTxn. Tuttavia ci sono altri modi per annullare le transazioni che probabilmente richiedono la tua attenzione. Quando una transazione viene annullata, ad esempio, Refunded (Rimborsata), PartialRefund (Rimborso parziale), Chargedback, RefundedSuspectedFraud (Rimborso per sospetta frode) o RefundedFriendlyFraud (Rimborso per frode amichevole): vedi Appendice A: valori di stato), il back-end dovrebbe tentare il recupero degli articoli associati alla transazione annullata, se possibile. Consulta la nostra documentazione sulla Prevenzione delle frodi e assicurati di aver adottato misure per prevenire i tipi più comuni di frode.

Acquisti nel web

Se il negozio del tuo gioco è una pagina web o se desideri soltanto aggiungere Steam come metodo di pagamento nel tuo negozio già esistente, segui questi passaggi per l'integrazione:
  • Fase 1
    Ottieni l'ID di Steam dell'utente.
    • Se l'utente è in gioco, utilizza l'API di Steamworks ISteamUser::GetSteamID per ottenere l'ID di Steam.
    • Se l'utente è sul tuo sito web, puoi utilizzare l'API OpenID di Steamworks per recuperare in modo sicuro l'ID di Steam dell'utente. I dettagli relativi a OpenID sono disponibili nella seguente documentazione di Steamworks: Autenticazione basata su browser web con OpenID.

    Nota: consigliamo di collegare l'account di gioco dell'utente con il relativo ID di Steam, in modo che il giocatore debba eseguire questo accesso secondario una sola volta.
  • Fase 2
    Ottieni il Paese e la valuta dell'utente effettuando una chiamata all'API web ISteamMicroTxn/GetUserInfo e passando l'ID di Steam dell'utente. Questi dati possono essere utilizzati per mostrare all'utente il tuo negozio con i prezzi nella valuta corretta.

    Nota: GetUserInfo include un parametro opzionale dove poter inserire un indirizzo IP per suggerire a Steam la provenienza dell'utente. Invia l'indirizzo IP pubblico dell'utente per tutti gli acquisti dal web o quando l'utente sta giocando al tuo titolo senza aver effettuato l'accesso al client di Steam.
  • Fase 3
    Il server degli acquisti inizializza una richiesta di acquisto tramite il servizio web di Steam utilizzando il metodo ISteamMicroTxn/InitTxn. In aggiunta ai dati per gli acquisti in gioco, sono necessarie anche le seguenti informazioni:
    • usersession: questo parametro deve essere impostato su "web" a indicare che l'utente autenticherà la transazione tramite un browser.
    • ipaddress: l'indirizzo IP pubblico dell'utente.

    Quando il parametro "usersession" è impostato su WEB, la richiesta InitTxn restituirà un ulteriore parametro "steamurl". Si tratta di un URL unico a cui è possibile reindirizzare la sessione web dell'utente e che identifica la transazione creata da questa chiamata all'API.

  • Fase 4
    Il server degli acquisti reindirizza la sessione web dell'utente all'URL di Steam restituito nella chiamata all'API InitTxn. In questa fase di reindirizzamento, aggiungi anche l'URL a cui far tornare l'utente quando la transazione viene autorizzata (o rifiutata). Utilizza un URL completamente qualificato (ad esempio http://www.steamgames.com) nel seguente formato:
    returnurl=il_tuo_URL_qui
    Quando viene reindirizzato all'URL di Steam, l'utente dovrà accedere a Steam prima di eseguire l'autenticazione. Questo è ciò che l'utente si aspetta quando seleziona Steam come metodo di pagamento sul tuo sito web. Se però l'utente ha già effettuato l'accesso su Steam e sta giocando al tuo titolo, sarebbe meglio evitare di farlo accedere una seconda volta. A questo scopo, è possibile utilizzare il browser web integrato nell'Overlay di Steam. Utilizzando il browser dell'Overlay di Steam per l'autorizzazione, l'accesso dell'utente avverrà in modo automatico. Per avviare il browser, utilizza la seguente chiamata all'API di Steamworks:
    ISteamFriends::ActivateGameOverlayToWebPage

    Puoi trovare maggiori dettagli sull'uso dell'Overlay di Steam qui.
  • Fase 5
    Quando l'utente fa ritorno nel tuo sito, chiama il metodo ISteamMicroTxn/QueryTxn dell'API web per ottenere i risultati. Se lo stato dell'ordine è "Approved", acquisisci i fondi con una chiamata al metodo ISteamMicroTxn/FinalizeTxn dell'API web. Se viene restituito un qualunque altro stato, dovrai abbandonare la transazione.

    Nota: se l'utente chiude il browser o qualcosa gli impedisce di tornare nel tuo sito, abbandona la transazione e non effettuare la chiamata a FinalizeTxn. Abbandona e ricomincia la procedura anche nel caso in cui l'utente abbia approvato la transazione senza essere reindirizzato.
  • Fase 6
    Il tuo server di acquisto dovrà chiamare regolarmente l'API ISteamMicroTxn/GetReport per ricevere notifiche riguardo allo stato di liquidazione delle transazioni. Dovresti chiamare questa API almeno una volta al giorno per riconciliare gli aggiornamenti relativi alle liquidazioni, ma non è una cattiva idea chiamare questa API ogni minuto per garantire che i tuoi server siano sempre aggiornati con eventuali aggiornamenti delle transazioni.

    A tua discrezione puoi rimborsare le transazioni dei clienti usando l'API ISteamMicroTxn/RefundTxn. Tuttavia ci sono altri modi per annullare le transazioni che probabilmente richiedono la tua attenzione. Quando una transazione viene annullata, ad esempio, Refunded (Rimborsata), PartialRefund (Rimborso parziale), Chargedback, RefundedSuspectedFraud (Rimborso per sospetta frode) o RefundedFriendlyFraud (Rimborso per frode amichevole): vedi Appendice A: valori di stato), il back-end dovrebbe tentare il recupero degli articoli associati alla transazione annullata, se possibile. Consulta la nostra documentazione sulla Prevenzione delle frodi e assicurati di aver adottato misure per prevenire i tipi più comuni di frode.

Appendice A: valori di stato

Di seguito sono elencati i possibili valori di stato restituiti dall'API Web ISteamMicroTxn. Il codice della risposta che riporta questi valori è solitamente chiamato status.
  • Init: l'ordine è stato creato ma non autorizzato dall'utente.
  • Approved: l'ordine è stato approvato dall'utente.
  • Succeeded: l'ordine è stato elaborato correttamente.
  • Failed: l'ordine non è stato elaborato correttamente o è stato negato.
  • Refunded: l'ordine è stato rimborsato e il prodotto deve essere revocato dal gioco. Il cliente può avviare una richiesta di rimborso.
  • PartialRefund: uno o più oggetti nel carrello sono stati rimborsati. Controlla il campo "itemstatus" di ogni oggetto per maggiori dettagli.
  • Chargedback: l'ordine è fraudolento o è stato contestato e il prodotto deve essere revocato dal gioco.
  • RefundedSuspectedFraud: l'ordine è stato rimborsato da Valve perché sospettato di essere fraudolento. Il prodotto deve essere revocato dal gioco.
  • RefundedFriendlyFraud: l'ordine è stato rimborsato da Valve in seguito a un caso di frode amichevole. Il prodotto deve essere revocato dal gioco.

Appendice B: codici di errore

Di seguito sono elencati i possibili codici di errore restituiti dall'API Web ISteamMicroTxn. Il codice della risposta che riporta questi valori è solitamente errorcode.
  • 1: operazione riuscita.
  • 2: operazione non riuscita.
  • 3: parametro non valido.
  • 4: errore interno.
  • 5: l'utente non ha approvato la transazione.
  • 6: la transazione è già stata eseguita.
  • 7: l'utente non ha effettuato l'accesso.
  • 8: la valuta non corrisponde alla valuta dell'account di Steam dell'utente.
  • 9: l'account non esiste o è temporaneamente non disponibile.
  • 10: l'utente ha rifiutato la transazione.
  • 11: la transazione è stata rifiutata poiché l'utente si trova in un Paese con restrizioni.
  • 12: la transazione è stata rifiutata perché il contratto di fatturazione non è attivo.
  • 13: il contratto di fatturazione non può essere elaborato in quanto non è di tipo GAME.
  • 14: il contratto di fatturazione è in sospeso a causa di una contestazione o di un chargeback.
  • 15: il contratto di fatturazione non può essere elaborato perché non è di tipo STEAM.
  • 16: l'utente ha già stipulato un contratto di fatturazione per questo gioco.
  • 100: fondi insufficienti.
  • 101: è stato superato il limite di tempo per la finalizzazione.
  • 102: l'account è disabilitato.
  • 103: l'account non è abilitato all'acquisto.
  • 104: transazione rifiutata per il rilevamento di una frode.
  • 105: nessun metodo di pagamento nella cache.
  • 106: la transazione supererebbe il limite di spesa indicato nel contratto di fatturazione.
  • 107: l'utente ha una transazione in sospeso che deve essere completata prima di iniziarne una nuova.

Altre domande?

Fai le tue domande nella bacheca discussioni sull'integrazione degli acquisti in gioco.