Passer au contenu

API Catalog (2.0.0)

Aperçu

  • Version : 2.0.0
  • Serveurs : https://store.xsolla.com/api
  • Contactez-nous par e-mail
  • URL de contact : https://xsolla.com/
  • Version TLS requise : 1.2

L’API Catalog permet de configurer un catalogue des objets en jeu côté Xsolla et de l’afficher aux utilisateurs dans votre magasin.

L’API permet de gérer les entités de catalogue suivantes :

  • Objets virtuels — objets en jeu tels que armes, skins, boosters.
  • Monnaie virtuelle — monnaie utilisée pour acheter des objets virtuels.
  • Packages de monnaie virtuelle — lots prédéfinis de monnaie virtuelle.
  • Lots — packages combinant objets virtuels, monnaie virtuelle ou clés de jeu vendus sous un seul UGS.
  • Clés de jeu — clés pour jeux et DLC distribuées via Steam ou d’autres fournisseurs DRM.
  • Groupes — regroupements logiques pour organiser et trier les éléments du catalogue.

Appels API

L’API est divisée en groupes suivants :

  • Admin — appels pour créer, mettre à jour, supprimer et configurer les objets et groupes du catalogue. Authentification via l’authentification d’accès de base avec vos identifiants marchand ou projet. Non destinés à un usage côté magasin.
  • Catalog — appels pour récupérer des objets et construire des vitrines personnalisées pour les utilisateurs finaux. Conçue pour gérer des charges importantes. Supporte l’autorisation optionnelle par JWT utilisateur pour retourner des données personnalisées telles que des limites spécifiques à l’utilisateur et des promotions actives.

Authentification

Les appels API nécessitent une authentification au nom d'un utilisateur ou d'un projet. Le schéma d'authentification à utiliser figure dans la section Security de la description de chaque appel.

Authentification à l'aide du JWT utilisateur

L'authentification par JWT utilisateur est utilisée lorsqu'une requête provient d'un navigateur, d'une application mobile ou d'un jeu. Par défaut, le schéma XsollaLoginUserJWT s'applique. Pour savoir comment créer un jeton, consultez la documentation de l'API Xsolla Login.

Transmettez le jeton dans l'en-tête Authorization au format suivant : Authorization: Bearer <user_JWT>, où <user_JWT> représente le jeton utilisateur. Ce jeton identifie l'utilisateur et donne accès à ses données personnalisées.

Vous pouvez également utiliser un jeton pour ouvrir l’interface de paiement.

Authentification HTTP basique

L'authentification HTTP basique est utilisée pour les interactions serveur à serveur, lorsqu'un appel API est envoyé directement depuis votre serveur plutôt que depuis le navigateur ou l'application mobile d'un utilisateur. Elle repose généralement sur une clé API.

Note

La clé API est confidentielle et ne doit jamais être stockée ni utilisée dans une application cliente.

Avec l'authentification basique côté serveur, toutes les requêtes API doivent inclure l'en-tête suivant :

  • pour basicAuth — Authorization: Basic <your_authorization_basic_key>, où your_authorization_basic_key est la paire project_id:api_key encodée en Base64
  • pour basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, où your_authorization_basic_key est la paire merchant_id:api_key encodée en Base64

Vous trouverez les valeurs des paramètres dans le Compte éditeur :

  • merchant_id s'affiche :
    • Dans Company settings > Company*.
    • Dans l'URL dans la barre d'adresse du navigateur sur n'importe quelle page du Compte éditeur. L'URL a le format suivant : https://publisher.xsolla.com/<merchant_id>.
  • project_id s'affiche :
    • À côté du nom du projet dans le Compte éditeur.
    • Dans l'URL dans la barre d'adresse du navigateur lors de l'utilisation d'un projet dans le Compte éditeur. L'URL a le format suivant : https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
  • api_key s'affiche dans le Compte éditeur uniquement au moment de la création et doit être stockée en toute sécurité de votre côté. Vous pouvez créer une clé API dans les sections suivantes :
