Documentation Steamworks
Guide de mise en œuvre des microtransactions

Présentation

L'objectif du système de paiement en jeu de Steam est d'offrir aux équipes de développement un moyen facile de vendre tous types de produits sans que leur clientèle n'ait besoin de quitter le jeu. La nature des produits à vendre est totalement laissée à l'appréciation de l'entité marchande. Il peut s'agir d'objets en jeu, comme des armes ou des munitions, d'une devise en jeu, comme de l'or ou des pièces, ou même d'items cosmétiques pour le personnage jouable. Vous pouvez avoir autant d'items que vous le souhaitez dans votre jeu et les vendre à l'unité ou par lot. Steam ne pose aucune restriction sur ce que vous vendez ou sur la manière dont vous le vendez, pas plus qu'il n'empêche l'utilisation de tout autre mécanisme dont pourrait disposer votre jeu pour vendre des items. Son objectif est d'apporter à votre jeu la même expérience de paiement à laquelle les utilisatrices et utilisateurs sont habitués sur la plateforme Steam, et de leur permettre d'acheter facilement vos produits avec l'argent qui se trouve dans leur portemonnaie Steam. En utilisant ce type d'intégration, votre jeu aura un accès immédiat aux nouveaux utilisateurs et utilisatrices Steam et aux nouveaux moyens de paiement dès qu'ils seront disponibles.

Grâce à ce système, les achats sont entièrement sous votre contrôle. Quand une demande d'achat aboutit positivement, cela signifie, d'une part, que la personne a pu effectuer son paiement de manière sécurisée et, d'autre part, que vous avez été immédiatement notifié(e) du succès de la transaction. Une fois un achat approuvé, vous n'avez plus qu'à attribuer et gérer les items. Si, par exemple, un item n'est disponible que pour une durée limitée, votre système impose cette durée de validité.

En plus des achats en jeu, le système apportera des fonctionnalités supplémentaires que vos systèmes de comptabilité et d'assistance pourront utiliser.
  1. Vous pourrez recevoir une notification en cas de défaut de paiement de la part des clients et clientes.
  2. Vous pourrez effectuer des remboursements et consulter les statuts des transactions via le service Web.
  3. Sur notre site des partenaires Steamstats, vous aurez accès à des rapports détaillés des ventes en direct d'items et de jeux.

Bonnes pratiques pour les achats en jeu

Si vous cherchez à publier votre jeu sur Steam avec des achats en jeu, nous avons quelques suggestions, bonnes pratiques et ressources pour vous aider à démarrer. Qu'il s'agisse d'un jeu gratuit ou avec achat initial, il y a certains éléments communs entre tous les jeux comportant des achats en jeu qu'il est utile de prendre en compte quand vous préparez votre lancement sur Steam.

Si vous avez des suggestions par rapport aux économies en jeu et aux bonnes pratiques, veuillez consulter la section Microtransactions (achats en jeu) de la documentation.

Fonctionnement du système de paiement

Le système de paiement comprend le processus d'achat que vous avez en jeu, le service de facturation Web Steam ainsi que le processus d'approbation de la personne qui effectue l'achat.

