# Webhooks

# Présentation {% #overview %}

Les webhooks sont des notifications déclenchées par des événements système. 
Lorsqu'un événement spécifique se produit, Xsolla envoie à votre application 
une requête HTTP, généralement sous la forme d'une requête POST au format JSON, 
contenant les données de l'événement.

<strong>Exemples d'événement :</strong>
- interaction de l'utilisateur avec le catalogue des objets ;
- paiement ou annulation d'une commande.

Lorsqu'un événement se produit, Xsolla envoie une notification à votre système 
via un webhook. Vous pouvez ensuite effectuer des actions telles que :
- recharger le solde de l'utilisateur ;
- effectuer un remboursement de paiement ;
- créditer des objets au compte de l'utilisateur ou en débiter ;
- commencer à fournir un abonnement ;
- bloquer un utilisateur en cas de soupçon de fraude.

<b>Exemple de flux de travail d'un webhook de traitement de paiement :</b>

![Webhook de traitement de paiement 
](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)

<div class="note">
<p><strong>Note</strong></p><p>En fonction de la solution utilisée et du type d'intégration, l'ensemble des webhooks et la séquence des interactions peuvent différer de l'exemple fourni.</p>
</div>

<b>Guide vidéo pour l'intégration des webhooks Xsolla :</b>

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 15px; overflow: hidden;">
  <iframe src="https://player.vimeo.com/video/1034591338" style="position: absolute; top:0; left: 0; width: 100%; height: 100%; border:0; border-radius: 15px;" allowfullscreen></iframe>
</div>


<b>Paramètres des webhooks lors de l'interaction avec les produits et solutions Xsolla :</b>

<table>
<thead>
    <tr>
        <th>Produit/Solution</th>
        <th>Obligatoire/Facultatif</th>
        <th>À quoi servent les webhooks ?</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Payments</td>
        <td>Obligatoire</td>
        <td>
          <ul>
            <li>Validation utilisateur.</li>
            <li>Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement.</li>
            <li>Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Store</td>
        <td>Obligatoire</td>
        <td>
          <ul>
            <li>Validation utilisateur.</li>
            <li>Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement.</li>
            <li>Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Game Sales</td>
        <td>Facultatif</td>
        <td>Pour la vente de clés de jeu, la validation utilisateur et le crédit des objets ne sont pas nécessaires. Connectez des webhooks si vous souhaitez recevoir des informations sur des événements tels que le paiement ou l'annulation de commandes.<br />Assurez-vous de traiter tous les <a href="/fr/webhooks/overview/#section/List-of-required-webhooks"> webhooks entrants requis</a>.
</td>
    </tr>
    <tr>
        <td>Subscriptions</td>
        <td>Facultatif</td>
        <td>Réception d'informations sur la création, la mise à jour ou l'annulation d'abonnements. Vous pouvez également <a href="/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_information_set_up_via_api">demander des informations via API</a>.
</td>
    </tr>
    <tr>
        <td>Web Shop</td>
        <td>Obligatoire</td>
        <td>
          <ul>
            <li>Validation utilisateur.</li>
            <li>Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement.</li>
            <li>Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.</li>
            <li>Authentification utilisateur, si vous utilisez l'authentification par ID utilisateur. Vous pouvez également utiliser l'<a href="/solutions/web-shop/authentication-and-analytics/set-up-authentication/#web_shop_guide_shop_with_auth_set_up_auth_xsolla_login_how_to_get_it">authentification utilisateur via Xsolla Login</a>.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Digital Distribution Hub</td>
        <td>Obligatoire</td>
        <td>
          <ul>
            <li>Validation utilisateur.</li>
            <li>Liaison de l'ID de transaction côté Xsolla à l'ID de transaction de votre système.</li>
            <li>Transfert de paramètres de transaction supplémentaires dans la commande.</li>
            <li>Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.</li>
          </ul>
          <p>Reportez-vous à la <a href="/solutions/ddh/#integration_guide_ddh_webhook">documentation</a> pour obtenir plus d'informations sur la configuration des webhooks pour Digital Distribution Hub.</p>
        </td>
    </tr>
    <tr>
        <td>Login</td>
        <td>Facultatif</td>
        <td>
          <p>Réception d'informations sur les événements :</p>
          <ul>
            <li>enregistrement/autorisation d'utilisateur</li>
            <li>confirmation d'adresse e-mail d'utilisateur</li>
            <li>liaison du compte de réseau social de l'utilisateur</li>
          </ul>
          <p>Reportez-vous à la <a href="/api/login/operation/add-webhook-for-event/">documentation Login</a> pour des informations détaillées sur la configuration des webhooks.</p>
        </td>
    </tr>
</tbody>
</table>

# Liste des webhooks requis {% #list-of-required-webhooks %}
Si vous utilisez des produits et des solutions nécessitant de travailler avec 
des webhooks, <a href="/webhooks/overview/#section/Set-up-webhooks-in-Publisher-
Account">activez et testez ces webhooks dans votre Compte éditeur</a>, puis <a 
href="/webhooks/overview/#section/Webhook-listener">configurez leur 
traitement</a>. Lorsque des événements spécifiques se produisent, les webhooks 
sont envoyés de manière séquentielle. Assurez-vous de traiter tous les webhooks 
requis, sinon les suivants ne seront pas envoyés. La liste des webhooks requis 
est présentée ci-dessous.

## Store et Payments {% #store-and-payments %}
Deux options d'envoi de webhook sont configurées côté Xsolla lors de l'achat et 
du retour de biens sur le site : les informations sur les données de paiement 
et de transaction, ainsi que celles sur les biens achetés, peuvent être 
envoyées séparément ou être combinées dans un seul webhook.

<b>Réception d'informations dans des webhooks combinés :</b>

Si vous avez enregistré un <a href="https://publisher.xsolla.com/">Compte 
éditeur</a> après le 22 janvier 2025, vous recevez toutes les informations dans 
les webhooks <a href="/webhooks/operation/successful-order-payment">Paiement de 
commande réussi</a> (`order_paid`) et <a href="/webhooks/operation/order-
cancellation">Annulation de commande</a> (`order_canceled`). Dans ce cas, vous 
n'avez pas besoin de traiter les webhooks <a 
href="/webhooks/operation/payment">Paiement</a> (`payment`) et <a 
href="/webhooks/operation/refund">Remboursement</a> (`refund`).

<b>Réception d'informations dans des webhooks distincts :</b>

Si vous avez enregistré un <a href="https://publisher.xsolla.com/">Compte 
éditeur</a> au plus tard le 22 janvier 2025, vous recevez les webhooks suivants 
:
- <a href="/webhooks/operation/payment">Paiement</a> (`payment`) et <a 
  href="/webhooks/operation/refund">Remboursement</a> (`refund`) avec des 
  informations sur les données de paiement et de transaction.
- <a href="/webhooks/operation/successful-order-payment-separate">Paiement de 
  commande réussi</a> (`order_paid`) et <a href="/webhooks/operation/order-
  cancellation-separate">Annulation de commande</a> (`order_canceled`) avec des 
  informations sur les objets achetés.

Vous devez traiter tous les webhooks entrants. Pour passer à la nouvelle option 
de réception des webhooks combinés, contactez vos responsables de la réussite 
client ou envoyez un e-mail à <a 
href="mailto:csm@xsolla.com">csm@xsolla.com</a>.

Pour assurer le fonctionnement complet du magasin en jeu et de la gestion des 
paiements, il est nécessaire d'implémenter le traitement des principaux 
webhooks.

<b>Si vous recevez des webhooks combinés</b> :

<table>
<thead>
    <tr>
        <th>Nom et type du webhook</th>
        <th>Description</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
        <td>Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu.</td>
    </tr>
    <tr>
        <td>Services de jeux &gt; Webhooks combinés &gt; <a href="/webhooks/operation/successful-order-payment">Paiement de commande réussi</a> (<code>order_paid</code>)</td>
        <td>Il contient les données du paiement et de la transaction ainsi que des informations sur les biens achetés. Utilisez les données du webhook pour octroyer les objets à l'utilisateur.</td>
    </tr>
    <tr>
        <td>Services de jeux &gt; Webhooks combinés &gt; <a href="/webhooks/operation/order-cancellation">Annulation de commande</a> (<code>order_canceled</code>)</td>
        <td>Il contient les données du paiement annulé et de la transaction ainsi que des informations sur les biens achetés. Utilisez les données du webhook pour retirer les objets achetés.</td>
    </tr>
</tbody>
</table>


<b>Si vous recevez des webhooks distincts</b> :

<table>
<thead>
    <tr>
        <th>Nom et type du webhook</th>
        <th>Description</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
        <td>Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu.</td>
    </tr>
    <tr>
        <td>Payments &gt; <a href="/webhooks/operation/payment">Paiement</a> (<code>payment</code>)</td>
        <td>Il contient les données du paiement et de la transaction.</td>
    </tr>
    <tr>
        <td>Services de jeux &gt; Webhooks distincts &gt; <a href="/webhooks/operation/successful-order-payment-separate">Paiement de commande réussi</a> (<code>order_paid</code>)</td>
        <td>Il contient des informations sur les biens achetés. Utilisez les données du webhook pour octroyer les objets à l'utilisateur.</td>
    </tr>
    <tr>
        <td>Payments &gt; <a href="/webhooks/operation/refund">Remboursement</a> (<code>refund</code> )</td>
        <td>Il contient les données du paiement et de la transaction.</td>
    </tr>
    <tr>
        <td>Services de jeux &gt; Webhooks distincts &gt; <a href="/webhooks/operation/order-cancellation-separate">Annulation de commande</a> (<code>order_canceled</code>)</td>
        <td>Il contient des informations sur les biens achetés et l'ID de la transaction annulée. Utilisez les données du webhook pour retirer les objets achetés.</td>
    </tr>
</tbody>
</table>

Si la <a href="/doc/in-game-
store/features/personalization">personnalisation</a> du catalogue des objets 
est implémentée du côté de votre application, configurez le traitement du 
webhook <a href="/webhooks/operation/personalized-partner-
catalog">Personnalisation du catalogue côté partenaire</a>.

<div class="note">
<p><strong>Note</strong></p>
<p>Pour recevoir des paiements réels, vous devez simplement <a href="/doc/in-game-store/integration-guide/sign-licensing-agreement/">signer le contrat de licence</a> et implémenter le traitement des webhooks :</p>
<p><ul><li><a href="/webhooks/operation/payment">Paiement</a>, <a href="/webhooks/operation/successful-order-payment-separate">Paiement de commande réussi</a> et <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> si vous recevez des webhooks distincts ;</li><li><a href="/webhooks/operation/successful-order-payment">Paiement de commande réussi</a> et <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> si vous recevez des webhooks combinés.</li></ul></p>
</div>