Remarque

Si un appel API requis n'inclut pas le paramètre de chemin project_id, utilisez une clé API valide pour l'ensemble des projets de l'entreprise pour l'autorisation.

Pour plus d'informations sur l'utilisation des clés API, consultez les références API.

Authentification avec prise en charge de l'accès invité

Le schéma d’authentification AuthForCart est utilisé pour les achats via le panier et prend en charge deux modes :

  1. Authentification par JWT utilisateur. Le jeton est passé dans l'en-tête Authorization au format suivant : Authorization: Bearer <user_JWT>, où <user_JWT> représente le jeton utilisateur. Ce jeton identifie l'utilisateur et donne accès à ses données personnalisées. Vous pouvez également utiliser un jeton pour ouvrir l'interface de paiement.

  2. Mode simplifié sans en-tête Authorization. Ce mode est réservé aux utilisateurs non authentifiés et peut être utilisé uniquement pour la vente de clés de jeu. Au lieu d'un jeton, la requête doit inclure les en-têtes suivants :

    • x-unauthorized-id avec un identifiant de requête
    • x-user avec l'adresse e-mail de l'utilisateur encodée en Base64

Structure de l'entité principale

Les objets de tous types (objets virtuels, lots, monnaie virtuelle et clés) partagent une structure de données similaire. Comprendre cette structure de base facilite l’utilisation de l'API et la navigation dans la documentation.

Note

Certains appels peuvent inclure des champs supplémentaires, mais ils ne modifient pas la structure de base.

Identification

  • merchant_id — ID de l'entreprise dans le Compte éditeur
  • project_id — ID de projet dans le Compte éditeur
  • sku — UGS de l'objet, unique au sein du projet

Affichage en magasin

  • name — nom de l'objet
  • description — description de l'objet
  • image_url — URL de l'image
  • is_enabled — disponibilité de l'objet
  • is_show_in_store — affichage de l'objet dans le catalogue

Pour plus d'informations sur la gestion de la disponibilité des objets dans le catalogue, consultez la documentation.

Organisation

  • type — type d'objet, par exemple, un objet virtuel (virtual_item) ou un lot (bundle)
  • groups — groupes auxquels l'objet appartient
  • order — ordre d'affichage dans le catalogue

Conditions de vente

  • prices — prix en devise réelle ou monnaie virtuelle
  • limits — limites d'achat
  • periods — périodes de disponibilité
  • regions — restrictions régionales

Exemple de structure d'entité principale :

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

Processus d'achat de base

L'API Xsolla vous permet d'implémenter la logique de magasin en jeu, notamment la récupération du catalogue des objets, la gestion du panier, la création de commandes et le suivi de leur statut. Selon le scénario d'intégration, les appels API sont répartis en sections Administrateur et Catalogue, qui utilisent différents schémas d'authentification.

L'exemple suivant montre un processus de base pour configurer et exploiter un magasin, de la création d'objets à l'achat.

Création d'objets et de groupes (Administrateur)

Créez un catalogue des objets pour votre magasin, tels que des objets virtuels, des lots ou de la monnaie virtuelle.

Exemples d'appels API :

Configuration de promotions, chaînes et limites (Administrateur)

Configurez des outils d'acquisition d'utilisateurs et de monétisation, tels que des remises, des bonus, des récompenses quotidiennes ou des chaînes d'offres.

Exemples d'appels API :

Récupération d'informations sur un objet (Client)

Configurez l'affichage des objets dans l'application.

Remarque

N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue utilisateur. Ces appels API présentent des limites de taux et ne sont pas destinés au trafic utilisateur.

Exemples d'appels API :

Note

Par défaut, les appels API du catalogue renvoient les objets disponibles dans la boutique au moment de la requête. Pour récupérer les objets inactifs ou à durée limitée, ajoutez le paramètre "show_inactive_time_limited_items": 1 dans la requête du catalogue.

Vente des objets