Le processus d'achat se déroule dans l'ordre suivant. La personne commence et termine toujours sa commande dans votre jeu.
  1. Lorsqu'une personne souhaite acheter quelque chose en jeu, votre jeu envoie une requête d'achat à votre serveur d'achat. Le serveur d'achat peut être toute entité de service dont dispose votre système de jeu pour traiter les demandes d'achat. Il peut s'agir d'un serveur Web ou de votre système d'authentification. Le serveur aura besoin de communiquer avec les serveurs de facturation Steam via HTTP. Votre serveur d'achat peut également demander le pays, la langue et la devise de l'utilisateur ou l'utilisatrice aux serveurs de facturation Steam. Vous pouvez utiliser ces données pour ajuster votre tarification selon les besoins.
  2. Votre serveur d'achat envoie ensuite au service Web de Steam une opération de paiement au nom du client Steam. Cette requête est une requête POST HTTP sécurisée. Le contenu de cette requête comprend les métadonnées de la personne, une description et le cout de chaque item que la personne souhaite acheter.
  3. À la réception de cette requête, Steam activera automatiquement l'overlay et affichera une boite de dialogue énumérant tous les items, leur cout et un bouton pour confirmer ou autoriser la transaction. Si la personne ne dispose pas de fonds suffisants sur son compte Steam, l'overlay l'invitera à suivre un processus d'ajout de fonds. Toutes les informations de facturation sont récupérées via l'overlay Steam. Une fois le processus d'achat terminé, la personne recevra une notification qui indique si l'achat a été autorisé ou refusé. Votre jeu doit être enregistré pour recevoir un rappel de cette notification et transmettre le résultat à votre serveur d'achat.
  4. Votre serveur d'achat reçoit la notification et envoie un appel FinalizeTransaction à Steam pour terminer l'opération. Si la requête d'achat reçoit une réponse positive, l'utilisatrice ou l'utilisateur sera facturé et vous pourrez alors lui remettre l'item.

Sinon, pour les jeux dont les options d'achat sont généralement traitées via une page Web ou si vous souhaitez proposer directement Steam en tant que moyen de paiement sur votre site Web, vous pouvez effectuer une intégration basée sur le navigateur. Si vous optez pour cette solution, la procédure d'achat se déroule dans l'ordre suivant.
  1. Quelqu'un souhaite acheter quelque chose en jeu ou sur votre site Web. Pour les achats en jeu, vous devez lancer un navigateur vers votre page Web.
  2. Votre serveur d'achat lance une transaction Web au nom de la personne sous la forme d'une requête POST HTTP sécurisée. En cas de réussite, il renverra une URL Steam unique vers laquelle vous pourrez ensuite rediriger la session du navigateur de l'utilisateur ou de l'utilisatrice, qui devra autoriser la transaction. Lors de la redirection, vous spécifierez également une URL de renvoi vers laquelle la personne sera renvoyée après le processus d'autorisation.
  3. Quand la personne est redirigée vers votre site, votre serveur d'achat demande le statut de la transaction et, si elle a bien été autorisée, vous pouvez récupérer les fonds à l'aide d'un appel FinalizeTransaction à Steam.

Paramétrer une connexion

Prérequis

Créez tout d'abord une clé d'édition d'API Web. Vous trouverez les instructions dans la section Authentification à l'aide des clés de l'API Web de la documentation. La clé est passée avec toutes les requêtes du serveur Web et est utilisée pour authentifier les requêtes du serveur. Le tout doit être envoyé en tant que paramètre key=<votre clé ici> avec les requêtes.

Enregistrer la commande

Enregistrez chaque commande dans votre système pour pouvoir vous y référer dans le futur. Utilisez un ID de commande unique à 64 bits pour référencer les transactions au sein de Steam.

Envoi de requêtes

Toutes les requêtes doivent être envoyées à l'aide de GET ou POST de HTTP 1.1 et avec une connexion sécurisée TLS. Le type de contenu doit être « application/x-www-form-urlencoded » et les paramètres de POST doivent se trouver dans le corps de la requête au format standard de codage d'URL. Le texte doit être transmis au format UTF-8.

Les demandes passeront par l'URI de base :
https://partner.steam-api.com/ISteamMicroTxn/*

Certaines commandes renvoient un résultat Réussite ou Échec. Dans le cas d'un renvoi de résultat de type Échec, un code d'erreur supplémentaire avec sa description sera ajouté en annexe. Ces clés ne seront pas présentes pour une réponse de type Réussite.

Les réponses seront renvoyées au format JSON par défaut. Vous pouvez choisir de spécifier un format XML en ajoutant le paramètre « format=xml » à la requête.
Remarque : vous devez absolument incorporer une solution JSON ou XML flexible qui permet aux clés de paramétrage d'être postées et renvoyées dans un ordre arbitraire.

Tests

