Octroyer les achats à l’utilisateur

Implémentez l’octroi des achats à l’utilisateur dans votre application en utilisant les informations fournies par les webhooks de Xsolla concernant les détails de la transaction et les objets achetés.

Pour le bon fonctionnement du magasin en jeu et la gestion des paiements, implémentez le traitement des principaux webhooks suivants :

Le schéma ci-dessous montre le processus d’achat et de retour d’objets en utilisant des webhooks combinés.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as Utilisateur
    participant GameClient as Client du jeu
    participant Xsolla as Xsolla
    participant GameServer as Serveur de jeu
    %% Item Purchase
    rect rgb(243, 243, 241)
        Note over User, GameServer: Achat d’objet
    end
        User ->> GameClient: Se connecte
        activate GameClient
        GameClient ->> Xsolla: Envoie une demande d’authentification de l’utilisateur
        activate Xsolla
        Xsolla -->> GameClient: Renvoie un jeton JWT / OAuth 2.0
        deactivate Xsolla
        GameClient ->> Xsolla: Envoie le JWT, l’ID du projet et les paramètres de pagination
        activate Xsolla
        Xsolla -->> GameClient: Renvoie un tableau d’objets
        deactivate Xsolla
        GameClient -->> User: Affiche la vitrine
        deactivate GameClient
        User ->> GameClient: Sélectionne l’objet et appuie sur Acheter
        activate GameClient
        GameClient ->> Xsolla: Crée une demande de commande
        deactivate GameClient
        activate Xsolla
        Xsolla -->> GameClient: Renvoie un jeton de paiement
        deactivate Xsolla
        activate GameClient
        GameClient ->> Xsolla: Ouvre l’URL de l’interface utilisateur de paiement avec le jeton reçu
        deactivate GameClient
        activate Xsolla
        Xsolla ->> GameServer: Envoie un webhook de validation de l’utilisateur
        activate GameServer
        GameServer -->> Xsolla: Renvoie un code d’état de réussite
        deactivate GameServer
        Xsolla -->> User: Affiche l’interface de paiement
        deactivate Xsolla
        User ->> Xsolla: Choisit le mode de paiement et appuie sur Payer
        activate Xsolla
        Xsolla ->> GameServer: Envoie le webhook de paiement de commande réussi
        activate GameServer
        activate GameServer
        Note right of GameServer: Octroie les achats à l’utilisateur
        deactivate GameServer
        GameServer -->> Xsolla: Renvoie un code d’état de réussite
        deactivate GameServer
        Xsolla -->> User: Affiche l’écran de confirmation d’achat
        deactivate Xsolla
    %% Refund / Chargeback
    rect rgb(243, 243, 241)
        Note over User, GameServer: Remboursement / Chargeback
    end
        User ->> Xsolla: Demandes de remboursement ou de chargeback
        activate Xsolla
        Xsolla ->> GameServer: Envoie un webhook d’annulation de commande
        activate GameServer
        activate GameServer
        Note right of GameServer: Supprime des objets de l’inventaire de l’utilisateur
        deactivate GameServer
        GameServer -->> Xsolla: Renvoie un code d’état de réussite
        deactivate GameServer
        Xsolla -->> User: Rembourse le paiement
        deactivate Xsolla

Si la personnalisation du catalogue des objets est implémentée du côté de votre application, configurez le traitement de la Personnalisation du catalogue côté partenaire.

Configurer les webhooks dans le Compte éditeur

Pour activer la réception des webhooks :

1. Dans le projet dans le Compte éditeur, accédez à la section Project settings > Webhooks.
2. Dans le champ Webhook server, spécifiez l’URL du serveur où vous souhaitez recevoir les webhooks au format https://example.com. Vous pouvez également utiliser une URL fournie par un outil de test de webhooks.

3. Générez une clé secrète :

1. Dans la section Secret keys, appuyez sur Add key.
2. Dans la fenêtre modale qui s'affiche, entrez le nom de la clé qui vous permettra de l'identifier dans la liste générale.
3. Appuyez sur Create key.
4. Appuyez sur Copy secret et enregistrez la clé créée de votre côté.
5. Appuyez sur Done.
6. Confirmez que vous avez enregistré la clé et appuyez sur Ok, close.

4. Appuyez sur Enable webhooks.

Rotation de la clé secrète

Créez jusqu'à 5 clés secrètes dans votre projet afin de permettre leur rotation.

Une seule clé secrète peut être active par projet. Pour la modifier, appuyez sur Set as active sur la ligne d'une autre clé, puis confirmez l'action. Une fois la migration vers une nouvelle clé effectuée, nous vous recommandons de supprimer les clés désactivées.

Tester les webhooks dans le Compte éditeur

Après l’activation des webhooks dans le projet, une section permettant de les tester s’affiche dans le Compte éditeur, sous les paramètres avancés.

Vous pouvez tester les webhooks suivants :

En l’absence de valeurs réelles, saisissez des valeurs arbitraires.

Vous pouvez également tester les webhooks lorsque vous effectuez des achats en mode bac à sable ou en mode de production. Le test du webhook Refund n’est possible qu’en mode de production.

Envoi de réponses au webhook

Pour confirmer la réception du webhook, votre serveur doit renvoyer :

• Un code HTTP 200, 201 ou 204 en cas de réponse positive ;
• Un code HTTP 400 avec description du problème au cas où l’utilisateur spécifié n’a pas été trouvé ou une signature non valide a été passée.

Votre gestionnaire de webhooks peut également renvoyer un code 5xx en cas de problèmes temporaires sur votre serveur.

Étapes suivantes

1. Configurez la vente d'abonnements (facultatif).
2. Configurez l'authentification utilisateur.

Configuration des informations sur les objets dans les webhooks

Vous pouvez configurer les données relatives aux objets inclus dans les webhooks Paiement de commande réussi et Annulation de commande via le tableau items.

Activation de l'inclusion de paramètres supplémentaires

Permet d’inclure des paramètres supplémentaires indiquant :

• si l’objet est gratuit (is_free ) ;
• si l’objet est un bonus (is_bonus) ;
• si l’objet fait partie d’un lot (is_bundle_content).

Pour recevoir ces paramètres, vous devez mettre à jour vos webhooks vers la version 2 en utilisant l’appel API Mettre à jour les informations sur les paramètres du webhook. Dans la version 1 (par défaut), ces paramètres ne sont pas disponibles.

Exemple de tableau items avec des paramètres supplémentaires :

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Désactivation de l'inclusion du contenu du lot

Par défaut, les webhooks incluent tous les objets du lot sous forme de liste d’objets individuels. Vous pouvez configurer le webhook pour n’inclure que le lot lui-même, sans énumérer son contenu.

Dans ce cas, les objets contenus dans le lot ne sont pas inclus dans le tableau items. Par exemple, dans le tableau ci-dessus, l’objet portant l’UGS com.xsolla.gold_1, qui fait partie du lot, est exclu.

Exemple de tableau items lorsque le contenu du lot est désactivé :

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Pour désactiver l’inclusion du contenu des lots, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

Liens utiles