Vous pouvez vendre des objets en utilisant les méthodes suivantes :

  • Achat rapide — vendre une UGS plusieurs fois.
  • Achat via le panier — l'utilisateur ajoute des objets au panier, supprime des objets et modifie les quantités dans une seule commande.

Si un objet est acheté en utilisant de la monnaie virtuelle au lieu des devises réelles, utilisez l'appel API Créer une commande à partir d'un objet spécifique en monnaie virtuelle. L'interface de paiement n'est pas requise, car le coût est traité lors de l'exécution de l'appel API.

Pour l'achat d'un objet gratuit, utilisez l'appel API Créer une commande avec un bien gratuit spécifique ou l'appel API Créer une commande à partir d'un panier gratuit. L'interface de paiement n'est pas requise, la commande est immédiatement définie sur le statut done.

Achat rapide

Utilisez l'appel API côté client pour créer une commande à partir d'un objet spécifique. L'appel renvoie un jeton utilisé pour ouvrir l'interface de paiement.

Note

Les informations sur les remises sont disponibles pour l'utilisateur uniquement dans l'interface de paiement. Les codes promo ne sont pas pris en charge.

Achat via le panier

La configuration et les achats du panier peuvent être gérés côté client ou côté serveur.

Configuration et achat du panier côté client

Implémentez vous-même la logique d'ajout et de suppression des objets. Avant d'appeler l'API pour configurer un panier, vous ne disposerez pas d'informations sur les promotions qui s'appliqueront à l'achat. Le coût total ainsi que les informations des objets bonus ajoutés ne seront donc pas encore connus.

Implémentez la logique suivante pour le panier :

  1. Après que le joueur a rempli un panier, utilisez l'appel API Remplir le panier d'objets. L'appel renvoie les informations actuelles sur les objets sélectionnés (prix avant et après remises, objets bonus).
  2. Mettez à jour le contenu du panier en fonction des actions utilisateur :
Note

Pour obtenir le statut actuel du panier, utilisez l'appel API Lire le panier de l'utilisateur actuel.
  1. Utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel. L'appel renvoie l'ID de commande et le jeton de paiement. La commande nouvellement créée est définie sur le statut new par défaut.

Configuration et achat du panier côté serveur

Cette approche peut nécessiter davantage de temps pour configurer le panier, car chaque modification doit être effectuée via des appels API.

Implémentez la logique suivante pour le panier :

  1. Après que le joueur a rempli un panier, utilisez l'appel API Remplir le panier d'objets. L'appel renvoie les informations à jour sur les objets sélectionnés (prix avant et après remises, objets bonus).
  2. Utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel. L'appel renvoie l'ID de commande et le jeton de paiement. La commande nouvellement créée est définie sur le statut new par défaut.

Ouverture de l'interface de paiement

Utilisez le jeton renvoyé pour ouvrir l'interface de paiement dans une nouvelle fenêtre. D'autres méthodes d'ouverture de l'interface de paiement sont décrites dans la documentation.

ActionEndpoint
Ouverture dans l'environnement de production.https://secure.xsolla.com/paystation4/?token={token}
Ouverture en mode bac à sable.https://sandbox-secure.xsolla.com/paystation4/?token={token}
Note

Utilisez le mode bac à sable pendant le développement et les tests. Les achats de test n'entraînent aucun débit sur des comptes réels. Vous pouvez utiliser des cartes bancaires de test.

Après le premier paiement réel, une politique stricte du mode bac à sable s'applique. Les paiements en mode bac à sable sont disponibles uniquement pour les utilisateurs spécifiés dans la section Company settings > Users du Compte éditeur.

L'achat de monnaie virtuelle et d'objets en devise réelle n'est possible qu'après la signature d'un contrat de licence avec Xsolla. Pour cela, dans le Compte éditeur, accédez à Agreements & Taxes > Agreements, complétez le formulaire et attendez la validation. Le traitement du contrat peut prendre jusqu'à 3 jours ouvrés.