Steam propose un bac à sable (sandbox) à l'usage des équipes de développement pour tester votre intégration. Le bac à sable prend en charge toutes les requêtes disponibles via l'API habituelle, mais aucune somme d'argent ne sera retirée du portemonnaie Steam de la personne qui effectue les tests.

Pour accéder au bac à sable, il faut utiliser un URI de base différente :
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Étapes d'intégration

Achats en jeu


Cette section concerne les jeux qui disposent d'un magasin intégré et pour lesquels l'expérience du public reste en jeu.
  • Étape 1.
    L'API Steamworks doit être intégrée à votre jeu. Cela implique d'inclure un fichier d'entête, de lier un fichier lib et d'intégrer une DLL à votre produit. Veuillez vous référer à la section Présentation de l'API Steamworks de la documentation pour plus de détails. L'API Steamworks doit être correctement initialisée avant de poursuivre !
  • Étape 2.
    Quelqu'un choisit d'acheter un ou plusieurs items dans votre jeu. Une fois le ou les items identifiés, votre jeu devra collecter des métadonnées sur l'utilisateur ou l'utilisatrice.
    • SteamID : ce numéro 64 bits est l'identifiant unique du compte utilisateur dans le système Steam.
    • Code pays : le code pays ISO 3166 indique d'où la personne effectue ses achats. Utilisez ce code pour déterminer le prix à appliquer pour l'achat.
    • Code de devise : le code de devise ISO 4217 dans laquelle la personne sera facturée.
    • Code de langue du client du jeu : le code de langue ISO 639-1 dans laquelle le client Steam du jeu est actuellement exécuté.

    Le SteamID et la langue peuvent être obtenus depuis les appels de l'API Steamworks :

    Pour obtenir le pays et le type de devise de l'utilisateur ou l'utilisatrice, utilisez la requête d'API Web ISteamMicroTxn/GetUserInfo en lui passant le SteamID de cette personne.

    Ces métadonnées de compte doivent être regroupées et envoyées avec les données d'achat habituelles à votre serveur d'achat.
  • Étape 3.
    Votre serveur d'achat initie une demande d'achat via le service Web Steam au nom du client Steam. Utilisez la fonction ISteamMicroTxn/InitTxn décrite plus bas dans ce document. Vous devrez envoyer les données ci-dessous avec la requête.
    • ID de commande : un numéro 64 bits unique que vous attribuez à cet achat. Ce numéro est votre clé pour la transaction. Il est utilisé pour référencer la transaction dans le système Steam.
    • SteamID : l'ID du compte utilisateur reçu du client Steam à l'étape 3.
    • AppID : l'identifiant unique de votre jeu Steam.
    • Langue : le code de langue ISO 639-1 dans laquelle votre ou vos items sont répertoriés.
    • Devise : le code de devise ISO 4217 dans laquelle votre ou vos prix sont répertoriés. Si cela ne correspond pas au code de devise recueilli lors de l'étape 2, une conversion automatique de la devise sera appliquée au taux actuel du marché. Steam présentera à la personne le prix converti dans sa devise locale pour approbation. Pour améliorer l'expérience du public, il est recommandé de fournir des prix spécifiques dans chaque devise qui pourrait être utilisée par votre clientèle.
    • Une liste du ou des items que la personne souhaite acheter. Pour chaque item, indiquez les données suivantes :
      • ID d'item : votre propre identifiant 32 bits pour l'item.
      • Quantité : le nombre d'items de ce type dans la transaction.
      • Montant : le montant (en centimes) que vous souhaitez facturer pour cet item. Certaines devises doivent être exprimées en valeurs entières. Consultez la section Devises prises en charge de la documentation pour plus d'informations. Si la valeur Quantité de cet item est supérieure à 1, cette valeur sera le total qui sera facturé (Montant = Quantité × prix de l'item).
      • Description de l'item : une description textuelle de l'item. Celle-ci sera présentée à l'utilisatrice ou l'utilisateur lorsqu'il lui sera demandé d'autoriser la transaction. Vous pouvez choisir de traduire cette description en fonction du code de langue spécifié pour le client Steam.
      • Catégorie d'item : une description textuelle facultative de la catégorie sous laquelle cet item devrait se retrouver. Cette valeur est utilisée pour regrouper les données de ventes dans les rapports internes de Steam et n'est jamais présentée au public.

    Si la transaction est acceptée par Steam, le client Steam en sera automatiquement notifié pour qu'il autorise l'achat. Si une erreur est renvoyée, le problème devra être corrigé et une nouvelle transaction d'achat devra être soumise.
  • Étape 4.
    Si la tentative de ISteamMicroTxn/InitTxn est réussie, l'utilisateur ou l'utilisatrice recevra en jeu, via l'overlay Steam, une notification pour l'informer que la transaction doit être autorisée. Les détails de la transaction sont affichés à l'aide des descriptions d'items fournies par votre requête d'achat. L'utilisateur ou l'utilisatrice peut alors autoriser la transaction. Si la personne n'a pas les fonds suffisants sur son compte, Steam l'invitera automatiquement à suivre un processus d'ajout de fonds. À la fin du processus, votre jeu recevra une notification indiquant si la transaction a été autorisée ou refusée.

    Votre jeu devra enregistrer un gestionnaire de rappel ISteamUser::MicroTxnAuthorizationResponse_t pour recevoir une notification d'acceptation ou de refus de l'évènement. Ce résultat de rappel contient l'AppID, l'ID de commande et le statut d'autorisation de la transaction. Votre jeu peut envoyer ce résultat à votre serveur d'achat pour qu'il sache quand finaliser la transaction. Veuillez consulter la section Rappels de la documentation pour plus de détails.
  • Étape 5.
    Votre serveur d'achat utilise la commande de l'API ISteamMicroTxn/FinalizeTxn pour finaliser la transaction avec les paramètres repris ci-dessous.
    • ID de commande : l'ID de commande que vous avez créé pour initier la transaction.
    • AppID : l'identifiant unique de votre jeu Steam.

    Une réponse positive signifie que l'achat a été accepté et que les articles doivent être distribués. Une réponse négative (une erreur) indique que l'achat n'a pas été effectué correctement, et un message d'erreur approprié apparait.
  • Étape 6.
    Votre serveur d'achat devra appeler l'API ISteamMicroTxn/GetReport régulièrement pour recevoir les notifications de changement relatives à l'état de règlement des transactions. Cette API doit être appelée au moins une fois par jour pour réconcilier les règlements actualisés, mais il ne serait pas raisonnable de l'appeler toutes les minutes pour que vos serveurs soient tout le temps au courant de l'évolution des transactions.
    Les transactions peuvent cependant être annulées par d'autres moyens qui méritent surement votre attention. Lorsqu'une transaction passe en état d'annulation (par exemple « Refunded », « PartialRefund », « Chargedback », « RefundedSuspectedFraud » ou « RefundedFriendlyFraud », voir plus bas Annexe A : valeurs d’état), alors votre serveur doit tenter de récupérer les articles associés à la transaction annulée si c'est possible. Veuillez revoir la section sur comment anticiper les fraudes dans notre documentation et vous assurer que vous avez pris des précautions pour vous protéger des types de fraudes les plus courants.

