Pour suivre l’état des commandes créées et les valider, vous devrez configurer le traitement des webhooks côté serveur de votre application.

Pour passer à la nouvelle option avec réception de webhooks combinés, contactez vos responsables de la réussite client ou envoyez un e-mail à csm@xsolla.com.

Pour gérer pleinement le magasin en jeu et les paiements, il est nécessaire d’implémenter le traitement des principaux webhooks :

• Si vous recevez des webhooks combinés
• Si vous recevez des webhooks séparés

Nom du webhook	Description
User validation > Validation utilisateur (user_validation)	Est envoyé à différentes étapes du paiement pour s’assurer que l’utilisateur est bel et bien enregistré dans le jeu.
Game services > Combined webhooks > Paiement de commande réussi (order_paid)	Il contient les données de paiement, les données de la transaction et des informations sur les objets achetés. Utilisez les données du webhook pour attribuer les objets à l’utilisateur.
Game services > Combined webhooks > Annulation de commande (order_canceled)	Il contient les données du paiement annulé, les données de la transaction et des informations sur les objets achetés. Utilisez les données du webhook pour retirer les objets achetés.

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

Nom du webhook	Description
User validation > Validation utilisateur (user_validation)	Est envoyé à différentes étapes du paiement pour s’assurer que l’utilisateur est bel et bien enregistré dans le jeu.
Payments > Paiement (payment)	Il contient des informations sur le paiement et les données de la transaction.
Game services > Separate webhooks > Paiement de commande réussi (order_paid)	Il contient des informations sur les objets achetés et les données de la transaction. Utilisez les données du webhook pour attribuer les objets à l’utilisateur.
Payments > Remboursement (refund)	Il contient des informations sur le paiement et les données de la transaction.
Game services > Separate webhooks > Annulation de commande (order_canceled)	Il contient des informations sur les objets achetés et l’ID de la transaction annulée. Utilisez les données du webhook pour retirer les objets achetés.

Le schéma ci-dessous illustre le processus d’achat et de retour d’objets en utilisant les webhooks distincts.

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

Pour accéder à la liste complète des webhooks et obtenir des informations générales sur leur utilisation, consultez la documentation sur les webhooks.

PHP SDK

Utilisez des classes prêtes à l'emploi pour traiter les webhooks

Configurer l'envoi de webhooks

Pour configurer les webhooks côté Xsolla :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Payments > Webhooks.
2. Dans le champ Webhook server, spécifiez l’URL vers laquelle Xsolla enverra les webhooks.

3. Cliquez sur Enable webhooks.

Ajouter un écouteur webhook

L’écouteur webhook est un code de programme qui permet de recevoir des webhooks entrants à une adresse URL spécifiée, de générer une signature et d’envoyer une réponse au serveur webhook de Xsolla.

Génération d'une signature

Lorsque vous recevez un webhook, vous devez vous assurer de la sécurité de la transmission des données. Pour cela, vous devez générer une signature à partir des données du webhook et vérifier qu’elle correspond à la signature envoyée dans l’en-tête de la requête HTTP.

Pour générer une signature :

1. Concaténez le JSON du corps de la requête avec la clé secrète du projet.
2. Appliquez la fonction de hachage cryptographique SHA-1 à la chaîne obtenue lors de la première étape.

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.

Si le serveur Xsolla ne reçoit pas de réponse aux webhooks Paiement de commande réussi et Annulation de commande ou s’il reçoit une réponse contenant un code 5xx, les webhooks sont renvoyés selon le calendrier suivant :

• 2 tentatives à intervalles de 5 minutes ;
• 7 tentatives à intervalles de 15 minutes ;
• 10 tentatives à intervalles de 60 minutes.

Un maximum de 20 tentatives d’envoi de webhooks sont effectuées dans les 12 heures suivant la première tentative.

Si le serveur Xsolla ne reçoit pas de réponse aux webhooks Paiement ou Remboursement, ou s’il reçoit une réponse contenant un code 5xx, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectuées dans les 12 heures.

Si le serveur Xsolla ne reçoit pas de réponse au webhook Validation utilisateur ou s’il reçoit une réponse contenant un code 400 ou 5xx, le webhook Validation utilisateur n’est pas renvoyé.

Dans ce cas, une erreur est affichée à l’utilisateur et les webhooks Paiement et Paiement de commande réussi ne sont pas envoyés.

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.

Présentation

L’API d’événements Xsolla vous permet d’utiliser le service GetUpdates pour recevoir et traiter les informations de paiement directement depuis le client de votre application, sans recourir aux webhooks sur votre serveur. Cette option accélère et simplifie votre intégration en supprimant le besoin de configurer et de maintenir votre propre serveur de traitement des notifications de paiement.

Interaction entre votre jeu et Xsolla :

Comment configurer

Pour recevoir des événements Xsolla via API :

1. Dans votre projet, dans le Compte éditeur, accédez à la section Payments > Webhooks.
2. Cliquez sur Use API. Les paramètres sont enregistrés automatiquement.

3. Depuis l’application client, envoyez une requête à https://getupdate.xsolla.com/events pour récupérer les informations de paiement. Reportez-vous aux références API pour obtenir des informations détaillées. La réponse contiendra des données de paiement dans le même format que celui utilisé pour le webhook Paiement.
4. En cas de réussite de paiement, l’achat est attribué à l’utilisateur.

Référence API

Lire la liste d'événements non traités pour l'utilisateur

1GET https://getupdate.xsolla.com/events

Sécurité : jeton JWT utilisateur porteur

Exemple de réponse :

 1{
 2  "events": [
 3   {
 4     "id": 49, // event_id
 5     "status": 0,
 6     "created_at": "2025-04-03T21:21:27Z",
 7     "data": {
 8       "notification_type": "payment",
 9       "purchase": {
10         "order": {
11           "id": 000000001,
12           "lineitems": [
13             {
14               "quantity": 1,
15               "sku": "skill"
16             }
17           ]
18         }
19       },
20       ...
21     }
22   }
23 ]
24}

Marquer les événements comme traités

1POST https://getupdate.xsolla.com/events/<event_id>/processed

event_id est le paramètre events.id obtenu à partir de la réponse à l’appel API Lire la liste d’événements non traités pour l’utilisateur.

Sécurité : jeton JWT utilisateur porteur