Pour activer ou désactiver le mode bac à sable, modifiez la valeur du paramètre sandbox dans la requête pour l'achat rapide et l'achat via le panier. Le mode bac à sable est désactivé par défaut.

Statuts de commande possibles :

  • new — commande créée
  • paid — paiement reçu
  • done — objet attribué
  • canceled — commande annulée
  • expired — commande expirée

Suivez le statut de la commande en utilisant l'une des méthodes suivantes :

Pagination

Les appels API qui renvoient de grands ensembles d'enregistrements (par exemple lors de la création d'un catalogue) utilisent la pagination. La pagination est un mécanisme qui limite le nombre d'objets renvoyés dans une seule réponse et permet de récupérer les pages suivantes de manière séquentielle.

Utilisez les paramètres suivants pour contrôler le nombre d'objets renvoyés :

  • limit — nombre d'objets par page
  • offset — indice du premier objet sur la page (la numérotation commence à 0)
  • has_more — indique si une autre page est disponible
  • total_items_count — nombre total d'objets

Exemple de requête :

GET /items?limit=20&offset=40

Exemple de réponse :

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

Il est recommandé d'envoyer des requêtes successives jusqu'à ce que la réponse renvoie has_more = false.

Format de date et d'heure

Les dates et les valeurs temporelles sont transmises au format ISO 8601.

Les valeurs suivantes sont prises en charge :

  • Décalage UTC
  • Valeur null lorsqu'il n'y a pas de restriction temporelle pour l'affichage d'un objet
  • Horodatage Unix (en secondes) utilisé dans certains champs

Format : YYYY-MM-DDTHH:MM:SS±HH:MM

Exemple : 2026-03-16T10:00:00+03:00

Localisation

Xsolla prend en charge la localisation des champs destinés aux utilisateurs, tels que le nom et la description de l'objet. Les valeurs localisées sont transmises sous forme d'objet, où le code de langue est utilisé comme clé. La liste complète des langues prises en charge est disponible dans la documentation.

Champs pris en charge

Les paramètres suivants peuvent être localisés :

  • name
  • description
  • long_description

Format de langue

La clé de la langue peut être spécifiée dans l'un des formats suivants :

  • Code de langue à deux lettres : en, ru
  • Code de langue à cinq lettres : en-US, ru-RU, de-DE

Exemples

Exemple avec un code de langue à deux lettres :

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

Exemple avec un code de langue à cinq lettres :

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

Format de réponse d'erreur

En cas d'erreur, l'API renvoie un statut HTTP ainsi qu'un corps de réponse au format JSON. La liste complète des erreurs liées au magasin est disponible dans la documentation.

Exemple de réponse :

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — code d'erreur.
  • errorMessage — courte description de l'erreur.
  • statusCode — statut de la réponse HTTP.
  • transactionId — ID de la requête. Retourné uniquement dans certains cas.
  • errorMessageExtended — informations supplémentaires sur l'erreur, telles que les paramètres de la requête. Retournées uniquement dans certains cas.

Exemple de réponse détaillée :

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

Codes de statut HTTP courants

  • 400 — requête non valide
  • 401 — erreur d'authentification
  • 403 — permissions insuffisantes
  • 404 — ressource non trouvée
  • 422 — erreur de validation
  • 429 — limite de taux dépassée

Recommandations

  • Gérez ensemble le statut HTTP et le corps de la réponse.
  • Utilisez errorCode pour traiter les erreurs liées à la logique de l'application.
  • Utilisez transactionId pour identifier plus rapidement les requêtes lors de l'analyse des erreurs.
Télécharger la description d'OpenAPI
index.json
index.yaml
Langues
Serveurs
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/fr/api/catalog/

Aperçu

Vous pouvez utiliser des objets virtuels et de la monnaie virtuelle pour créer un magasin en jeu et configurer son affichage pour les utilisateurs. Les types d'objets suivants sont disponibles :

  • Objets virtuels — biens en jeu tels que des armes, des skins ou des boosters. Peuvent être vendus contre des devises réelles ou de la monnaie virtuelle.
  • Monnaie virtuelle — monnaie en jeu utilisée pour acheter des objets virtuels. Peut être vendue contre des devises réelles ou de la monnaie virtuelle.
  • Packages de monnaie virtuelle — quantité fixe de monnaie virtuelle. Peuvent être vendus contre des devises réelles ou de la monnaie virtuelle.