Achat sur le Web

Si le magasin de votre jeu est une page Web ou que vous souhaitez simplement ajouter Steam en tant que moyen de paiement aux options de paiement existantes de votre magasin, veuillez suivre les étapes d'intégration ci-dessous.
  • Étape 1.
    Obtenez le SteamID du compte.
    • Si la personne est actuellement en jeu, utilisez l'API Steamworks pour renvoyer le SteamID : ISteamUser::GetSteamID.
    • Si la personne est sur votre site Web, vous pouvez utiliser l'API Steamworks OpenID pour récupérer son SteamID de manière sécurisée. Vous trouverez plus de détails sur OpenID dans la section Authentification basée sur le navigateur Web avec OpenID de la documentation Steamworks.

    Remarque : nous vous recommandons d'associer le compte de jeu de l'utilisateur ou l'utilisatrice à son SteamID, pour qu'il ou elle n'ait à effectuer cette connexion secondaire qu'une seule fois.
  • Étape 2.
    Récupérez le pays et le type de devise de l'utilisateur ou de l'utilisatrice en appelant la requête d'API Web ISteamMicroTxn/GetUserInfo et en lui passant son SteamID. Ces données peuvent être utilisées pour afficher les prix et la devise qui correspondent à l'utilisateur ou l'utilisatrice sur votre magasin.

    Remarque : GetUserInfo a un paramètre d'adresse IP optionnel que vous pouvez utiliser pour indiquer à Steam d'où vient la personne qui effectue l'achat. Envoyez l'adresse IP publique du compte à chaque fois qu'il effectue un achat sur le Web ou à chaque fois qu'il n'est pas connecté activement au client Steam et qu'il lance votre jeu.
  • Étape 3.
    Votre serveur d'achat initie une requête d'achat via le service Web Steam à l'aide de ISteamMicroTxn/InitTxn. Deux types de données supplémentaires seront fournies en plus des données nécessaires à un achat normal.
    • usersession : doit être défini sur « web » pour indiquer que l'utilisateur ou l'utilisatrice authentifiera la transaction via un navigateur.
    • ipaddress : adresse IP publique du compte utilisateur.

    Lorsque usersession est défini sur WEB, la requête InitTxn renverra un paramètre steamurl supplémentaire. Il s'agit d'une URL unique vers laquelle vous pouvez rediriger la session Web du compte utilisateur et qui identifie la transaction créée par cet appel d'API.

  • Étape 4.
    Votre serveur d'achat redirige la session Web du compte utilisateur vers l'URL Steam renvoyée dans l'appel d'API InitTxn. En plus de l'adresse de redirection, ajoutez votre propre URL vers laquelle la personne sera renvoyée une fois la transaction autorisée (ou refusée). Utilisez une URL entièrement spécifiée (exemple : http://www.steamgames.com) sous la forme
    returnurl=votre_URL_ici.
    Lorsqu'une personne est redirigée vers l'URL Steam, elle doit se connecter à Steam avant de s'authentifier. Si la personne choisit Steam comme méthode de paiement sur votre site Web, elle s'attendra à ce qu'on lui demande de se connecter à son compte Steam. Toutefois, si la personne est déjà connectée à Steam et est en train de jouer à votre jeu, il est préférable d'éviter cette nouvelle demande de connexion. Pour cela, vous pouvez utiliser le navigateur Web intégré dans l'overlay de jeu. Quand le navigateur intégré à l'overlay de jeu est utilisé pour l'autorisation, la personne est automatiquement connectée. Pour lancer le navigateur, utilisez l'appel d'API Steamworks
    ISteamFriends::ActivateGameOverlayToWebPage

    Vous trouverez tous les détails nécessaires sur l'utilisation de l'overlay de jeu ici.
  • Étape 5.
    Quand la personne retourne sur votre site, émettez un appel d'API ISteamMicroTxn/QueryTxn pour obtenir les résultats. Si l'état de la commande est « Approved », récupérez les fonds à l'aide de l'appel d'API ISteamMicroTxn/FinalizeTxn. Abandonnez la transaction en cas de renvoi de tout autre état.

    Remarque : si l'utilisateur ou l'utilisatrice ferme son navigateur ou s'il se passe quelque chose qui l'empêche de revenir sur votre site, abandonnez la transaction et n'émettez pas d'appel FinalizeTxn. Si la personne a approuvé la transaction, mais qu'elle n'a pas été redirigée, abandonnez la transaction et recommencez.
  • Étape 6.
    Votre serveur d'achat devra appeler l'API ISteamMicroTxn/GetReport régulièrement pour recevoir les notifications de changement relatives à l'état de règlement des transactions. Cette API doit être appelée au moins une fois par jour pour réconcilier les règlements actualisés, mais il ne serait pas raisonnable de l'appeler toutes les minutes pour que vos serveurs soient tout le temps au courant de l'évolution des transactions.
    Les transactions peuvent cependant être annulées par d'autres moyens qui méritent surement votre attention. Lorsqu'une transaction passe en état d'annulation (par exemple « Refunded », « PartialRefund », « Chargedback », « RefundedSuspectedFraud » ou « RefundedFriendlyFraud », voir plus bas Annexe A : valeurs d’état), alors votre serveur doit tenter de récupérer les articles associés à la transaction annulée si c'est possible. Veuillez revoir la section sur comment anticiper les fraudes dans notre documentation et vous assurer que vous avez pris des précautions pour vous protéger des types de fraudes les plus courants.