## Subscriptions {% #required-webhooks-subscriptions %}
Pour gérer les plans d'abonnement de manière automatique, il est nécessaire 
d'implémenter le traitement des principaux webhooks :
- <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> 
  (`user_validation`) — envoyé à différentes étapes du processus de paiement pour 
  s'assurer que l'utilisateur est bel et bien enregistré dans le jeu.
- <a href="/webhooks/operation/payment">Paiement</a> (`payment`) — envoyé 
  lorsqu'une commande est payée et contient les données de paiement ainsi que les 
  détails de la transaction.
- <a href="/webhooks/operation/created-subscription/">Abonnement créé</a> 
  (`create_subscription`) — envoyé lorsqu'un webhook <a 
  href="/webhooks/operation/payment">Paiement</a> est traité avec succès ou 
  lorsque l'utilisateur achète un abonnement avec une période d'essai. Il 
  contient les détails de l'abonnement acheté ainsi que les données de 
  l'utilisateur. Utilisez les données du webhook pour ajouter l'abonnement à 
  l'utilisateur.
- <a href="/webhooks/operation/updated-subscription/">Abonnement mis à jour</a> 
  (`update_subscription`) — envoyé lorsqu'un abonnement est renouvelé ou modifié, 
  lorsqu'un webhook <a 
  href="https://developers.xsolla.com/fr/webhooks/operation/payment">Paiement</a> 
  est traité avec succès. Il contient les détails de l'abonnement acheté et les 
  données de l'utilisateur. Utilisez les données du webhook pour prolonger 
  l'abonnement de l'utilisateur ou modifier les paramètres de l'abonnement.
- <a href="/webhooks/operation/refund">Remboursement</a> (`refund`) — envoyé 
  lorsqu'une commande est annulée et contient les données du paiement annulé 
  ainsi que les détails de la transaction.
- <a href="/webhooks/operation/canceled-subscription/">Abonnement annulé</a> 
  (`cancel_subscription`) — envoyé lorsqu'un webhook <a 
  href="/webhooks/operation/refund">Remboursement</a> est traité avec succès ou 
  lorsque l'abonnement est annulé pour une autre raison. Il contient des 
  informations sur l'abonnement et les données de l'utilisateur. Utilisez les 
  données du webhook pour déduire les abonnements achetés de l'utilisateur.

# Configurer les webhooks dans le Compte éditeur {% #set-up-webhooks-in-publisher-account %}

## Paramètres généraux {% #general-settings %}

Pour activer la réception des webhooks :
1. Dans le projet dans le Compte éditeur, accédez à la section <a 
   href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>.
2. Dans le champ <b>Webhook server</b>, spécifiez l'URL du serveur où vous 
   souhaitez recevoir des webhooks au format `https://example.com`. Vous pouvez 
   également indiquer l'URL que vous trouvez dans un outil de test de webhooks.

<div class="notice">
<p><strong>Attention</strong></p>
<p> Le protocole HTTPS est utilisé pour transférer les données ; le protocole HTTP n'est pas pris en charge.</p>
</div>

<p></p>

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

<ol><ol type="a">
<li>Dans la section <strong>Secret keys</strong>, appuyez sur <strong>Add key</strong>.</li>
<li>Dans la fenêtre modale qui s'ouvre, entrez un nom pour identifier facilement la clé dans la liste générale.</li>
<li>Appuyez sur <strong>Create key</strong>.</li>
<li>Appuyez sur <strong>Copy secret</strong> et enregistrez la clé générée de votre côté.</li>
<li>Appuyez sur <strong>Done</strong>.</li>
<li>Confirmez que vous avez bel et bien enregistré la clé et appuyez sur <strong>Ok, close</strong>.</li>
</ol></ol>

![Ajoutez une 
clé](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-key.svg)

<div class="notice">
<p><strong>Important</strong></p>
<p>Recommandations concernant la clé :<ul>
<li><strong>Enregistrez la clé secrète générée de votre côté.</strong> Elle s'affichera qu'une seule fois dans le Compte éditeur, au moment de sa création.</li>
<li>Ne communiquez votre clé secrète à personne.</li>
<li>La clé secrète doit être stockée sur votre serveur et jamais dans des binaires ni côté client.</li></ul>
</p>
</div>

4. Appuyez sur **Enable webhooks**.

<div class="note">
<p><strong>Note</strong></p>
<p>Pour tester les webhooks, sélectionnez n'importe quel site Web dédié, tel que <a href="https://webhook.site/#!/">webhook.site</a>, ou une plateforme, telle que <a href="https://ngrok.com/">ngrok</a>.</p>
</div>

<p></p>

<div class="notice">
    <p><strong>Remarque</strong></p>
    <p>Il est impossible d'envoyer simultanément des webhooks à différentes URL. Une approche consiste à spécifier d'abord une URL pour les tests dans le Compte éditeur, puis à la remplacer par l'URL réelle.</p>
</div>

Pour désactiver la réception de webhooks :
1. Dans le projet dans le Compte éditeur, accédez à la section <a 
   href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>.
2. Cliquez sur <b>Disable webhooks</b>.

## Rotation des clés secrètes {% #secret-key-rotation %}

La rotation régulière des clés secrètes renforce la sécurité de votre 
intégration. Créez jusqu'à 5 clés secrètes par projet afin de faciliter leur 
rotation. Pour ce faire, suivez les étapes ci-dessous :

1. Dans la section <a 
   href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>, appuyez sur **Add key**.

![Ajoutez une 
clé](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-new-key.svg)

2. Dans la fenêtre modale qui s'ouvre, entrez un nom pour identifier facilement la 
   clé dans la liste générale.
3. Appuyez sur **Create key**.
4. Appuyez sur **Copy secret** et enregistrez la clé générée de votre côté.
5. Appuyez sur **Done**.
6. Confirmez que vous avez bel et bien enregistré la clé et appuyez sur **Ok, 
   close**.

<div class="notice">
<p><strong>Important</strong></p>
<p>Recommandations concernant la clé :<ul>
<li><strong>Enregistrez la clé secrète générée de votre côté.</strong> Elle s'affichera qu'une seule fois dans le Compte éditeur, au moment de sa création.</li>
<li>Ne communiquez votre clé secrète à personne.</li>
<li>La clé secrète doit être stockée sur votre serveur et jamais dans des binaires ni côté client.</li></ul>
</p>
</div>

Il ne peut y avoir qu'une seule clé secrète 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 la nouvelle clé effectuée, nous 
vous recommandons de supprimer les clés désactivées.

![Changez une clé 
active](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/activate-key.svg)

## Paramètres avancés {% #advanced-settings %}

Pour les webhooks de la section <a href="/webhooks/overview/#section/Test-
webhooks-in-Publisher-Account/Store">Payments and Store</a>, des paramètres 
avancés sont disponibles. Ils apparaîtront automatiquement sous le bloc <a 
href="/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account/General-
settings">General settings</a> après que vous aurez cliqué sur le bouton <b>Get 
webhooks</b>.

<div class="note">
<p><strong>Note</strong></p>
<p>Si les paramètres avancés ne s'affichent pas, assurez-vous que la réception de webhook est connectée dans les paramètres généraux et que vous êtes sur l'onglet <b>Testing &gt; Payments and Store</b>.</p>
</div>

Dans cette section, vous pouvez configurer la réception d'informations 
supplémentaires dans les webhooks. Pour ce faire, réglez les bascules 
correspondantes en position active. La ligne de chaque autorisation indique les 
webhooks qui seront affectés par la modification des paramètres.

<table>
<thead>
    <tr>
        <th>Bascule</th>
        <th>Description</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Afficher les informations du compte de paiement enregistré (visible uniquement si votre Compte éditeur a été créé au plus tard le 22 janvier 2025 et si vous recevez des webhooks distincts).</td>
        <td>Les informations relatives au mode de paiement enregistré sont passées à l'objet personnalisé <code>payment_account</code>.</td>
    </tr>
    <tr>
        <td>Afficher les informations relatives aux transactions effectuées via les modes de paiement enregistrés.</td>
        <td><p>Les informations sont passées dans les paramètres personnalisés suivants du webhook :</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — le mode de paiement enregistré n'a pas été utilisé ;</li><li><code>1</code> — le mode de paiement a été enregistré lors du paiement en cours ;</li><li><code>2</code> — le mode de paiement précédemment enregistré est utilisé.</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — paiement unique ;</li><li><code>2</code> — paiement récurrent.</li></ul></li></ul></td>
    </tr>
    <tr>
        <td>Ajouter l'objet <code>order</code> au webhook (affiché uniquement si votre Compte éditeur a été créé au plus tard le 22 janvier 2025 et que vous recevez des webhooks distincts).</td>
        <td>Les informations relatives à la commande sont passées dans l'objet <code>order</code> du webhook <a href="/webhooks/operation/payment/">Paiement</a>.</td>
    </tr>
    <tr>
        <td>Envoyer uniquement des paramètres utilisateur nécessaires sans données sensibles.</td>
        <td><p>Seules les informations suivantes sur l'utilisateur sont passées dans le webhook :</p><ul><li>ID ;</li><li>pays.</li></ul></td>
    </tr>
    <tr>
        <td>Envoyer des paramètres personnalisés</td>
        <td>Les informations relatives aux <a href="/api/pay-station/operation/create-token/">paramètres du jeton personnalisé</a> sont passées dans le webhook.</td>
    </tr>
    <tr>
        <td>Afficher le BIN et le suffixe de la carte.</td>
        <td><p>Les informations suivantes sur le numéro de la carte bancaire sont passées dans le webhook :</p><ul><li>les 6 premiers chiffres du paramètre <code>card_bin</code> ;</li><li>les 4 derniers chiffres du <code>card_suffix</code>.</li></ul></td>
    </tr>
    <tr>
        <td>Afficher marque de carte.</td>
        <td>La marque de la carte utilisée pour effectuer le paiement. Par exemple, Mastercard ou Visa.</td>
    </tr>
    <tr>
        <td>Afficher des informations sur le motif du remboursement.</td>
        <td>Informations détaillées sur les motifs de remboursement.</td>
    </tr>
    <tr>
        <td>Afficher les frais de retenue à la source par pays et les frais d'acquisition utilisateur.</td>
        <td>Les objets <code>payment_details.​country_wht</code> et <code>payment_details.​user_acquisition_fee</code> seront passés dans le webhook. Cette option est activée par défaut.</td>
    </tr>
    <tr>
        <td>Envoyer les informations 3DS.</td>
        <td>L'objet <code>cards</code> contenant des données sur la vérification 3-D Secure sera passé dans le webhook.</td>
    </tr>