Les groupes sont utilisés pour organiser les objets dans le catalogue. Ils vous permettent de regrouper logiquement les objets et de gérer leur affichage.

Utilisez les appels API de la sous-section Administrateur pour créer, modifier et supprimer des objets.

Utilisez les appels API de la sous-section Catalogue pour récupérer des listes d'objets et les afficher aux utilisateurs.

Note

N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue de magasin.

Note

L'appel API Lire la liste des objets virtuels renvoie des données détaillées sur les objets, y compris les prix et les attributs, et prend en charge la pagination. Utilisez-le pour afficher les pages du catalogue dans la vitrine.

L'appel API Lire la liste de tous les objets virtuels renvoie l'UGS, le nom, la description des objets, ainsi que l'ID et le nom du groupe sans pagination. Utilisez-le pour la recherche côté client ou l'indexation.

Pour les achats avec de la monnaie virtuelle, utilisez l'appel API Créer une commande à partir d'un objet spécifique en monnaie virtuelle. L'interface de paiement n'est pas requise, le coût est traité lors de l'exécution de l'appel API.

Exemple de processus d'achat avec de la monnaie virtuelle :

Exemple de processus d'achat avec de la monnaie virtuelle

Administrateur

Opérations

Catalogue

Opérations

Paiement virtuel

Opérations

Aperçu

Les clés de jeu sont des codes alphanumériques uniques à usage unique permettant d’accéder à un jeu ou à un contenu téléchargeable (DLC) sur les plateformes de jeux vidéo. Vous pouvez vendre des clés de jeu via un lien direct, via l'interface du magasin, ou via un widget. Vous pouvez également configurer des restrictions régionales afin de vendre les clés de jeu dans des pays spécifiques. Pour plus d'informations, consultez la section Packs de clés de jeux.

L'authentification utilisateur n'est pas requise pour vendre des clés de jeu : elles sont envoyées à l'adresse e-mail fournie lors du paiement. Vous pouvez toutefois la configurer pour accéder à des fonctionnalités comme la personnalisation, les limites d'achat ou le système des droits. Pour en savoir plus, consultez la section Comment configurer l'authentification pour la vente de clés de jeu.

Flux de vente de clés de jeux :

  1. Créez un jeu en utilisant l'appel API Créer un jeu.
  2. Configurez les restrictions régionales.
  3. Téléchargez des clés dans un package de clés de jeu en utilisant l'appel API Télécharger des codes afin de les proposer à la vente.
  4. Affichez le catalogue des jeux avec les prix correspondant à la région de l'utilisateur à l'aide de l'appel API Lire la liste des jeux.
  5. Créez une commande. Pour un achat rapide, utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel, en passant l'UGS de la clé de jeu. La réponse renvoie un jeton permettant d'ouvrir l'interface de paiement.
  6. Implémentez l'ouverture de l'interface de paiement afin de régler la commande.

Pour recevoir des notifications en temps réel sur les paiements réussis et l'attribution des objets à l'utilisateur, configurez le suivi du statut des commandes, par exemple via les webhooks. Les clés sont envoyées à l'adresse e-mail indiquée lors du paiement, et la commande passe au statut done.

Clés de jeu

Catalogue

Opérations

Droit

Opérations

Administrateur

Opérations

Aperçu

Les lots sont des ensembles d'objets vendus comme une seule unité. Un lot peut inclure des objets virtuels, de la monnaie virtuelle, des packages de monnaie virtuelle, des clés de jeu et d'autres lots. Utilisez les lots pour créer des kits de démarrage, des offres saisonnières et des offres spéciales.