Annexe A : valeurs d’état

Voici les possibles valeurs d'état renvoyées par l'API Web ISteamMicroTxn. La clé de réponse portant ces valeurs est généralement appelée status.
  • Init : la commande a été créée, mais non autorisée par l'utilisateur ou l'utilisatrice.
  • Approved : la commande a été approuvée par l'utilisateur ou l'utilisatrice.
  • Succeeded : la commande a été traitée avec succès.
  • Failed : la commande a échoué ou a été refusée.
  • Refunded : la commande a été remboursée, et le produit doit être révoqué par le jeu. Un remboursement peut être initié par le client ou la cliente.
  • PartialRefund : un item ou plus du panier a été remboursé. Vérifiez le champ itemstatus de chaque item pour afficher les détails.
  • Chargedback : la commande est frauduleuse ou contestée, et le produit doit être révoqué par le jeu.
  • RefundedSuspectedFraud : la commande a été remboursée par Valve, car il semblerait qu'il s'agissait d'une fraude. Le produit devrait être révoqué par le jeu.
  • RefundedFriendlyFraud : la commande a été remboursée par Valve, car il semblerait qu'il s'agissait d'une rétrofacturation frauduleuse. Le produit devrait être révoqué par le jeu.

Annexe B : codes d'erreur

Voici les possibles codes d'erreur renvoyés par l'API Web ISteamMicroTxn. La clé de réponse portant ces valeurs est généralement errorcode.
  • 1 : réussite.
  • 2 : échec de l'opération.
  • 3 : paramètre invalide.
  • 4 : erreur interne.
  • 5 : la personne n'a pas approuvé la transaction.
  • 6 : la transaction a déjà été effectuée.
  • 7 : la personne n'est pas connectée.
  • 8 : la devise ne correspond pas à la devise indiquée sur le compte Steam.
  • 9 : le compte n'existe pas ou est temporairement indisponible.
  • 10 : la transaction a été refusée par l'utilisateur ou l'utilisatrice.
  • 11 : la transaction a été refusée, car l'utilisateur ou l'utilisatrice se trouve dans un pays à accès restreint.
  • 12 : la transaction a été refusée, car l'accord de facturation n'est pas actif.
  • 13 : l'accord de facturation ne peut être traité, car il n'est pas du type GAME.
  • 14 : l'accord de facturation est en attente pour cause de rétrofacturation ou de conflit lié à la facturation.
  • 15 : l'accord de facturation ne peut être traité, car il n'est pas du type STEAM.
  • 16 : l'utilisateur ou l'utilisatrice dispose déjà d'un accord de facturation pour ce jeu.
  • 100 : fonds insuffisants.
  • 101 : le délai de finalisation a été dépassé.
  • 102 : le compte est désactivé.
  • 103 : le compte n'est pas autorisé à effectuer des achats.
  • 104 : la transaction a été refusée, car une fraude a été détectée.
  • 105 : aucun moyen de paiement en cache.
  • 106 : la transaction dépasserait le plafond de dépenses prévu par l'accord de facturation.
  • 107 : la personne doit terminer une transaction en attente avant de pouvoir initier une nouvelle transaction.

D'autres questions ?

Posez-les sur le forum de discussion sur l'intégration des achats en jeu.