</tbody>
</table>

![Paramètres 
avancés](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/advanced-settings.png)

# Tester les webhooks dans le Compte éditeur {% #test-webhooks-in-publisher-account %}

Tester les webhooks permet de s'assurer de la bonne configuration du projet, 
tant de votre côté que du côté de Xsolla.

Si les webhooks sont <a href="/webhooks/overview/#section/Set-up-webhooks-in-
Publisher-Account">configurés</a> avec succès, une section de test des webhooks 
s'affiche sous celle de configuration des webhooks.

![Section de test des 
webhooks](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-section.svg)

La section de test dans le Compte éditeur varie en fonction de l'option de 
réception du webhook.

Si vous avez enregistré votre Compte éditeur après le 22 janvier 2025, vous 
recevrez des webhooks combinés :

<table>
<thead>
    <tr>
        <th>Nom de l'onglet pour le test du webhook</th>
        <th>Nom et type du webhook</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><b>Payments and store</b></td>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Services de jeux &gt; Webhooks combinés &gt; <a href="/webhooks/operation/successful-order-payment">Paiement de commande réussi</a> (<code>order_paid</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Services de jeux &gt; Webhooks combinés &gt; <a href="/webhooks/operation/order-cancellation">Annulation de commande</a> (<code>order_canceled</code>)</td>
    </tr>
    <tr>
        <td><b>Subscriptions</b></td>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Payments &gt; <a href="/webhooks/operation/payment">Paiement</a> (<code>payment</code>)</td>
    </tr>
</tbody>
</table>


Si vous avez enregistré votre Compte éditeur avant ou le 22 janvier 2025, vous 
recevrez des webhooks distincts :

<table>
<thead>
    <tr>
        <th>Nom de l'onglet pour le test du webhook</th>
        <th>Nom et type du webhook</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><b>Store</b></td>
        <td>Services de jeux &gt; Webhooks distincts &gt; <a href="/webhooks/operation/successful-order-payment-separate">Paiement de commande réussi</a> (<code>order_paid</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Services de jeux &gt; Webhooks distincts &gt; <a href="/webhooks/operation/order-cancellation-separate">Annulation de commande</a> (<code>order_canceled</code>)</td>
    </tr>
    <tr>
        <td><b>Payments</b></td>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Payments &gt; <a href="/webhooks/operation/payment">Paiement</a> (<code>payment</code>)</td>
    </tr>
    <tr>
        <td><b>Subscriptions</b></td>
        <td>Validation utilisateur &gt; <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Payments &gt; <a href="/webhooks/operation/payment">Paiement</a> (<code>payment</code>)</td>
    </tr>
</tbody>
</table>

<div class="note">
<p><strong>Note</strong></p>
<p>Si un avertissement indiquant que le test a échoué apparaît dans la section de test, vérifiez les paramètres de réponse du webhook dans votre <a href="/webhooks/overview/#section/Webhook-listener">écouteur webhook</a>. Les raisons des erreurs dans les tests sont indiquées dans les résultats.</p>
<p><b>Exemple :</b></p>
<p>Vous utilisez le site spécialisé <a href="https://webhook.site/#!/">webhook.site</a> pour effectuer des tests.</p>
<p>Une erreur s'affiche dans la section <b>Testing response to invalid signature</b>.</p>
<p>Cela se produit parce que Xsolla envoie un webhook avec une signature incorrecte et s'attend à ce que votre gestionnaire réponde avec un code HTTP <code>4xx</code> spécifiant le code d'erreur <code>INVALID_SIGNATURE</code>.</p>
<p><a href="https://webhook.site/#!/">webhook.site</a> renvoie un code HTTP <code>200</code> en réponse à tous les webhooks, y compris à ceux avec une signature incorrecte. Le code HTTP <code>4xx</code> attendu ne pouvant pas être obtenu, une erreur apparaît dans le résultat du test.</p>
</div>

Le processus de test du scénario avec des webhooks combinés est décrit ci-
dessous.

## Payments and Store {% #payments-and-store %}

Dans l'onglet <b>Payments and Store</b>, vous pouvez tester les webhooks 
suivants :
- <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> 
  (`user_validation`) ;
- <a href="/webhooks/operation/successful-order-payment">Paiement de commande 
  réussi</a> (`order_paid`) ;
- <a href="/webhooks/operation/order-cancellation">Annulation de commande</a> 
  (`order_canceled`).

Pour tester les webhooks :
1. Dans la section de test des webhooks, accédez à l'onglet <b>Payments and 
   Store</b>.
2. Dans la liste déroulante, sélectionnez le type d'objet. Si ce type n'est pas 
   encore configuré dans le Compte éditeur, appuyez sur le bouton pour le 
   configurer. Une fois l'objet créé, revenez à la section de test des webhooks et 
   passez à l'étape suivante.
3. Remplissez les champs nécessaires :
   * **User ID** — lors des tests, vous pouvez utiliser n'importe quelle combinaison 
     de lettres et de chiffres.
   * Entrez une valeur aléatoire dans le champ **Xsolla order ID**
   * **Xsolla invoice ID** — ID de transaction côté Xsolla. Lors des tests, vous 
     pouvez utiliser n'importe quelle valeur numérique.
   * **Invoice ID** — ID de transaction côté de votre jeu. Lors des tests, vous 
     pouvez utiliser n'importe quelle combinaison de lettres et de chiffres. Ce 
     n'est pas un paramètre requis pour un paiement réussi, mais vous pouvez le 
     transmettre pour lier l'ID de transaction de votre côté à l'ID de transaction 
     côté Xsolla.
   * **Amount** — montant du paiement. Lors des tests, vous pouvez utiliser 
     n'importe quelle valeur numérique.
   * **Currency** — sélectionnez une devise dans la liste déroulante.
   * Sélectionnez l'UGS de l'objet dans la liste déroulante et indiquez le montant. 
     Pour choisir plusieurs objets du même type, appuyez sur **+** et ajoutez-les 
     sur une nouvelle ligne.
4. Appuyez sur **Test webhooks**.

Les webhooks <a href="/webhooks/operation/user-validation/">Validation 
urilisateur</a>, <a href="/webhooks/operation/successful-order-
payment">Paiement de commande réussi</a> et <a href="/webhooks/operation/order-
cancellation">Annulation de commande</a> avec les données spécifiées sont 
envoyés à l'URL fournie. Les résultats du test de chaque type de webhook sont 
affichés sous le bouton <b>Tester les webhooks</b>.

Si la case <b>Use public user ID</b> est cochée dans la section <a 
href="https://publisher.xsolla.com/0/projects/0/edit/advanced">Project settings 
> Integration settings</a>, le webhook <a href="/webhooks/user-validation/user-
search">User search</a> sera également envoyé à l'URL de votre serveur de 
webhooks et le résultat du test s'affichera.

Il est nécessaire de configurer le traitement des deux scénarios pour chaque 
webhook : un scénario réussi et un scénario avec une erreur.

![Section de test des 
paiements](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-results.svg)

## Subscriptions {% #test-webhooks-subscriptions %}

<div class="note">
<p><strong>Remarque</strong></p>
<p>Pour tester les webhooks, vous devez avoir au moins un <a href="/sell-subscriptions/integration-guide/set-up-plan/">plan d'abonnement créé</a> dans le Compte éditeur dans la section <a href="https://publisher.xsolla.com/0/projects/0/subscriptions/plans">Items catalog&gt; Subscriptions</a>.</p>
</div>

Dans l'onglet <b>Subscriptions</b>, vous pouvez tester les webhooks suivants :
- <a href="/webhooks/operation/user-validation/">Validation utilisateur</a> 
  (`user_validation`) ;
- <a href="/webhooks/operation/payment">Paiement</a> (`payment`).

<div class="note">
<p><strong>Remarque</strong></p>
<p>Vous trouverez des informations détaillées sur le test d'autres scénarios de gestion des abonnements dans le <a href="/sell-subscriptions/integration-guide/set-up-plan/#guides_subscriptions_set_up_plan_testing_purchase">guide d'intégration</a>.</p>
</div>

Pour tester les webhooks :

1. Dans la section de test, accédez à l'onglet **Subscriptions**.
2. Remplissez les champs nécessaires :
   * **User ID** — lors des tests, vous pouvez utiliser n'importe quelle combinaison 
     de lettres et de chiffres.
   * **Xsolla invoice ID** — ID de transaction côté Xsolla. Lors des tests, vous 
     pouvez utiliser n'importe quelle valeur numérique.
   * **Public user ID** — ID connu de l'utilisateur, par exemple, un e-mail ou un 
     pseudo. Ce champ s'affiche si vous avez coché la case **Use public user ID** 
     dans le projet dans la section [Project settings > Integration 
     settings](https://publisher.xsolla.com/0/projects/0/edit/advanced).
   * **Amount** — montant du paiement. Lors des tests, vous pouvez utiliser 
     n'importe quelle valeur numérique.
   * **Currency** — sélectionnez une devise dans la liste déroulante.
   * **Plan ID** — un plan d'abonnement. Choisissez un plan dans la liste déroulante.
   * **Subscription product** — choisissez un produit dans la liste déroulante 
     (facultatif). La liste s'affiche si des [produits](/fr/sell-subscriptions/integration-guide/get-started/#guides_subscriptions_glossary_product) sont 
     configurés dans le projet.
   * **Invoice ID** — ID de transaction côté de votre jeu. Lors des tests, vous 
     pouvez utiliser n'importe quelle combinaison de lettres et de chiffres. Ce 
     n'est pas un paramètre requis pour un paiement réussi, mais vous pouvez le 
     transmettre pour lier l'ID de transaction de votre côté à l'ID de transaction 
     côté Xsolla.
   * **Trial period**. Pour tester l'[achat d'un abonnement sans période d'essai
     ](/fr/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_sandbox) ou 
     pour tester le [renouvellement d'un abonnement](/fr/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal)
     , spécifiez la valeur `0`.
3. Appuyez sur **Test**.

À l'URL spécifiée, vous recevrez des webhooks avec les données remplies. Les 
résultats des tests de chaque webhook, pour un scénario réussi et un scénario 
avec une erreur, sont affichés sous le bouton <b>Test</b>.

# Écouteur webhook {% #webhook-listener %}

L'écouteur webhook est un code de programme qui permet de recevoir des webhooks 
entrants à une adresse URL spécifiée, de <a href="/webhooks/overview/#section
/Webhook-listener/Generation-of-signature">générer une signature</a> et d'<a 
href="/webhooks/overview/#section/Webhook-listener/Sending-responses-to-
webhook">envoyer une réponse</a> au serveur webhook de Xsolla.

<div class="note">
<p><strong>Note</strong></p>
<p>Vous pouvez utiliser la <a href="https://developers.xsolla.com/fr/sdk/php/">bibliothèque Pay Station PHP SDK</a>, qui contient des classes prêtes à l'emploi, pour le traitement des webhooks.</p>
</div>

<!-- IMPORTANT! Changing the list of IP addresses should be coordinated with the administrators. Request for Director of Infrastructure and IT approval in the ticket for changing the IP address list. -->

Du côté de votre application, implémentez la réception des webhooks envoyés 
depuis les adresses IP suivantes :
- `185.30.20.0/24`
- `185.30.21.0/24`
- `185.30.22.0/24`
- `185.30.23.0/24`
- `34.102.38.178`
- `34.94.43.207`
- `35.236.73.234`
- `34.94.69.44`
- `34.102.22.197`

Si vous avez intégré le produit <a href="/doc/login/">Login</a>, ajoutez 
également le traitement des webhooks envoyés depuis les adresses IP suivantes :

- `34.94.0.85`
- `34.94.14.95`
- `34.94.25.33`
- `34.94.115.185`
- `34.94.154.26`
- `34.94.173.132`
- `34.102.48.30`
- `35.235.99.248`
- `35.236.32.131`
- `35.236.35.100`
- `35.236.117.164`

Restrictions :
- La base de données de votre application ne doit pas contenir plusieurs 
  transactions réussies avec le même ID.
- Si l'écouteur reçoit un webhook avec un ID qui existe déjà dans la base de 
  données, renvoyez le résultat précédent du traitement de cette transaction. Il 
  est déconseillé de créditer l'utilisateur pour un achat déjà effectué et de 
  créer des enregistrements en double dans la base de données.

## Génération de la signature {% #generation-of-signature %}

Pour garantir la sécurité de la transmission des données, vérifiez que le 
webhook provient bien du serveur Xsolla et qu’il n’a pas été altéré pendant le 
transport. Pour ce faire, générez votre propre signature sur la base de la 
charge utile du corps de la requête et comparez-la à celle fournie dans l’en-
tête `authorization` de la requête entrante. Si les deux signatures 
correspondent, le webhook est authentique et peut être traité en toute sécurité.

Étapes de vérification :

1. Récupérez la signature depuis l’en-tête `authorization` de la requête webhook 
   entrante. Le format de cet en-tête est : `Signature <signature_value>`.
2. Récupérez le corps de la requête webhook au format JSON. <div 
   class="notice"><p><strong>Remarque</strong></p><p>Utilisez la charge utile JSON 
   exactement telle qu’elle est reçue. Ne la parsez ni ne la réencodez, car cela 
   modifierait son formatage et entraînerait l’échec de la vérification de la 
   signature.</p></div><p></p>

3. Générez votre propre signature à des fins de comparaison : <ol type="a"> 
   <li>Concaténez la charge utile JSON avec la clé secrète de votre projet, en 
   ajoutant cette dernière à la fin de la chaîne.</li> <li>Appliquez la fonction 
   de hachage cryptographique SHA-1 à la chaîne obtenue. Le résultat sera une 
   chaîne hexadécimale en minuscules.</li> </ol>
4. Comparez la signature que vous avez générée avec celle fournie dans l’en-tête 
   `authorization`. Si elles correspondent, le webhook est authentique.

Voici des exemples d’implémentation de la génération de signatures pour les 
langages suivants : C#, C++, Go, PHP et Node.js.

### Exemple de webhook (HTTP) : {% #example-of-a-webhook-http %}

```http
POST /your_uri HTTP/1.1
host: your.host
accept: application/json
content-type: application/json
content-length: 165
authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}
```

### Exemple de webhook (curl) : {% #example-of-a-webhook-curl %}

```bash
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'
```

### Exemple d'implémentation de la génération de signatures en C# (exemple général) : {% #csharp-signature-generation-general-sample %}

<div class="note">
<p><strong>Note</strong></p>
<p>Ce code fonctionne avec .NET Framework 4.0 et versions ultérieures, .NET Core et d'autres versions récentes de .NET. La vérification des signatures utilise <code>ConstantTimeEquals</code> pour une comparaison en temps constant, réduisant le risque d'attaques temporelles.</p>
</div>

```csharp
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        // Concatenation of the JSON from the request body and the project's secret key
        string dataToSign = jsonBody + secretKey;
        using (SHA1 sha1 = SHA1.Create())
        {
            byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
            // Convert hash bytes to lowercase hexadecimal string
            var hexString = new StringBuilder(hashBytes.Length * 2);
            foreach (byte b in hashBytes)
            {
                hexString.Append(b.ToString("x2"));
            }
            return hexString.ToString();
        }
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}
```

### Exemple C# d'implémentation de la génération de signatures (.NET 5.0 et versions supérieures) : {% #csharp-signature-generation-net-5-0-and-later %}

<div class="note">
<p><strong>Note</strong></p>
<p>La méthode <code>Convert.ToHexString</code> nécessite .NET 5.0 ou ultérieure.<p></p>Avec .NET 7.0 ou ultérieure, vous pouvez aussi utiliser la méthode <code>CryptographicOperations.FixedTimeEquals</code> à la place de <code>ConstantTimeEquals</code>.</p>
</div>

```csharp
// For .NET 5.0 and later, you can use the more concise Convert.ToHexString method:
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        string dataToSign = jsonBody + secretKey;
        using var sha1 = SHA1.Create();
        byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
        return Convert.ToHexString(hashBytes).ToLower();
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}
```

### Exemple C# d'implémentation de la génération de signatures (.NET 7.0 et versions supérieures) : {% #csharp-signature-generation-net-7-0-and-later %}

<div class="note">
<p><strong>Note</strong></p>
<p>Si vous disposez de .NET 7.0 ou ultérieure, vous pouvez utiliser la méthode <code>CryptographicOperations.FixedTimeEquals</code>.</p>
</div>

```csharp
// For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals:
using System.Security.Cryptography;
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
    string computedSignature = ComputeSha1(jsonBody, secretKey);
    byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature);
    byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower());
    return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes);
}
```

### Exemple d'implémentation de la génération de signatures en C++ : {% #cpp-signature-generation %}

```c++
#include <string>
#include <sstream>
#include <iomanip>
#include <openssl/sha.h>
class XsollaWebhookSignature {
public:
    static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        std::string dataToSign = jsonBody + secretKey;
        unsigned char digest[SHA_DIGEST_LENGTH];
        // Create SHA1 hash
        SHA1(reinterpret_cast<const unsigned char*>(dataToSign.c_str()),
             dataToSign.length(), digest);
        // Convert to lowercase hexadecimal string
        std::ostringstream hexStream;
        hexStream << std::hex << std::setfill('0');
        for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) {
            hexStream << std::setw(2) << static_cast<unsigned int>(digest[i]);
        }
        return hexStream.str();
    }
    static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) {
        std::string computedSignature = computeSha1(jsonBody, secretKey);
        // Timing-safe comparison
        if (computedSignature.length() != receivedSignature.length()) {
            return false;
        }
        volatile unsigned char result = 0;
        for (size_t i = 0; i < computedSignature.length(); ++i) {
            result |= (computedSignature[i] ^ receivedSignature[i]);
        }
        return result == 0;
    }
};
```

### Exemple d'implémentation de la génération de signatures en Go : {% #go-signature-generation %}

```go
package main
import (
	"crypto/sha1"
    "crypto/subtle"
	"encoding/hex"
	"strings"
)
type XsollaWebhookSignature struct{}
func (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {
	// Concatenation of the JSON from the request body and the project's secret key
	dataToSign := jsonBody + secretKey
	// Create SHA1 hash
	h := sha1.New()
	h.Write([]byte(dataToSign))
	signature := h.Sum(nil)
	// Convert to lowercase hexadecimal string
	return strings.ToLower(hex.EncodeToString(signature))
}
func (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {
	computedSignature := x.ComputeSha1(jsonBody, secretKey)
	receivedSignatureLower := strings.ToLower(receivedSignature)
	// Use constant time comparison to prevent timing attacks
	return subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1
}
```

### Exemple d'implémentation de la génération de signatures en PHP : {% #php-signature-generation %}

```php
<?php
class XsollaWebhookSignature
{
    /**
     * Compute SHA1 signature from webhook JSON body and secret key
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key
     * @return string The lowercase SHA1 signature
     */
    public static function computeSha1(string $jsonBody, string $secretKey): string
    {
        // Concatenation of the JSON from the request body and the project's secret key
        $dataToSign = $jsonBody . $secretKey;
        // Generate SHA1 signature
        $signature = sha1($dataToSign);
        return strtolower($signature);
    }
    /**
     * Verify webhook signature using timing-safe comparison
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key  
     * @param string $receivedSignature The signature from authorization header
     * @return bool True if signature is valid, false otherwise
     */
    public static function verifySignature(string $jsonBody, string $secretKey, string $receivedSignature): bool
    {
        $computedSignature = self::computeSha1($jsonBody, $secretKey);
        // Use hash_equals for timing-safe comparison
        return hash_equals($computedSignature, strtolower($receivedSignature));
    }
}
?>
```

### Exemple d'implémentation de la génération de signatures en Node.js : {% #nodejs-signature-generation %}

```js
const crypto = require('crypto');
class XsollaWebhookSignature {
    // IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla
    static computeSha1(jsonBody, secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        const dataToSign = jsonBody + secretKey;
        // Create SHA1 hash
        const hash = crypto.createHash('sha1');
        hash.update(dataToSign, 'utf8');
        // Convert to lowercase hexadecimal string
        return hash.digest('hex').toLowerCase();
    }
    static verifySignature(jsonBody, secretKey, receivedSignature) {
        const computedSignature = this.computeSha1(jsonBody, secretKey);
        const cleanReceivedSignature = receivedSignature.toLowerCase();
        // Check if signatures have the same length before using timingSafeEqual
        if (computedSignature.length !== cleanReceivedSignature.length) {
            return false;
        }
        try {
            return crypto.timingSafeEqual(
                Buffer.from(computedSignature, 'hex'),
                Buffer.from(cleanReceivedSignature, 'hex')
            );
        } catch (error) {
            // Return false if there's any error (e.g., invalid hex characters)
            return false;
        }
    }
}
```

## Envoi de réponses au webhook {% #sending-responses-to-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 <a 
  href="/webhooks/overview/#section/Erreurs">description du problème</a> au cas où 
  l'utilisateur spécifié n'a pas été trouvé ou une signature non valide a été 
  passée. Le gestionnaire de webhook peut également renvoyer un code HTTP `5xx` 
  en cas de problèmes temporaires sur votre serveur.

Si le serveur Xsolla n'a pas reçu de réponse aux webhooks <a 
href="/webhooks/operation/successful-order-payment">Paiement de commande 
réussi</a> et <a href="/webhooks/operation/order-cancellation">Annulation de 
commande</a>, 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.

La logique de réessai pour les webhooks <a 
href="/webhooks/operation/payment">Payment</a> et <a 
href="/webhooks/operation/refund">Refund</a> est décrite sur la page du webhook 
concerné.

<div class="notice">
<p><strong>Remarque</strong></p>
<p>Le paiement sera quand même remboursé à l'utilisateur si toutes les conditions suivantes sont réunies :<ul><li>Xsolla a initié le remboursement.</li><li>En réponse au webhook, un code d'état <code>4xx</code> est renvoyé, ou aucune réponse n'est reçue après toutes les tentatives, ou un code d'état <code>5xx</code> est renvoyé.</li></ul></p>
</div>

Si le serveur Xsolla n'a pas reçu de réponse au webhook <a 
href="/webhooks/operation/user-validation/">Validation utilisateur</a> ou s'il 
a reçu une réponse contenant un code `400` ou `5xx`, le webhook <a 
href="/webhooks/operation/user-validation/">Validation utilisateur</a> n'est 
pas renvoyé. Dans ce cas, l'utilisateur voit une erreur et les webhooks <a 
href="/webhooks/operation/payment">Paiement</a> et <a href="/webhooks/operation
/successful-order-payment">Paiement de commande réussi</a> ne sont pas envoyés.

# Erreurs {% #errors %}

Codes d'erreur pour le code HTTP 400 :

<table>
<thead>
    <tr>
        <th>Code</th>
        <th>Message</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>INVALID_USER</td>
        <td>Utilisateur non valide</td>
    </tr>
    <tr>
        <td>INVALID_PARAMETER</td>
        <td>Paramètre non valide</td>
    </tr>
    <tr>
        <td>INVALID_SIGNATURE</td>
        <td>Signature non valide</td>
    </tr>
    <tr>
        <td>INCORRECT_AMOUNT</td>
        <td>Montant incorrect</td>
    </tr>
    <tr>
        <td>INCORRECT_INVOICE</td>
        <td>Facture incorrecte</td>
    </tr>
</tbody>
</table>

```
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}
```

# Bonnes pratiques {% #best-practices %}

## Sécurité {% #security %}

Suivez ces lignes directrices :

* Utilisez uniquement le protocole HTTPS, avec un certificat valide.
* Vérifiez toujours la signature à partir du corps brut de la requête ; 
  n'analysez pas et ne réencodez pas les données.
* Ne passez pas de données sensibles dans les URL et évitez de divulguer des 
  détails techniques dans les messages d'erreur.
* Exemptez le point de terminaison du webhook du middleware 
  [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery). Les requêtes 
  entrantes de Xsolla n'incluent pas de jeton CSRF et seront rejetées sans ce 
  paramètre.
* Liste blanche [Adresses IP de Xsolla](/fr/webhooks/section/webhook-listener).


## Architecture du gestionnaire de webhook {% #webhook-handler-architecture %}

Suivez ces lignes directrices :

1. Acceptez la requête `POST` avec son corps et ses en-têtes tels quels, **sans 
   modification**.
2. [Vérifiez la signature du webhook](/fr/webhooks/section/webhook-listener/generation-of-signature) et renvoyez le code d'état approprié :
   * `4xx` : si les signatures ne correspondent pas ;
   * `2xx` : en cas de succès. Nous recommandons de renvoyer 204 `No Content` 
     **avant** d'exécuter la logique métier principale. `200 OK` est également 
     acceptable.
3. Passez la charge utile à une tâche asynchrone ou à une file d'attente pour un 
   traitement ultérieur.
4. Implémentez 
   l'[idempotence](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning). Vous devez vous assurer que votre système est capable de gérer la 
   [réception d'un même webhook plusieurs fois](/fr/webhooks/section/webhook-listener/sending-responses-to-webhook).

**Exemple de flux :**

```http
HTTP POST /webhooks/xsolla
  read raw_body, headers
  if !verify_signature(raw_body, headers['authorization']):
     return 400 {"error":{"code":"INVALID_SIGNATURE","message":"Invalid signature"}}
  enqueue(raw_body)
  return 204  # or 200
```

## Idempotence et doublons {% #idempotency-and-duplicates %}

Suivez ces lignes directrices :

* Utilisez l'ID de transaction et/ou l'[ID externe](/fr/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id), ainsi que 
  l'ID de commande comme clés d'idempotence.
* Enregistrez les identifiants traités et renvoyez le résultat précédent en cas 
  de doublon.
* Évitez les réattributions d'objets, les doublons en base de données et les 
  doubles facturations.
* Gardez à l'esprit qu'avec une livraison séquentielle, un échec sur un événement 
  antérieur bloque le traitement de tous les suivants.

## Résilience du système {% #system-resilience %}

Suivez ces lignes directrices :

* Utilisez des files d'attente et un traitement asynchrone pour les opérations 
  gourmandes en ressources, comme les appels à des API tierces, la facturation et 
  l'attribution d'objets.
* Définissez des délais d'expiration pour le gestionnaire de webhook (1 à 3 s). 
  En cas d'échecs temporaires, appuyez-vous sur le [mécanisme de réessai de 
  Xsolla](/fr/webhooks/section/webhook-listener/sending-responses-to-webhook).
* N'implémentez pas de tentatives de réessai dans le gestionnaire de webhook : 
  cela est pris en charge par Xsolla.
* Enregistrez les horodatages de livraison des webhooks et les statuts de 
  traitement ; configurez des alertes en cas de pics d'erreurs `5xx` et de 
  nouvelles tentatives de passage.
* Transférez les ID de corrélation du webhook vers vos journaux et votre système 
  de surveillance (APM).
* Configurez la journalisation et le suivi des erreurs. En cas d'échec non 
  récupérable, transférez les tâches vers une file de messages morts (DLQ). 
  Développez un outil sécurisé de relecture des événements, protégé par un 
  mécanisme d'idempotence.

## Exemples d'implémentation {% #implementation-examples %}

**Achat réussi — objet obtenu dès la première tentative :**

![Achat](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/purchase-v2.svg)

**Livraison en double (timeout du partenaire lors de la première tentative) :**

![Timeout](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/timeout-v2.svg)

**Remboursement :**

![Remboursement](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/refund-v2.svg)

**Interruption de service chez un partenaire** :

![Interruption de service chez un 
partenaire](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/server-error.svg)

# FAQ {% #faqs %}

## Ai-je besoin d'utiliser HTTPS pour un protocole de webhook ? {% #do-i-need-to-use-https-for-a-webhook-protocol %}

Oui.

## Puis-je recevoir des webhooks de paiement sur plusieurs URL ? {% #can-i-receive-payment-webhooks-at-several-urls %}

Non. Les webhooks de paiement utilisent un protocole serveur à serveur et sont 
envoyés à une URL unique définie dans les [paramètres du 
projet](/fr/webhooks/section/set-up-webhooks-in-publisher-account). Si vous 
souhaitez recevoir des notifications dans votre jeu, site web ou application 
mobile, configurez les webhooks sur votre serveur pour assurer l'échange de 
données entre Xsolla et votre application. Vous pouvez également les tester 
depuis la console développeur.

<div class="note">
<p><strong>Note</strong></p>
<p>Si vous testez l'intégration localement, les requêtes `POST` de Xsolla n'atteignent pas des URLs comme <code>http://localhost:3000/my-webhook-endpoint</code>. Utilisez des services tels que <a href="https://ngrok.com/">Ngrok</a> pour créer un tunnel d'accès externe et recevoir les requêtes Xsolla localement. Vous pouvez en savoir plus dans la <a href="https://ngrok.com/docs/guides/share-localhost/webhooks#test-webhooks-locally">documentation Ngrok</a>.</p>
</div>

## Pourquoi la notification Xsolla n'a-t-elle pas été envoyée à l'URL du webhook ? {% #why-was-xsolla-notification-not-sent-to-the-webhook-url %}

Assurez-vous que votre serveur de webhooks prend en charge les types de 
requêtes HTTP `POST` et `GET`.

## Comment éviter les doublons d'identifiants de transaction lors du traitement ? {% #how-do-i-prevent-duplicate-transaction-ids-during-processing %}

Utilisez l'ID externe : il s'agit de l'identifiant de transaction dans votre 
jeu, attribué à la commande dans votre système. Côté Xsolla, l'ID externe est 
associé à l'ID de transaction, ce qui permet d'éviter les paiements en double 
pour une même transaction. Pour en savoir plus sur la configuration, consultez 
notre [documentation](/fr/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id).

## Existe-t-il de bonnes pratiques pour l'utilisation des webhooks ? {% #are-there-any-best-practices-for-working-with-webhooks %}

Nous vous recommandons :

* Retourner le code `204` ou `200` immédiatement après la vérification de la 
  signature.
* Vérifier la signature du webhook par rapport au corps brut de la requête, sans 
  modification.
* Implémenter l'idempotence pour toutes les opérations.
* Enregistrer tous les événements et configurer un système de surveillance des 
  erreurs.
* Éviter d'inclure des données sensibles dans les URL et de divulguer des détails 
  techniques dans les messages d'erreur.

Consultez la section [Meilleures pratiques](/fr/webhooks/section/best-practices) 
pour plus d'informations.

# Liste de contrôle pour l'intégration des webhooks {% #webhook-integration-checklist %}

Pour que le bon fonctionnement des webhooks, assurez-vous que les éléments 
suivants sont bien en place avant de passer en production :

* Le protocole HTTPS est utilisé.
* La [vérification de la signature](/fr/webhooks/section/webhook-listener/generation-of-signature) du webhook s'effectue à partir du corps brut de la requête, sans 
  aucune modification.
* Une réponse `204/200` est renvoyée dès que la signature est confirmée.
* L'idempotence est assurée pour toutes les opérations.
* La journalisation et la surveillance des erreurs sont configurées.
* Les données sensibles ne sont pas transmises dans les URL, et les messages 
  d'erreur ne divulguent aucun détail technique.
* Les tentatives de réenvoi des webhooks sont prises en charge conformément à la 
  [logique de réessai de Xsolla](/fr/webhooks/section/webhook-listener/sending-responses-to-webhook).
* L'ensemble du processus d'intégration est documenté.

# Liste des webhooks {% #webhooks-list %}

<div class="note">
<p><strong>Note</strong></p>
<p>Le type de notification est passé dans le paramètre <code>notification_type</code>.</p>
</div>

<table>
<thead>
    <tr>
        <th>Webhook</th>
        <th>Type de notification</th>
        <th>Description</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><a href="/webhooks/operation/user-validation/">Validation utilisateur</a></td>
        <td><code>user_validation</code></td>
        <td>Envoyé pour vérifier si l'utilisateur existe dans le jeu.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/user-search/">Recherche utilisateur</a></td>
        <td><code>user_search</code></td>
        <td>Envoyé pour récupérer les informations sur l'utilisateur à partir de son ID utilisateur public.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/payment/">Paiement</a></td>
        <td><code>payment</code></td>
        <td>Envoyé lorsque l'utilisateur effectue un paiement.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/refund/">Remboursement</a></td>
        <td><code>refund</code></td>
        <td>Envoyé lorsqu'un paiement doit être annulé pour une raison quelconque.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/partial-refund/">Remboursement partiel</a></td>
        <td><code>partial_refund</code></td>
        <td>Envoyé lorsqu'un paiement doit être partiellement annulé pour une raison quelconque.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/payment-declined/">Paiement refusé</a></td>
        <td><code>ps_declined</code></td>
        <td>Envoyé lorsqu'un paiement est refusé par le système de paiement.</td>
    </tr>
    <tr>
        <td><a href="https://developers.xsolla.com/fr/webhooks/operation/afs-rejected-transaction/">Transaction rejetée par AFS</a></td>
        <td><code>afs_reject</code></td>
        <td>Envoyé lorsqu'une transaction est refusée lors d'un contrôle AFS.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/afs-rejected-blocklist/">Mise à jour de la liste noire AFS</a></td>
      <td><code>afs_black_list</code></td>
      <td>Envoyé lorsque la liste noire AFS est mise à jour.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/created-subscription/">Abonnement créé</a></td>
      <td><code>create_subscription</code></td>
      <td>Envoyé lorsque l'utilisateur crée un abonnement.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/updated-subscription/">Abonnement mis à jour</a></td>
      <td><code>update_subscription</code></td>
      <td>Envoyé lors du renouvellement ou de la modification d'un abonnement.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/canceled-subscription/">Abonnement annulé</a></td>
      <td><code>cancel_subscription</code></td>
      <td>Envoyé lorsqu'un abonnement est annulé.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/nonrenewing-subscription/">Abonnement non renouvelable</a></td>
      <td><code>non_renewal_subscription</code></td>
      <td>Envoyé lorsque le statut est défini sur non renouvelable.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/add-payment-account/">Ajout de compte de paiement</a></td>
      <td><code>payment_account_add</code></td>
      <td>Envoyé lorsque l'utilisateur ajoute ou enregistre un compte de paiement.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/remove-payment-account/">Suppression de compte de paiement</a></td>
      <td><code>payment_account_remove</code></td>
      <td>Envoyé lorsque l'utilisateur supprime un compte de paiement des comptes enregistrés.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/user-validation-in-webshop">Validation utilisateur dans Web Shop</a></td>
      <td><code>-</code></td>
      <td>Envoyé depuis le site d'un Web Shop pour vérifier si l'utilisateur existe dans le jeu.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/personalized-partner-catalog">Personnalisation du catalogue côté partenaire</a></td>
      <td><code>partner_side_catalog</code></td>
      <td>Envoyé lorsque l'utilisateur interagit avec le magasin.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/successful-order-payment">Paiement de commande réussi</a></td>
      <td><code>order_paid</code></td>
      <td>Envoyé lorsqu'une commande est payée.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/order-cancellation">Annulation de commande</a></td>
      <td><code>order_canceled</code></td>
      <td>Envoyé lorsqu'une commande est annulée.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/fr/webhooks/operation/dispute">Contestation</a></td>
      <td><code>dispute</code></td>
      <td>Envoyé lorsqu'une nouvelle contestation est ouverte.</td>
    </tr>
</tbody>
</table>


Version: 1.0

## Servers

```
https://api.xsolla.com/merchant/v2
```

## Download OpenAPI description

[Webhooks](https://xsolla.redocly.app/_bundle/@l10n/fr/webhooks/index.yaml)

## Validation utilisateur

### Recherche d'utilisateur

 - [POST user-search](https://xsolla.redocly.app/fr/webhooks/user-validation/user-search.md): Public User ID est un paramètre qui identifie l'utilisateur de manière unique et qui lui est connu, contrairement à User ID(Public User ID peut être une adresse e-mail, un pseudo, etc.). Xsolla envoie un webhook de type user_search lorsqu'un achat est effectué en dehors du magasin de jeu (par exemple, via des kiosques de paiement).

### Validation utilisateur

 - [POST user-validation](https://xsolla.redocly.app/fr/webhooks/user-validation/user-validation.md): Xsolla envoie un webhook de type user_validation à l'URL du webhook pour 
vérifier que l'utilisateur est enregistré dans le jeu. La requête est envoyée 
plusieurs fois pendant le processus de paiement :

* lorsque l'utilisateur choisit un mode de paiement dans l'interface de paiement ;
* lorsque l'utilisateur saisit des données dans le formulaire de paiement, par 
  exemple les données de sa carte bancaire ou le code postal lors d'un paiement 
  via PayPal ;
* lorsque l'utilisateur clique sur Pay now pour procéder au paiement ;
* lorsque le processus de paiement est terminé et que le statut de la transaction 
  passe à done.

La requête est envoyée lors d'un paiement via n'importe quel mode de paiement.

Lorsque vous enregistrez l'URL du webhook dans le Compte éditeur, vous pouvez 
activer les autorisations pour recevoir des informations détaillées dans les 
webhooks. Pour ce faire, activez les bascules correspondantes dans la section 
Project 
settings &gt; Webhooks &gt; Advanced settings.


Note
Si vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Bascule
        Description
    


    
        Envoyer paramètres utilisateur nécessaires seulement sans données sensibles
        Seules les informations suivantes sur l'utilisateur sont passées dans le webhook :ID ;pays.
    
    
        Envoyer paramètres personnalisés
        Les informations relatives aux paramètres du jeton personnalisé sont passées dans le webhook.

### Validation utilisateur dans Web Shop

 - [POST user-validation-in-webshop](https://xsolla.redocly.app/fr/webhooks/user-validation/user-validation-in-webshop.md): Xsolla envoie un webhook depuis le site d'un Web Shop pour vérifier si l'utilisateur existe dans le jeu. Le webhook est envoyé depuis l'adresse IP suivante : 34.102.38.178.
Note
Le webhook est utilisé uniquement pour la validation utilisateur dans Web Shop. Reportez-vous aux instructions  pour plus d'informations sur la configuration de ce webhook dans Site Builder.

## Payments

### Ajout de compte de paiement

 - [POST add-payment-account](https://xsolla.redocly.app/fr/webhooks/payments/add-payment-account.md): Xsolla envoie un webhook de type payment_account_add à l'URL du webhook chaque fois que l'utilisateur ajoute un compte de paiement ou enregistre un compte de paiement lors d'un achat dans le jeu. Pour recevoir ce webhook, contactez votre responsable de réussite client ou envoyez un e-mail à csm@xsolla.com.

### Remboursement partiel

 - [POST partial-refund](https://xsolla.redocly.app/fr/webhooks/payments/partial-refund.md): Lorsqu'un remboursement partiel est effectué, Xsolla envoie les détails de la 
transaction annulée via un webhook de type partial_refund à l'URL du webhook. 
Pour en savoir plus sur le processus de remboursement partiel, consultez ces 
instructions.

Lorsque vous enregistrez l'URL du webhook dans le Compte éditeur, vous pouvez 
activer les autorisations pour recevoir des informations détaillées dans les 
webhooks. Pour ce faire, activez la bascule correspondante dans la section Project 
settings &gt; Webhooks &gt; Advanced settings.


Note
Si vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Bascule
        Description
    


    
        Afficher infos sur transactions effectuées via modes de paiement enregistrés
        Les informations sont passées dans les paramètres personnalisés suivants du webhook :saved_payment_method:0 — le mode de paiement enregistré n'a pas été utilisé ;1 — le mode de paiement a été enregistré lors du paiement en cours ;2 — le mode de paiement précédemment enregistré est utilisé.payment_type:1 — paiement unique ;2 — paiement récurrent.
    



Codes de remboursement :


    
    
        Code
        Motif
        Description
    
    
    
    
        1
        Cancellation by the user request / the game request
        Annulation initiée dans le Compte éditeur.
    
    
        3
        Integration error
        Problèmes d'intégration entre Xsolla et le jeu.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        5
        Test payment
        Transaction test suivie d'une annulation.Recommandation : n'ajoutez pas l'utilisateur à la liste de noire.
    
    
        7
        Fraud notification from PS
        Paiement refusé : le système de paiement a détecté une fraude potentielle. Recommandation : bloquez cet utilisateur.
    
    
        9
        Cancellation by the user request
        Utilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        10
        Cancellation by the game request
        Annulation demandée par le jeu.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.

### Paiement

 - [POST payment](https://xsolla.redocly.app/fr/webhooks/payments/payment.md): Lorsque l'utilisateur effectue un paiement, Xsolla envoie les informations sur 
le paiement via un webhook de type payment à l'URL du webhook.

Les codes de réponse attendus sont décrits dans la section Responses, 
mais vous pouvez également utiliser d’autres codes de réponse :


    
    
        Code de réponse
        Description
    
    
    
    
        200, 201, 204
        Réponse de réussite.
    
    
        4xx
        Une erreur s'est produite. Par exemple, si l'utilisateur spécifié est introuvable ou si une signature non valide a été passée.
    
    
        5xx
        Erreur serveur temporaire. Lorsque cette réponse est reçue, Xsolla réessaie automatiquement d’envoyer le webhook, en espaçant progressivement les tentatives jusqu’à ce que votre écouteur confirme la réception. Le nombre maximal de tentatives est de 12 sur une période de 48 heures.
    
    


Lorsque vous enregistrez l'URL du webhook dans le Compte 
éditeur, vous pouvez également configurer la réception d'informations 
supplémentaires dans les webhooks.


Note
Si vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans le projet, sous la section Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Bascule
        Description
    


    
        Afficher infos sur le compte de paiement enregistré
        Les informations relatives au mode de paiement enregistré sont passées à l'objet personnalisé payment_account.
    
    
        Afficher infos sur transactions effectuées via modes de paiement enregistrés
        Les informations sont passées dans les paramètres personnalisés suivants du webhook :saved_payment_method:0 — le mode de paiement enregistré n'a pas été utilisé ;1 — le mode de paiement a été enregistré lors du paiement en cours ;2 — le mode de paiement précédemment enregistré est utilisé.payment_type:1 — paiement unique ;2 — paiement récurrent.
    
    
        Ajouter l'objet de la commande au webhook
        Les informations relatives à la commande sont passées dans l'objet order du webhook Paiement.
    
    
        Envoyer paramètres utilisateur nécessaires seulement sans données sensibles
        Seules les informations suivantes sur l'utilisateur sont passées dans le webhook :ID ;pays.
    
    
        Afficher BIN et suffixe de carte
        Les informations suivantes sur le numéro de la carte bancaire sont passées dans le webhook :les 6 premiers chiffres du paramètre card_bin ;les 4 derniers chiffres du card_suffix.
    
    
        Afficher marque de carte
        La marque de la carte utilisée pour effectuer le paiement. Par exemple, Mastercard ou Visa.
    
    
        Afficher les frais de retenue à la source par pays et les frais d'acquisition utilisateur.
        Les objets payment_details.​country_wht et payment_details.​user_acquisition_fee seront passés dans le webhook. Cette option est activée par défaut.
    
    
        Envoyer les informations 3DS.
        L'objet cards contenant des données sur la vérification 3-D Secure sera passé dans le webhook.
    




Remarque
L'ensemble des champs envoyés dans un webhook dépend :des paramètres avancés configurés dans le Compte éditeur ;des paramètres personnalisés configurés côté Xsolla.Si vous avez des questions, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

### Paiement refusé

 - [POST payment-declined](https://xsolla.redocly.app/fr/webhooks/payments/payment-declined.md): Si une transaction est refusée par un système de paiement, Xsolla envoie les 
informations de la transaction via un webhook de type ps_declined à l'URL de 
webhook que vous avez configurée. Ce webhook est déclenché lors de l'étape 
d'autorisation ou de traitement du paiement. Dans ce cas, le webhook de 
paiement\ order_paid n'est pas envoyé. 

Raisons typiques de refus par le système de paiement :

* L'autorisation de la carte a échoué (par exemple, le système de paiement n'a 
  pas pu finaliser l'opération en raison d'une erreur technique ou d'une absence 
  de réponse de la banque) ou a été refusée (par exemple, la banque a répondu, 
  mais a rejeté la transaction pour fonds insuffisants ou coordonnées de carte 
  non valides).
* La vérification 3-D Secure a échoué, n'a pas été finalisée ou la confirmation 
  de l'utilisateur est expirée.  
* Le processeur ou la banque acquéreuse est temporairement indisponible ou 
  renvoie un refus définitif en raison d'une erreur irréversible, comme un compte 
  fermé ou un numéro de carte non valide. Tenter de réexécuter la transaction 
  sans corriger le problème sous-jacent ne donnera pas de résultat positif.

À ne pas confondre avec :

* Les rejets Anti-Fraud, qui sont signalés via le webhook 
  afs_reject.
* Les remboursements et remboursements partiels après un paiement réussi, qui 
  sont signalés via les webhooks 
  refund et 
  partial_refund.


Note
Pour recevoir le webhook ps_declined, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

### Remboursement

 - [POST refund](https://xsolla.redocly.app/fr/webhooks/payments/refund.md): Lorsqu'un paiement est annulé, Xsolla envoie les informations de la transaction 
annulée dans un webhook de type refund à l'URL du webhook.

Le mécanisme de réessai du webhook dépend de la personne qui a initié le 
remboursement :
* Si vous initiez le remboursement de votre côté, aucun webhook n'est envoyé. Le 
  paiement est remboursé à l'utilisateur indépendamment de la réponse au webhook.
* Si une tierce partie initie le remboursement, par exemple un système de 
  paiement ou l'équipe d'assistance Xsolla, et qu'un code d'état 5xx est 
  renvoyé en réponse au webhook, Xsolla renvoie ce webhook à des intervalles 
  croissants. Le nombre maximal de tentatives est de 12 dans les 48 heures 
  suivant la première tentative.

Pour obtenir des informations détaillées sur la procédure de remboursement, 
référez-vous aux instructions instructions.


Remarque
Le paiement sera quand même remboursé à l'utilisateur si toutes les conditions suivantes sont réunies :Xsolla a initié le remboursement.En réponse au webhook, un code d'état 4xx est renvoyé, ou aucune réponse n'est reçue après toutes les tentatives, ou un code d'état 5xx est renvoyé.


Lorsque vous enregistrez l'URL du webhook dans le Compte 
éditeur, vous pouvez également configurer la réception d'informations 
supplémentaires dans les webhooks.


Note
Si vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans le projet, sous la section Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Bascule
        Description
    


    
        Afficher infos sur transactions effectuées via modes de paiement enregistrés
        Les informations sont passées dans les paramètres personnalisés suivants du webhook :saved_payment_method:0 — le mode de paiement enregistré n'a pas été utilisé ;1 — le mode de paiement a été enregistré lors du paiement en cours ;2 — le mode de paiement précédemment enregistré est utilisé.payment_type:1 — paiement unique ;2 — paiement récurrent.
    
    
        Afficher des informations sur le motif du remboursement.
        Informations détaillées sur les motifs de remboursement.
    



Codes de remboursement :


    
    
        Code
        Motif
        Description
    
    
    
    
        1
        Cancellation by the user request / the game request
        Annulation initiée dans le Compte éditeur.
    
    
        2
        Chargeback
        Chargeback pour une transaction demandé.
    
    
        3
        Integration error
        Problèmes d'intégration entre Xsolla et le jeu.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        4
        Potential fraud – AFS reject
        Transaction refusée : le système antifraude Xsolla a détecté une fraude potentielle.
    
    
        5
        Test payment
        Transaction test suivie d'une annulation.Recommandation : n'ajoutez pas l'utilisateur à la liste de noire.
    
    
        6
        User invoice expired
        Facture en retard (utilisée pour le modèle de paiement différé).
    
    
        7
        Fraud notification from PS
        Paiement refusé : le système de paiement a détecté une fraude potentielle. Recommandation : bloquez cet utilisateur.
    
    
        8
        Cancellation by the PS request
        Annulation demandée par le système de paiement.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        9
        Cancellation by the user request
        Utilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        10
        Cancellation by the game request
        Annulation demandée par le jeu.Recommandation : n'ajoutez pas l'utilisateur à la liste noire.
    
    
        11
        Account holder called to report fraud
        Le titulaire du compte affirme ne pas avoir effectué cette transaction. Recommandation : bloquez cet utilisateur.
    
    
        12
        Potential fraud – friendly fraud
        Le titulaire légitime de la carte a contesté cette transaction.
    
    
        13
        Duplicate
        Transaction dupliquée pour la même facture.
    
    
        21
        Potential fraud – BIN attack
        Cartes volées provenant d'un ou plusieurs BIN dans un même lot. Un afflux soudain de tentatives partageant une plage de BIN sur une courte période, souvent avec des numéros de carte énumérés, est un indicateur clé.
    
    
        22
        Potential fraud – monetization fraud
        Carte volée utilisée pour acheter des objets échangeables destinés à la revente.
    
    
        23
        Potential fraud – low-scale card fraud
        Cartes volées provenant d'un ou plusieurs BIN. Attaque moins répandue et coordonnée que l'attaque par BIN (code de remboursement 21).
    
    
        24
        Potential fraud – regional price abuse
        Abus de la tarification régionale ou revente de clés. Des utilisateurs ont contourné les prix régionaux en falsifiant leur localisation ou leur mode de paiement afin d'acheter à bas prix et de revendre les objets sur des marchés plus chers.
    
    
        25
        Potential fraud – partner or PS exploit
        Vol d'identifiants et prise de contrôle de compte : compromission d'un compte ou d'une intégration côté partenaire ou système de paiement, plutôt qu'une utilisation frauduleuse directe de cartes.
    
    
        26
        Potential fraud – not definable
        Fraude confirmée, mais le type d'attaque ne peut pas être déterminé avec certitude.
    
    
        27
        Fraud notification from PS – linked transactions
        La transaction n'a pas été signalée comme frauduleuse par le système de paiement, mais elle est liée, par une carte ou un appareil commun, à des transactions ayant fait l'objet d'un remboursement pour fraude.

### Suppression de compte de paiement

 - [POST remove-payment-account](https://xsolla.redocly.app/fr/webhooks/payments/remove-payment-account.md): Lorsque l'utilisateur supprime un compte de paiement des comptes enregistrés, Xsolla envoie un webhook de type payment_account_remove à l'URL du webhook. Pour recevoir ce webhook, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

## Webhooks combinés

### Annulation de commande (avec données de paiement et de transaction)

 - [POST order-cancellation](https://xsolla.redocly.app/fr/webhooks/combined-webhooks/order-cancellation.md): Xsolla envoie le webhook order_canceled à l'URL spécifiée lorsque 
le paiement est annulé par l'utilisateur, le partenaire ou automatiquement. Le 
webhook inclut des informations sur les objets retournés, le paiement et la 
commande annulée.

Le webhook n'est pas envoyé si le paiement n'a pas abouti, par exemple :
* l'interface de paiement a été ouverte, mais l'utilisateur n'a pas procédé au 
  paiement de la commande ;
* l'interface de paiement a été ouverte, mais des erreurs se sont produites lors 
  du paiement.

Le temps de traitement recommandé pour le webhook est de 3 secondes.

### Paiement de commande réussi (avec données de paiement et de transaction)

 - [POST successful-order-payment](https://xsolla.redocly.app/fr/webhooks/combined-webhooks/successful-order-payment.md): Xsolla envoie le webhook order_paid à l'URL spécifiée lorsque 
l'utilisateur effectue le paiement de la commande avec succès.

Le webhook order_paid contient des informations sur les objets 
achetés, les données du paiement et les détails de la transaction.

Le webhook order_paid n'est pas envoyé si le paiement n'aboutit 
pas, par exemple :
* le formulaire de paiement a été ouvert, mais l'utilisateur n'a pas procédé au 
  paiement de la commande ;
* le formulaire de paiement a été ouvert, mais des erreurs se sont produites lors 
  du paiement.

Il est recommandé de veiller à ce que la temps de traitement du webhook 
order_paid soit inférieur à 3 secondes.


Remarque
L'ensemble des champs envoyés dans un webhook dépend : des paramètres configurés dans le Compte éditeur dans la section Project settings &gt; Webhooks &gt; Advanced settings ;des paramètres configurés côté Xsolla.Si vous avez des questions, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.


Les réponses attendues sont décrites dans la section Réponses. Vous 
pouvez utiliser d'autres codes de réponse. En fonction du code de réponse et de 
la connexion à la fonctionnalité de remboursement automatique de paiement, la 
logique de traitement du webhook côté Xsolla est la suivante :


    
    
        Code de réponse
        Remboursement automatique de paiement désactivé (par défaut)
        Remboursement automatique de paiement activé
    
    
    
    
        400, 401, 402, 403, 404, 409, 422, 415
        Aucune action
        Remboursement automatique à l'utilisateur
    
    
        200, 201, 204
        Aucune action
        Aucune action
    
    
        Code différent ou absence de réponse au webhook
        Plusieurs webhooks sont envoyés à des intervalles de temps spécifiques : 2 tentatives à intervalles de 5 minutes, 7 tentatives à intervalles de 15 minutes, 10 tentatives à intervalles de 60 minutes.
        Plusieurs webhooks sont envoyés à des intervalles de temps spécifiques : 2 tentatives à intervalles de 5 minutes, 7 tentatives à intervalles de 15 minutes, 10 tentatives à intervalle de 60 minutes. Si tous les webhooks sont envoyés mais qu'aucune réponse n'est reçue, l'utilisateur est automatiquement remboursé.
    
    


Pour connecter la fonctionnalité de remboursement automatique, contactez vos 
responsables de réussite client ou envoyez un e-mail à csm@xsolla.com.

## Webhooks distincts

### Annulation de commande (sans données de paiement et de transaction)

 - [POST order-cancellation-separate](https://xsolla.redocly.app/fr/webhooks/separate-webhooks/order-cancellation-separate.md): Xsolla envoie le webhook order_canceled à l'URL spécifiée lorsque 
le paiement est annulé par l'utilisateur, le partenaire ou automatiquement. Le 
webhook inclut des informations sur les objets retournés et la commande annulée.

Le webhook n'est pas envoyé si le paiement n'a pas abouti, par exemple :
* l'interface de paiement a été ouverte, mais l'utilisateur n'a pas procédé au 
  paiement de la commande ;
* l'interface de paiement a été ouverte, mais des erreurs se sont produites lors 
  du paiement.

Le temps de traitement recommandé pour le webhook est de 3 secondes.

### Paiement de commande réussi (sans données de paiement et de transaction)

 - [POST successful-order-payment-separate](https://xsolla.redocly.app/fr/webhooks/separate-webhooks/successful-order-payment-separate.md): Xsolla envoie le webhook order_paid à l'URL spécifiée lorsque les 
conditions suivantes sont remplies :
1. L'utilisateur a procédé au paiement de la commande avec succès.
2. Xsolla a reçu une réponse de traitement réussi du webhook 
   Paiement.

Le webhook order_paid contient des informations sur les objets 
achetés et les détails de la transaction.

Le webhook order_paid n'est pas envoyé si :
* Le paiement n'a pas été effectué, par exemple :
  * le formulaire de paiement a été ouvert, mais l'utilisateur n'a pas procédé au 
    paiement de la commande ;
  * le formulaire de paiement a été ouvert, mais des erreurs se sont produites lors 
    du paiement.
* Aucune réponse de traitement réussi du webhook 
  Paiement n'a été reçue.

Il est recommandé de veiller à ce que la temps de traitement du webhook 
order_paid soit inférieur à 3 secondes.

Les réponses attendues sont décrites dans la section Réponses. Vous 
pouvez utiliser d'autres codes de réponse. En fonction du code de réponse et de 
la connexion à la fonctionnalité de remboursement automatique de paiement, la 
logique de traitement du webhook côté Xsolla est la suivante :


    
    
        Code de réponse
        Remboursement automatique de paiement désactivé (par défaut)
        Remboursement automatique de paiement activé
    
    
    
    
        400, 401, 402, 403, 404, 409, 422, 415
        Aucune action
        Remboursement automatique à l'utilisateur
    
    
        200, 201, 204
        Aucune action
        Aucune action
    
    
        Code différent ou absence de réponse au webhook
        Plusieurs webhooks sont envoyés à des intervalles de temps spécifiques : 2 tentatives à intervalles de 5 minutes, 7 tentatives à intervalles de 15 minutes, 10 tentatives à intervalles de 60 minutes.
        Plusieurs webhooks sont envoyés à des intervalles de temps spécifiques : 2 tentatives à intervalles de 5 minutes, 7 tentatives à intervalles de 15 minutes, 10 tentatives à intervalle de 60 minutes. Si tous les webhooks sont envoyés mais qu'aucune réponse n'est reçue, l'utilisateur est automatiquement remboursé.
    
    


Pour connecter la fonctionnalité de remboursement automatique, contactez vos 
responsables de réussite client ou envoyez un e-mail à csm@xsolla.com.

## Webhook de personnalisation

### Personnalisation du catalogue côté partenaire

 - [POST personalized-partner-catalog](https://xsolla.redocly.app/fr/webhooks/personalization/personalized-partner-catalog.md): Xsolla enverra à l'URL du webhook un webhook partner_side_catalog 
contenant les paramètres de l'utilisateur et du projet chaque fois que 
l'utilisateur interagit avec le magasin.

En réponse, renvoyez la liste des item_id ou des UGS des biens 
disponibles pour l'utilisateur. Vous pouvez également inclure des informations 
sur la possibilité pour un utilisateur spécifique d'acheter certains biens un 
certain nombre de fois. Cette fonctionnalité vous permet de contrôler le nombre 
et le type de biens que l'utilisateur peut ajouter au panier et acheter.


Avis
Lors du traitement du webhook, tenez compte des limitations suivantes :Le webhook doit être traité en moins de 3 secondes. Si le traitement prend plus de temps, les appels API récupérer la liste des objets virtuels, créer un jeton de paiement, et créer une commande renvoient une erreur.La taille de la réponse au webhook ne doit pas dépasser 64 Ko. Les réponses dépassant cette limite ne sont pas traitées : l'utilisateur voit un catalogue vide et ne peut pas acheter d'objets. Pour modifier la taille maximale de la réponse, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

## Anti-Fraud

### Mettre à jour la liste de blocage Anti-fraud

 - [POST afs-rejected-blocklist](https://xsolla.redocly.app/fr/webhooks/anti-fraud/afs-rejected-blocklist.md): Lorsque la liste de blocage du système Anti-fraud est mise à jour (ajout ou suppression d'un paramètre), Xsolla envoie un webhook de type afs_black_list à l'URL du webhook. L'ajout d'un paramètre est effectué automatiquement côté Xsolla ou sur demande. La suppression d'un paramètre n'est possible que sur demande. Pour recevoir ce webhook, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

### Transaction rejetée par le système Anti-fraud

 - [POST afs-rejected-transaction](https://xsolla.redocly.app/fr/webhooks/anti-fraud/afs-rejected-transaction.md): Lorsqu'une transaction est refusée pendant un contrôle du système Anti-fraud, 
Xsolla envoie les détails de la transaction via un webhook de type afs_reject 
à l'URL du webhook. Pour recevoir ce webhook, contactez votre responsable de la 
réussite client ou envoyez un e-mail à csm@xsolla.com.

Lorsque vous enregistrez l'URL du webhook dans le Compte éditeur, vous pouvez 
activer les autorisations pour recevoir des informations détaillées dans les 
webhooks. Pour ce faire, activez la bascule correspondante dans la section Project 
settings &gt; Webhooks &gt; Advanced settings.


Note
Si vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Bascule
        Description
    


    
        Afficher infos sur transactions effectuées via modes de paiement enregistrés
        Les informations sont passées dans les paramètres personnalisés suivants du webhook :saved_payment_method:0 — le mode de paiement enregistré n'a pas été utilisé ;1 — le mode de paiement a été enregistré lors du paiement en cours ;2 — le mode de paiement précédemment enregistré est utilisé.payment_type:1 — paiement unique ;2 — paiement récurrent.

### Contestation

 - [POST dispute](https://xsolla.redocly.app/fr/webhooks/anti-fraud/dispute.md): Lorsqu'une nouvelle contestation est ouverte ou lorsqu'une contestation change de statut, Xsolla envoie un webhook contenant le type de dispute à l'URL du webhook. Pour recevoir ce webhook, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

## Subscriptions

### Abonnement annulé

 - [POST canceled-subscription](https://xsolla.redocly.app/fr/webhooks/subscriptions/canceled-subscription.md): Lorsqu'un abonnement est annulé, Xsolla envoie un webhook de type cancel_subscription à l'URL du webhook.

### Abonnement créé

 - [POST created-subscription](https://xsolla.redocly.app/fr/webhooks/subscriptions/created-subscription.md): Lorsque l'utilisateur crée un abonnement, Xsolla envoie un webhook de type create_subscription à l'URL du webhook.

### Abonnement non renouvelable

 - [POST nonrenewing-subscription](https://xsolla.redocly.app/fr/webhooks/subscriptions/nonrenewing-subscription.md): Lorsqu'un statut d'abonnement est défini sur Non renouvelable, Xsolla envoie un webhook de type non_renewal_subscription à l'URL du webhook. Pour recevoir ce webhook, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.

### Abonnement mis à jour

 - [POST updated-subscription](https://xsolla.redocly.app/fr/webhooks/subscriptions/updated-subscription.md): En cas de modification de certains paramètres de l'abonnement (plan_id, date_next_charge) et à chaque renouvellement d'abonnement, Xsolla envoie un webhook de type update_subscription à l'URL du webhook.