Utilisez les groupes d'appels API suivants pour interagir avec les lots :

  • Utilisez des appels API de la sous-section Administrateur pour créer, mettre à jour, supprimer des lots, et gérer leur visibilité.
  • Utilisez des appels API de la sous-section Catalogue pour récupérer des lots.

Les limites d'achat sont configurées via l'objet limits lors de la création ou de la mise à jour d'un lot. Pour en savoir plus, consultez l'aperçu des Limites. Vous pouvez également configurer des restrictions régionales afin de vendre des objets dans des pays spécifiques.

Note

Pour en savoir plus sur la configuration des lots, consultez la section Lots.

Scénario de gestion de lot :

  1. Créez un lot en utilisant l'appel API Créer un lot. Pour vérifier le lot créé, utilisez l'appel API Lire un lot. Pour récupérer tous les lots du projet, utilisez l'appel API Lire la liste des lots.
  2. Si nécessaire, utilisez l'appel API Mettre à jour un lot pour modifier le contenu ou les paramètres du lot.
  3. Implémentez la logique d'affichage des lots dans votre vitrine en utilisant l'appel API Lire la liste des lots, Lire un lot spécifique, ou Lire la liste des lots par groupe spécifique.
  4. Créez une commande en utilisant la section Panier et paiement. Par exemple, pour un achat rapide, vous pouvez utiliser l'appel API Créer une commande à partir d'un objet spécifique, en passant l'UGS du lot. La réponse contient un jeton pour ouvrir l'interface de paiement.
  5. Implémentez l'ouverture de l'interface de paiement pour payer la commande.
  6. Configurez le suivi du statut de la commande, par exemple en utilisant des webhooks, pour recevoir rapidement des données sur les objets payés avec succès et les attribuer à l'utilisateur.

Scénario de gestion de lot

Administrateur

Opérations

Catalogue

Opérations

Aperçu

Le panier est un mécanisme d'achat qui permet de regrouper plusieurs objets dans une seule commande. Un utilisateur peut acheter des objets de tout type et en toute quantité avec de la devise réelle, ainsi qu'utiliser des codes promo.

Le panier est stocké côté Xsolla. Sa sauvegarde d'une session à une autre dépend de l'authentification :

  • pour les utilisateurs authentifiés, le panier est lié à un utilisateur et conservé entre les sessions tant que les requêtes sont effectuées au nom de ce même utilisateur.

  • Pour les utilisateurs non authentifiés, la sauvegarde du panier dépend de la transmission de l'en-tête x-unauthorized-id. Pour conserver le panier d'un utilisateur non authentifié d'une session à l'autre, passez le même x-unauthorized-id dans chaque requête. Cette option est disponible uniquement pour la vente de clés de jeu.

Vous pouvez identifier le panier de deux façons : automatiquement via le JWT utilisateur ou via l'ID du panier (cart_id).

La gestion du panier est disponible à la fois côté client et côté serveur.

Côté serveur, vous pouvez remplir le panier avec des objets, par exemple lors de la restauration d'une session utilisateur. Les actions suivantes sont disponibles côté client :

  • récupérer le panier de l'utilisateur actuel ou un panier par ID
  • remplir le panier
  • mettre à jour les objets dans le panier
  • supprimer des objets du panier

Pour acheter des objets du panier, les appels client et serveur servent à créer une commande.

La durée de vie (TTL) du panier est de 72 heures par défaut. Si son contenu change, par exemple lorsqu'un nouvel objet est ajouté, la TTL est prolongée.

Après un paiement réussi, le panier n'est pas vidé automatiquement. Pour le vider, utilisez les appels API côté client suivants :

Scénario d'utilisation du panier :

  1. Implémentez une interface de magasin permettant à l'utilisateur de sélectionner des objets.

  2. Lorsque l'utilisateur sélectionne des objets dans le magasin, ajoutez-les au panier, par exemple via l'appel Remplir le panier d'objets. Dans le tableau des objets, indiquez les UGS et les quantités requises pour chaque objet.

  3. Implémentez l'interface du panier. Lors de l'accès au panier, affichez son contenu via l'appel Lire le panier de l'utilisateur actuel. La réponse inclut des informations sur le prix final de l'objet, avec remises et promotions appliquées.

  4. Implémentez l'ouverture de l'interface de paiement pour régler la commande. Vous pouvez, par exemple, utiliser l'appel Créer une commande à partir de tous les objets d'un panier spécifique. La réponse renvoie un jeton permettant d'ouvrir l'interface de paiement.

  5. Configurez le suivi du statut des commandes, par exemple à l'aide des webhooks, afin de recevoir rapidement les informations sur les objets payés avec succès et de les attribuer à l'utilisateur.

Note

Pour implémenter la vente d'objets en jeu et en ligne, consultez le guide d'intégration.

Flux de panier et de paiement

Cycle de vie d'une commande

Comprendre le cycle de vie d'une commande vous aide à suivre les commandes et à implémenter correctement la logique post-achat, par exemple l'attribution des objets.

La commande passe par les statuts suivants :

StatutDescriptionNotes
newCommande créée. Le système attend la confirmation du paiement..Les descriptions des statuts de transaction se trouvent dans la documentation Pay Station API.
paidCommande payée (la transaction est passée au statut done), et l'objet peut être attribué à l'utilisateur. La commande reste en statut new jusqu'à ce que le paiement soit confirmé.
doneObjet attribué à l'utilisateur. —
canceledPaiement remboursé. La commande passe à ce statut lorsque le statut de la transaction devient refunded.
expired La création d'une nouvelle commande pour un objet en édition limitée, un code promo ou une promotion fait passer toute commande antérieure non réglée contenant cet objet au statut expired. Seule la commande la plus récente peut être réglée. Si un utilisateur tente de régler une commande expirée, l'interface de paiement affichera une erreur 2002 et le paiement échouera.

Cycle de vie d'une commande

Note

Lorsque la commande passe au statut expired pendant que l'utilisateur finalise un paiement, mais que le paiement aboutit, la commande passe du statut expired au statut paid. Cela s'applique uniquement si la limite d'achat de l'objet associé à la commande n'est pas dépassée lors du paiement.

Panier (côté client)

Utilisez les appels de cette section pour gérer le panier côté client.

Opérations

Panier (côté serveur)

Utilisez les appels de cette section pour gérer le panier côté serveur.

Opérations

Paiement (côté client)

Utilisez les appels de cette section pour créer un jeton de paiement côté client.

Opérations

Paiement (côté serveur)

Utilisez les appels de cette section pour créer un jeton de paiement côté serveur.

Opérations

Commande

Utilisez les appels de cette section pour obtenir des informations sur les commandes.

Opérations

Biens gratuits

Use calls from this section to grant free items to users.

Opérations

Aperçu

Les limites d'achat vous permettent de restreindre la quantité d'objets disponibles à l'achat par un utilisateur unique ou par l'ensemble des utilisateurs. Vous pouvez également configurer des réinitialisations programmées des limites.

Les limites sont stockées côté Xsolla et sont configurées au niveau de l'objet individuel dans le Compte éditeur ou via l'objet limits dans les appels API suivants :

Les informations sur les limites sont renvoyées dans l'objet items.limits dans les appels API suivants pour récupérer le catalogue des objets :

Les appels API de la sous-section Gestion du groupe Limites vous permettent de récupérer l'état actuel des limites et de les mettre à jour pour un utilisateur spécifique, par exemple, réinitialiser le compteur après la fin d'une quête ou ajuster manuellement la quantité restante.

Note

Pour des informations détaillées sur la configuration des limites dans le catalogue, consultez la section Item purchase limits.

Gestion

Opérations

Administrateur

Opérations

Pré-commandes

Opérations

Commerçant

Opérations

Catalogue

Cette API permet de récupérer tout type d'objet vendable ou tout objet spécifique.

Opérations

Régions communes

Opérations

Administrateur

Opérations

Administrateur

Opérations

Catalogue

Opérations