Note
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.
\n| Produit/Solution | \nObligatoire/Facultatif | \nÀ quoi servent les webhooks ? | \n
|---|---|---|
| Payments | \nObligatoire | \n\n
| \n
| Store | \nObligatoire | \n\n
| \n
| Game Sales | \nFacultatif | \nPour 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. Assurez-vous de traiter tous les webhooks entrants requis.\n | \n
| Subscriptions | \nFacultatif | \nRéception d'informations sur la création, la mise à jour ou l'annulation d'abonnements. Vous pouvez également demander des informations via API.\n | \n
| Web Shop | \nObligatoire | \n\n
| \n
| Digital Distribution Hub | \nObligatoire | \n\n
Reportez-vous à la documentation pour obtenir plus d'informations sur la configuration des webhooks pour Digital Distribution Hub. \n | \n
| Login | \nFacultatif | \n\n Réception d'informations sur les événements : \n
Reportez-vous à la documentation Login pour des informations détaillées sur la configuration des webhooks. \n | \n
| Nom et type du webhook | \nDescription | \n
|---|---|
Validation utilisateur > Validation utilisateur (user_validation) | \n Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu. | \n
Services de jeux > Webhooks combinés > Paiement de commande réussi (order_paid) | \n 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. | \n
Services de jeux > Webhooks combinés > Annulation de commande (order_canceled) | \n 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. | \n
| Nom et type du webhook | \nDescription | \n
|---|---|
Validation utilisateur > Validation utilisateur (user_validation) | \n Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu. | \n
Payments > Paiement (payment) | \n Il contient les données du paiement et de la transaction. | \n
Services de jeux > Webhooks distincts > Paiement de commande réussi (order_paid) | \n Il contient des informations sur les biens achetés. Utilisez les données du webhook pour octroyer les objets à l'utilisateur. | \n
Payments > Remboursement (refund ) | \n Il contient les données du paiement et de la transaction. | \n
Services de jeux > Webhooks distincts > Annulation de commande (order_canceled) | \n 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. | \n
Note
\nPour recevoir des paiements réels, vous devez simplement signer le contrat de licence et implémenter le traitement des webhooks :
\nAttention
\nLe protocole HTTPS est utilisé pour transférer les données ; le protocole HTTP n'est pas pris en charge.
\nImportant
\nRecommandations concernant la clé :
Note
\nPour tester les webhooks, sélectionnez n'importe quel site Web dédié, tel que webhook.site, ou une plateforme, telle que ngrok.
\nRemarque
\nIl 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.
\nImportant
\nRecommandations concernant la clé :
Note
\nSi 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 Testing > Payments and Store.
\n| Bascule | \nDescription | \n
|---|---|
| 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). | \nLes informations relatives au mode de paiement enregistré sont passées à l'objet personnalisé payment_account. | \n
| Afficher les informations relatives aux transactions effectuées via les modes de paiement enregistrés. | \nLes informations sont passées dans les paramètres personnalisés suivants du webhook :
| \n
Ajouter l'objet order 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). | \n Les informations relatives à la commande sont passées dans l'objet order du webhook Paiement. | \n
| Envoyer uniquement des paramètres utilisateur nécessaires sans données sensibles. | \nSeules les informations suivantes sur l'utilisateur sont passées dans le webhook :
| \n
| Envoyer des paramètres personnalisés | \nLes informations relatives aux paramètres du jeton personnalisé sont passées dans le webhook. | \n
| Afficher le BIN et le suffixe de la carte. | \nLes informations suivantes sur le numéro de la carte bancaire sont passées dans le webhook :
| \n
| Afficher marque de carte. | \nLa marque de la carte utilisée pour effectuer le paiement. Par exemple, Mastercard ou Visa. | \n
| Afficher des informations sur le motif du remboursement. | \nInformations détaillées sur les motifs de remboursement. | \n
| Afficher les frais de retenue à la source par pays et les frais d'acquisition utilisateur. | \nLes 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. | \n
| Envoyer les informations 3DS. | \nL'objet cards contenant des données sur la vérification 3-D Secure sera passé dans le webhook. | \n
| Nom de l'onglet pour le test du webhook | \nNom et type du webhook | \n
|---|---|
| Payments and store | \nValidation utilisateur > Validation utilisateur (user_validation) | \n
| \n | Services de jeux > Webhooks combinés > Paiement de commande réussi (order_paid) | \n
| \n | Services de jeux > Webhooks combinés > Annulation de commande (order_canceled) | \n
| Subscriptions | \nValidation utilisateur > Validation utilisateur (user_validation) | \n
| \n | Payments > Paiement (payment) | \n
| Nom de l'onglet pour le test du webhook | \nNom et type du webhook | \n
|---|---|
| Store | \nServices de jeux > Webhooks distincts > Paiement de commande réussi (order_paid) | \n
| \n | Services de jeux > Webhooks distincts > Annulation de commande (order_canceled) | \n
| Payments | \nValidation utilisateur > Validation utilisateur (user_validation) | \n
| \n | Payments > Paiement (payment) | \n
| Subscriptions | \nValidation utilisateur > Validation utilisateur (user_validation) | \n
| \n | Payments > Paiement (payment) | \n
Note
\nSi 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 écouteur webhook. Les raisons des erreurs dans les tests sont indiquées dans les résultats.
\nExemple :
\nVous utilisez le site spécialisé webhook.site pour effectuer des tests.
\nUne erreur s'affiche dans la section Testing response to invalid signature.
\nCela 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 4xx spécifiant le code d'erreur INVALID_SIGNATURE.
webhook.site renvoie un code HTTP 200 en réponse à tous les webhooks, y compris à ceux avec une signature incorrecte. Le code HTTP 4xx attendu ne pouvant pas être obtenu, une erreur apparaît dans le résultat du test.
Remarque
\nPour tester les webhooks, vous devez avoir au moins un plan d'abonnement créé dans le Compte éditeur dans la section Items catalog> Subscriptions.
\nRemarque
\nVous trouverez des informations détaillées sur le test d'autres scénarios de gestion des abonnements dans le guide d'intégration.
\nNote
\nVous pouvez utiliser la bibliothèque Pay Station PHP SDK, qui contient des classes prêtes à l'emploi, pour le traitement des webhooks.
\nRemarque
Utilisez la charge utile JSON \n exactement telle qu’elle est reçue. Ne la parsez ni ne la réencodez, car cela \n modifierait son formatage et entraînerait l’échec de la vérification de la \n signature.
Note
\nCe 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 ConstantTimeEquals pour une comparaison en temps constant, réduisant le risque d'attaques temporelles.
Note
\nLa méthode Convert.ToHexString nécessite .NET 5.0 ou ultérieure.
CryptographicOperations.FixedTimeEquals à la place de ConstantTimeEquals.\nNote
\nSi vous disposez de .NET 7.0 ou ultérieure, vous pouvez utiliser la méthode CryptographicOperations.FixedTimeEquals.
Remarque
\nLe paiement sera quand même remboursé à l'utilisateur si toutes les conditions suivantes sont réunies :
4xx est renvoyé, ou aucune réponse n'est reçue après toutes les tentatives, ou un code d'état 5xx est renvoyé.| Code | \nMessage | \n
|---|---|
| INVALID_USER | \nUtilisateur non valide | \n
| INVALID_PARAMETER | \nParamètre non valide | \n
| INVALID_SIGNATURE | \nSignature non valide | \n
| INCORRECT_AMOUNT | \nMontant incorrect | \n
| INCORRECT_INVOICE | \nFacture incorrecte | \n
Note
\nSi vous testez l'intégration localement, les requêtes `POST` de Xsolla n'atteignent pas des URLs comme http://localhost:3000/my-webhook-endpoint. Utilisez des services tels que Ngrok pour créer un tunnel d'accès externe et recevoir les requêtes Xsolla localement. Vous pouvez en savoir plus dans la documentation Ngrok.
Note
\nLe type de notification est passé dans le paramètre notification_type.
| Webhook | \nType de notification | \nDescription | \n
|---|---|---|
| Validation utilisateur | \nuser_validation | \n Envoyé pour vérifier si l'utilisateur existe dans le jeu. | \n
| Recherche utilisateur | \nuser_search | \n Envoyé pour récupérer les informations sur l'utilisateur à partir de son ID utilisateur public. | \n
| Paiement | \npayment | \n Envoyé lorsque l'utilisateur effectue un paiement. | \n
| Remboursement | \nrefund | \n Envoyé lorsqu'un paiement doit être annulé pour une raison quelconque. | \n
| Remboursement partiel | \npartial_refund | \n Envoyé lorsqu'un paiement doit être partiellement annulé pour une raison quelconque. | \n
| Paiement refusé | \nps_declined | \n Envoyé lorsqu'un paiement est refusé par le système de paiement. | \n
| Transaction rejetée par AFS | \nafs_reject | \n Envoyé lorsqu'une transaction est refusée lors d'un contrôle AFS. | \n
| Mise à jour de la liste noire AFS | \nafs_black_list | \n Envoyé lorsque la liste noire AFS est mise à jour. | \n
| Abonnement créé | \ncreate_subscription | \n Envoyé lorsque l'utilisateur crée un abonnement. | \n
| Abonnement mis à jour | \nupdate_subscription | \n Envoyé lors du renouvellement ou de la modification d'un abonnement. | \n
| Abonnement annulé | \ncancel_subscription | \n Envoyé lorsqu'un abonnement est annulé. | \n
| Abonnement non renouvelable | \nnon_renewal_subscription | \n Envoyé lorsque le statut est défini sur non renouvelable. | \n
| Ajout de compte de paiement | \npayment_account_add | \n Envoyé lorsque l'utilisateur ajoute ou enregistre un compte de paiement. | \n
| Suppression de compte de paiement | \npayment_account_remove | \n Envoyé lorsque l'utilisateur supprime un compte de paiement des comptes enregistrés. | \n
| Validation utilisateur dans Web Shop | \n- | \n Envoyé depuis le site d'un Web Shop pour vérifier si l'utilisateur existe dans le jeu. | \n
| Personnalisation du catalogue côté partenaire | \npartner_side_catalog | \n Envoyé lorsque l'utilisateur interagit avec le magasin. | \n
| Paiement de commande réussi | \norder_paid | \n Envoyé lorsqu'une commande est payée. | \n
| Annulation de commande | \norder_canceled | \n Envoyé lorsqu'une commande est annulée. | \n
| Contestation | \ndispute | \n Envoyé lorsqu'une nouvelle contestation est ouverte. | \n
Note
\nSi vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings > Webhooks > Testing > Payments > Advanced settings.
\n| Bascule | \nDescription | \n
|---|---|
| Afficher infos sur transactions effectuées via modes de paiement enregistrés | \nLes informations sont passées dans les paramètres personnalisés suivants du webhook :
| \n
| Initiateur du remboursement | \nValeur du champ | \n
|---|---|
| Jeu (via API). | \nAPI | \n
| Utilisateur du Compte éditeur (remboursement automatique). | \nAdresse e-mail de l'utilisateur | \n
| Utilisateur du Compte éditeur (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Xsolla (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Code | \nMotif | \nDescription | \n
|---|---|---|
| 1 | \nCancellation by the user request / the game request | \nAnnulation initiée dans le Compte éditeur. | \n
| 2 | \nChargeback | \nChargeback pour une transaction demandé. | \n
| 3 | \nIntegration error | \nProblèmes d'intégration entre Xsolla et le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 4 | \nPotential fraud | \nFraude soupçonnée. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 5 | \nTest payment | \nTransaction test suivie d'une annulation. Recommandation : n'ajoutez pas l'utilisateur à la liste de noire. | \n
| 6 | \nUser invoice expired | \nFacture en retard (utilisée pour le modèle de paiement différé). | \n
| 7 | \nFraud notification from PS | \nPaiement refusé par le système de paiement en raison d'une fraude potentielle. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 8 | \nCancellation by the PS request | \nAnnulation demandée par le système de paiement. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 9 | \nCancellation by the user request | \nUtilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 10 | \nCancellation by the game request | \nAnnulation demandée par le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 11 | \nAccount holder called to report fraud | \nLe titulaire de compte déclare qu'il n'a pas effectué la transaction. | \n
| 12 | \nFriendly fraud | \nFraude de type « Friendly fraud » signalée. | \n
| 13 | \nDuplicate | \nTransaction dupliquée pour la même facture. | \n
order_canceled à l'URL spécifiée lorsque \nle paiement est annulé par l'utilisateur, le partenaire ou automatiquement. Le \nwebhook inclut des informations sur les objets retournés, le paiement et la \ncommande annulée.\n\nLe webhook n'est pas envoyé si le paiement n'a pas abouti, par exemple :\n* l'interface de paiement a été ouverte, mais l'utilisateur n'a pas procédé au \n paiement de la commande ;\n* l'interface de paiement a été ouverte, mais des erreurs se sont produites lors \n du paiement.\n\nLe temps de traitement recommandé pour le webhook est de 3 secondes.\n",
"operationId": "order-cancellation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"billing": {
"description": "Données de la transaction et du paiement.",
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"payment_details": {
"description": "Informations sur le paiement (objet).",
"properties": {
"country_wht": {
"$ref": "#/components/schemas/country_whc"
},
"direct_wht": {
"description": "Retenue à la source directe.",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Taux de retenue à la source directe.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"payment": {
"description": "Montant payé par l'utilisateur (objet).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payment_method_fee": {
"description": "Frais du système de paiement.",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payment_method_sum": {
"description": "Montant débité du système de paiement.",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payout": {
"description": "Détails de virement (objet).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payout_currency_rate": {
"description": "Taux de change entre les devises de paiement et de virement.",
"type": "string"
},
"repatriation_commission": {
"description": "Données sur les frais de rapatriement imposés à Xsolla par des tiers.",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"sales_tax": {
"description": "Taxe de vente (objet ; États-Unis et Canada uniquement).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Taux de taxe de vente.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"user_acquisition_fee": {
"description": "Montant total de la commission d'acquisition d'utilisateurs déduits pour les achats effectués via les réseaux d'affiliation et les influenceurs (objet).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Taux de la commission d'acquisition de l'utilisateur, en %.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"vat": {
"description": "Informations sur la TVA (objet ; UE uniquement).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Taux de TVA.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"xsolla_balance_sum": {
"description": "Montant débité du solde Xsolla.",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"xsolla_fee": {
"description": "Frais Xsolla (objet).",
"properties": {
"amount": {
"description": "Montant.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
}
},
"type": "object"
},
"purchase": {
"description": "Informations sur l'achat (objet).",
"properties": {
"subscription": {
"description": "Informations de l'abonnement (objet).",
"properties": {
"amount": {
"$ref": "#/components/schemas/amount-float"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
}
},
"type": "object"
},
"total": {
"description": "Prix total d'achat (objet).",
"properties": {
"amount": {
"description": "Montant total du paiement.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
}
},
"required": [
"total"
],
"type": "object"
},
"refund_details": {
"description": "Détails du remboursement (objet).",
"properties": {
"author": {
"description": "Initiateur du remboursement. La valeur du champ est passée conformément au \ntableau :\n\n| Initiateur du remboursement | \nValeur du champ | \n
|---|---|
| Jeu (via API). | \nAPI | \n
| Utilisateur du Compte éditeur (remboursement automatique). | \nAdresse e-mail de l'utilisateur | \n
| Utilisateur du Compte éditeur (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Xsolla (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
order_canceled à l'URL spécifiée lorsque \nle paiement est annulé par l'utilisateur, le partenaire ou automatiquement. Le \nwebhook inclut des informations sur les objets retournés et la commande annulée.\n\nLe webhook n'est pas envoyé si le paiement n'a pas abouti, par exemple :\n* l'interface de paiement a été ouverte, mais l'utilisateur n'a pas procédé au \n paiement de la commande ;\n* l'interface de paiement a été ouverte, mais des erreurs se sont produites lors \n du paiement.\n\nLe temps de traitement recommandé pour le webhook est de 3 secondes.\n",
"operationId": "order-cancellation-separate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_parameters": {
"description": "Informations supplémentaires.",
"type": "object"
},
"items": {
"description": "Liste des objets achetés par l'utilisateur.\n\nL'ensemble des paramètres inclus dans le tableau dépend de la version du \nwebhook. La version 2 comprend des paramètres supplémentaires : `is_free`, \n`is_bonus` et `is_bundle_content`. Pour changer de version, passez son numéro \ndans le paramètre `version` de l'appel API [Update information about webhook \nsettings](/fr/api/igs/operation/update-webhook/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Coût total des objets en fonction de leur quantité.",
"type": "string"
},
"custom_attributes": {
"description": "Un JSON contenant les attributs des objets et leurs valeurs.",
"type": "object"
},
"is_pre_order": {
"description": "Si la valeur est `true`, l'objet est en précommande.",
"type": "boolean"
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"quantity": {
"description": "Quantité d'objets.",
"type": "integer"
},
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
}
},
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"title": "version = 1",
"type": "object"
},
{
"properties": {
"amount": {
"description": "Coût total des objets en fonction de leur quantité.",
"type": "string"
},
"custom_attributes": {
"description": "Un JSON contenant les attributs des objets et leurs valeurs.",
"type": "object"
},
"is_bonus": {
"description": "Si la valeur est `true`, l'objet est un bonus.",
"type": "boolean"
},
"is_bundle_content": {
"description": "Si la valeur est `true`, l'objet fait partie d'un lot.",
"type": "boolean"
},
"is_free": {
"description": "Si ce paramètre est défini sur `true`, l'objet est gratuit.",
"type": "boolean"
},
"is_pre_order": {
"description": "Si la valeur est `true`, l'objet est en précommande.",
"type": "boolean"
},
"promotions": {
"description": "Promotions appliquées. Si aucune promotion n'a été appliquée, un tableau vide est passé dans le paramètre.",
"items": {
"properties": {
"amount_with_discount": {
"description": "Coût total des objets bénéficiant d'une remise.",
"type": "string"
},
"amount_without_discount": {
"description": "Coût total des objets sans remise.",
"type": "string"
},
"sequence": {
"description": "Ordre d'application de promotions",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"quantity": {
"description": "Quantité d'objets.",
"type": "integer"
},
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
}
},
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"title": "version = 2",
"type": "object"
}
]
},
"type": "array"
},
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"order": {
"description": "Informations sur commande.",
"properties": {
"amount": {
"description": "Coût total du panier en fonction de la devise sélectionnée.",
"type": "string"
},
"comment": {
"description": "Commentaire de l'utilisateur sur la commande.",
"nullable": true,
"type": "string"
},
"coupons": {
"description": "Coupons appliqués. Si aucun coupon n'a été appliqué, le tableau n'est pas renvoyé.",
"items": {
"properties": {
"code": {
"description": "Code du coupon appliqué.",
"type": "string"
},
"external_id": {
"description": "External ID.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"currency": {
"description": "Devise de commande. L'UGS est utilisée pour la monnaie virtuelle et un code à trois lettres selon la norme [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) pour les devises réelles.",
"type": "string"
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"id": {
"description": "Identifiant unique de la commande de l'utilisateur côté Xsolla.",
"type": "integer"
},
"invoice_id": {
"description": "ID de facture pour les paiements en devises réelles. Les paiements en monnaie virtuelle ou les biens gratuits ont une valeur `null`.",
"nullable": true,
"type": "string"
},
"mode": {
"description": "Mode de paiement. La valeur `default` est utilisée pour les paiements réels et `sandbox` pour les paiements test.",
"enum": [
"default",
"sandbox"
],
"type": "string"
},
"platform": {
"description": "Plateforme de paiement. La valeur `xsolla` est utilisée pour les paiements via Xsolla. Pour les autres paiements, la valeur correspondant au nom de la plateforme de publication de jeux est utilisée : `playstation_network`, `xbox_live`, `pc_standalone`, `nintendo_shop`, `google_play`, `app_store_ios`, `android_standalone`, `ios_standalone`, `android_other`, `ios_other`, `pc_other`.",
"enum": [
"xsolla",
"playstation_network",
"xbox_live",
"pc_standalone",
"nintendo_shop",
"google_play",
"app_store_ios",
"android_standalone",
"ios_standalone",
"android_other",
"ios_other",
"pc_other"
],
"nullable": true,
"type": "string"
},
"promocodes": {
"description": "Codes promo appliqués. Si aucun code promo n'a été appliqué, le tableau n'est pas renvoyé.",
"items": {
"properties": {
"code": {
"description": "Code promo appliqué.",
"type": "string"
},
"external_id": {
"description": "External ID.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"status": {
"description": "Statut de la commande.",
"type": "string"
}
},
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"type": "object"
},
"user": {
"description": "Informations sur l'utilisateur.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"description": "Adresse e-mail de l'utilisateur.",
"type": "string"
},
"external_id": {
"description": "ID utilisateur.",
"type": "string"
}
},
"required": [
"external_id",
"email"
],
"type": "object"
}
},
"required": [
"notification_type",
"items",
"order",
"user"
]
}
}
}
},
"responses": {
"200": {
"description": "Renvoyez pour indiquer un traitement réussi."
},
"400": {
"description": "Renvoyez en cas d'erreur dans les informations fournies (par exemple, un paramètre requis manquant, une autorisation échouée, etc.)."
}
},
"summary": "Annulation de commande (sans données de paiement et de transaction)",
"tags": [
"separate-webhooks"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \\\n-d '{\n \"notification_type\": \"order_canceled\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.v.item_1\",\n \"type\": \"virtual_good\",\n \"is_pre_order\": false,\n \"quantity\": 3,\n \"amount\": \"1000\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"6000\",\n \"amount_with_discount\": \"5000\",\n \"sequence\": 1\n },\n {\n \"amount_without_discount\": \"5000\",\n \"amount_with_discount\": \"4000\",\n \"sequence\": 2\n }\n ],\n \"custom_attributes\": {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.v.item_new_1\",\n \"type\": \"bundle\",\n \"is_pre_order\": false,\n \"quantity\": 1,\n \"amount\": \"1000\",\n \"promotions\": []\n },\n {\n \"sku\": \"com.xsolla.gold_1\",\n \"type\": \"virtual_currency\",\n \"is_pre_order\": false,\n \"quantity\": 1500,\n \"amount\": \"[null]\",\n \"promotions\": []\n }\n ],\n \"order\": {\n \"id\": 1,\n \"mode\": \"default\",\n \"currency_type\": \"virtual\",\n \"currency\": \"sku_currency\",\n \"amount\": \"2000\",\n \"status\": \"paid\",\n \"platform\": \"xsolla\",\n \"comment\": null,\n \"invoice_id\": \"1\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"4000\",\n \"amount_with_discount\": \"2000\",\n \"sequence\": 1\n }\n ],\n \"promocodes\": [\n {\n \"code\": \"promocode_some_code\",\n \"external_id\": \"promocode_sku\"\n }\n ],\n \"coupons\": [\n {\n \"code\": \"WINTER2021\",\n \"external_id\": \"coupon_sku\"\n }\n ]\n },\n \"user\": {\n \"external_id\": \"id_xsolla_login_1\",\n \"email\": \"email@example.com\",\n \"country\": \"US\"\n }\n\n}'"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-length: 258\ncontent-type: application/json\nauthorization: Signature d90d319f05df7b0f86d2485f48e7079f0f752523\n\n\n{\n \"notification_type\": \"order_canceled\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.v.item_1\",\n \"type\": \"virtual_good\",\n \"is_pre_order\": false,\n \"quantity\": 3,\n \"amount\": \"1000\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"6000\",\n \"amount_with_discount\": \"5000\",\n \"sequence\": 1\n },\n {\n \"amount_without_discount\": \"5000\",\n \"amount_with_discount\": \"4000\",\n \"sequence\": 2\n }\n ],\n \"custom_attributes\": {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.v.item_new_1\",\n \"type\": \"bundle\",\n \"is_pre_order\": false,\n \"quantity\": 1,\n \"amount\": \"1000\",\n \"promotions\": []\n },\n {\n \"sku\": \"com.xsolla.gold_1\",\n \"type\": \"virtual_currency\",\n \"is_pre_order\": false,\n \"quantity\": 1500,\n \"amount\": \"[null]\",\n \"promotions\": []\n }\n ],\n \"order\": {\n \"id\": 1,\n \"mode\": \"default\",\n \"currency_type\": \"virtual\",\n \"currency\": \"sku_currency\",\n \"amount\": \"2000\",\n \"status\": \"paid\",\n \"platform\": \"xsolla\",\n \"comment\": null,\n \"invoice_id\": \"1\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"4000\",\n \"amount_with_discount\": \"2000\",\n \"sequence\": 1\n }\n ],\n \"promocodes\": [\n {\n \"code\": \"promocode_some_code\",\n \"external_id\": \"promocode_sku\"\n }\n ],\n \"coupons\": [\n {\n \"code\": \"WINTER2021\",\n \"external_id\": \"coupon_sku\"\n }\n ]\n },\n \"user\": {\n \"external_id\": \"id_xsolla_login_1\",\n \"email\": \"email@example.com\",\n \"country\": \"US\"\n }\n}"
}
]
}
},
"partial-refund": {
"post": {
"description": "Lorsqu'un remboursement partiel est effectué, Xsolla envoie les détails de la \ntransaction annulée via un webhook de type `partial_refund` à l'URL du webhook. \nPour en savoir plus sur le processus de remboursement partiel, consultez ces \n[instructions](/fr/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow).\n\nLorsque vous enregistrez l'URL du webhook dans le Compte éditeur, vous pouvez \nactiver les autorisations pour recevoir des informations détaillées dans les \nwebhooks. Pour ce faire, activez la bascule correspondante dans la section Project \nsettings > Webhooks > Advanced settings.\n\nNote
\nSi vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings > Webhooks > Testing > Payments > Advanced settings.
\n| Bascule | \nDescription | \n
|---|---|
| Afficher infos sur transactions effectuées via modes de paiement enregistrés | \nLes informations sont passées dans les paramètres personnalisés suivants du webhook :
| \n
| Code | \nMotif | \nDescription | \n
|---|---|---|
| 1 | \nCancellation by the user request / the game request | \nAnnulation initiée dans le Compte éditeur. | \n
| 3 | \nIntegration error | \nProblèmes d'intégration entre Xsolla et le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 5 | \nTest payment | \nTransaction test suivie d'une annulation. Recommandation : n'ajoutez pas l'utilisateur à la liste de noire. | \n
| 7 | \nFraud notification from PS | \nPaiement refusé par le système de paiement en raison d'une fraude potentielle. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 9 | \nCancellation by the user request | \nUtilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 10 | \nCancellation by the game request | \nAnnulation demandée par le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| Initiateur du remboursement | \nValeur du champ | \n
|---|---|
| Jeu (via API). | \nAPI | \n
| Utilisateur du Compte éditeur (remboursement automatique). | \nAdresse e-mail de l'utilisateur | \n
| Utilisateur du Compte éditeur (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Xsolla (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Code de réponse | \nDescription | \n
|---|---|
200, 201, 204 | \n Réponse de réussite. | \n
4xx | \n Une erreur s'est produite. Par exemple, si l'utilisateur spécifié est introuvable ou si une signature non valide a été passée. | \n
5xx | \n 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. | \n
Note
\nSi vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans le projet, sous la section Settings > Webhooks > Testing > Payments > Advanced settings.
\n| Bascule | \nDescription | \n
|---|---|
| Afficher infos sur le compte de paiement enregistré | \nLes informations relatives au mode de paiement enregistré sont passées à l'objet personnalisé payment_account. | \n
| Afficher infos sur transactions effectuées via modes de paiement enregistrés | \nLes informations sont passées dans les paramètres personnalisés suivants du webhook :
| \n
| Ajouter l'objet de la commande au webhook | \nLes informations relatives à la commande sont passées dans l'objet order du webhook Paiement. | \n
| Envoyer paramètres utilisateur nécessaires seulement sans données sensibles | \nSeules les informations suivantes sur l'utilisateur sont passées dans le webhook :
| \n
| Afficher BIN et suffixe de carte | \nLes informations suivantes sur le numéro de la carte bancaire sont passées dans le webhook :
| \n
| Afficher marque de carte | \nLa marque de la carte utilisée pour effectuer le paiement. Par exemple, Mastercard ou Visa. | \n
| Afficher les frais de retenue à la source par pays et les frais d'acquisition utilisateur. | \nLes 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. | \n
| Envoyer les informations 3DS. | \nL'objet cards contenant des données sur la vérification 3-D Secure sera passé dans le webhook. | \n
Remarque
\nL'ensemble des champs envoyés dans un webhook dépend :
Si vous avez des questions, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.
\nNote
\nPour recevoir le webhook ps_declined, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.
| Initiateur du remboursement | \nValeur du champ | \n
|---|---|
| Jeu (via API). | \nAPI | \n
| Utilisateur du Compte éditeur (remboursement automatique). | \nAdresse e-mail de l'utilisateur | \n
| Utilisateur du Compte éditeur (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Xsolla (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Code | \nMotif | \nDescription | \n
|---|---|---|
| 1 | \nCancellation by the user request / the game request | \nAnnulation initiée dans le Compte éditeur. | \n
| 2 | \nChargeback | \nChargeback pour une transaction demandé. | \n
| 3 | \nIntegration error | \nProblèmes d'intégration entre Xsolla et le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 4 | \nPotential fraud | \nFraude soupçonnée. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 5 | \nTest payment | \nTransaction test suivie d'une annulation. Recommandation : n'ajoutez pas l'utilisateur à la liste de noire. | \n
| 6 | \nUser invoice expired | \nFacture en retard (utilisée pour le modèle de paiement différé). | \n
| 7 | \nFraud notification from PS | \nPaiement refusé par le système de paiement en raison d'une fraude potentielle. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 8 | \nCancellation by the PS request | \nAnnulation demandée par le système de paiement. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 9 | \nCancellation by the user request | \nUtilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 10 | \nCancellation by the game request | \nAnnulation demandée par le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 11 | \nAccount holder called to report fraud | \nLe titulaire de compte déclare qu'il n'a pas effectué la transaction. | \n
| 12 | \nFriendly fraud | \nFraude de type « Friendly fraud » signalée. | \n
| 13 | \nDuplicate | \nTransaction dupliquée pour la même facture. | \n
partner_side_catalog \ncontenant les paramètres de l'utilisateur et du projet chaque fois que \nl'utilisateur interagit avec le magasin.\n\nEn réponse, renvoyez la liste des item_id ou des UGS des biens \ndisponibles pour l'utilisateur. Vous pouvez également inclure des informations \nsur la possibilité pour un utilisateur spécifique d'acheter certains biens un \ncertain nombre de fois. Cette fonctionnalité vous permet de contrôler le nombre \net le type de biens que l'utilisateur peut ajouter au panier et acheter.\n\nAvis
\nLors du traitement du webhook, tenez compte des limitations suivantes :
Remarque
\nLe paiement sera quand même remboursé à l'utilisateur si toutes les conditions suivantes sont réunies :
4xx est renvoyé, ou aucune réponse n'est reçue après toutes les tentatives, ou un code d'état 5xx est renvoyé.Note
\nSi vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans le projet, sous la section Settings > Webhooks > Testing > Payments > Advanced settings.
\n| Bascule | \nDescription | \n
|---|---|
| Afficher infos sur transactions effectuées via modes de paiement enregistrés | \nLes informations sont passées dans les paramètres personnalisés suivants du webhook :
| \n
| Afficher des informations sur le motif du remboursement. | \nInformations détaillées sur les motifs de remboursement. | \n
| Code | \nMotif | \nDescription | \n
|---|---|---|
| 1 | \nCancellation by the user request / the game request | \nAnnulation initiée dans le Compte éditeur. | \n
| 2 | \nChargeback | \nChargeback pour une transaction demandé. | \n
| 3 | \nIntegration error | \nProblèmes d'intégration entre Xsolla et le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 4 | \nPotential fraud | \nFraude soupçonnée. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 5 | \nTest payment | \nTransaction test suivie d'une annulation. Recommandation : n'ajoutez pas l'utilisateur à la liste de noire. | \n
| 6 | \nUser invoice expired | \nFacture en retard (utilisée pour le modèle de paiement différé). | \n
| 7 | \nFraud notification from PS | \nPaiement refusé par le système de paiement en raison d'une fraude potentielle. Recommandation : ajoutez l'utilisateur à la liste noire. | \n
| 8 | \nCancellation by the PS request | \nAnnulation demandée par le système de paiement. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 9 | \nCancellation by the user request | \nUtilisateur non satisfait du jeu ou de l'achat pour quelque raison que ce soit. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 10 | \nCancellation by the game request | \nAnnulation demandée par le jeu. Recommandation : n'ajoutez pas l'utilisateur à la liste noire. | \n
| 11 | \nAccount holder called to report fraud | \nLe titulaire de compte déclare qu'il n'a pas effectué la transaction. | \n
| 12 | \nFriendly fraud | \nFraude de type « Friendly fraud » signalée. | \n
| 13 | \nDuplicate | \nTransaction dupliquée pour la même facture. | \n
| Initiateur du remboursement | \nValeur du champ | \n
|---|---|
| Jeu (via API). | \nAPI | \n
| Utilisateur du Compte éditeur (remboursement automatique). | \nAdresse e-mail de l'utilisateur | \n
| Utilisateur du Compte éditeur (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
| Xsolla (avec l'assistance du service client Xsolla). | \nsupport@xsolla.com | \n
order_paid à l'URL spécifiée lorsque \nl'utilisateur effectue le paiement de la commande avec succès.\n\nLe webhook order_paid contient des informations sur les objets \nachetés, les données du paiement et les détails de la transaction.\n\nLe webhook order_paid n'est pas envoyé si le paiement n'aboutit \npas, par exemple :\n* le formulaire de paiement a été ouvert, mais l'utilisateur n'a pas procédé au \n paiement de la commande ;\n* le formulaire de paiement a été ouvert, mais des erreurs se sont produites lors \n du paiement.\n\nIl est recommandé de veiller à ce que la temps de traitement du webhook \norder_paid soit inférieur à 3 secondes.\n\nRemarque
\nL'ensemble des champs envoyés dans un webhook dépend :
Si vous avez des questions, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.
\n| Code de réponse | \nRemboursement automatique de paiement désactivé (par défaut) | \nRemboursement automatique de paiement activé | \n
|---|---|---|
400, 401, 402, 403, 404, 409, 422, 415 | \n Aucune action | \nRemboursement automatique à l'utilisateur | \n
200, 201, 204 | \n Aucune action | \nAucune action | \n
| Code différent ou absence de réponse au webhook | \nPlusieurs 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. | \nPlusieurs 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é. | \n
order_paid à l'URL spécifiée lorsque les \nconditions suivantes sont remplies :\n1. L'utilisateur a procédé au paiement de la commande avec succès.\n2. Xsolla a reçu une réponse de traitement réussi du webhook \n [Paiement](/fr/webhooks/operation/payment/).\n\nLe webhook order_paid contient des informations sur les objets \nachetés et les détails de la transaction.\n\nLe webhook order_paid n'est pas envoyé si :\n* Le paiement n'a pas été effectué, par exemple :\n * le formulaire de paiement a été ouvert, mais l'utilisateur n'a pas procédé au \n paiement de la commande ;\n * le formulaire de paiement a été ouvert, mais des erreurs se sont produites lors \n du paiement.\n* Aucune réponse de traitement réussi du webhook \n [Paiement](/fr/webhooks/operation/payment/) n'a été reçue.\n\nIl est recommandé de veiller à ce que la temps de traitement du webhook \norder_paid soit inférieur à 3 secondes.\n\nLes réponses attendues sont décrites dans la section Réponses. Vous \npouvez utiliser d'autres codes de réponse. En fonction du code de réponse et de \nla connexion à la fonctionnalité de remboursement automatique de paiement, la \nlogique de traitement du webhook côté Xsolla est la suivante :\n\n| Code de réponse | \nRemboursement automatique de paiement désactivé (par défaut) | \nRemboursement automatique de paiement activé | \n
|---|---|---|
400, 401, 402, 403, 404, 409, 422, 415 | \n Aucune action | \nRemboursement automatique à l'utilisateur | \n
200, 201, 204 | \n Aucune action | \nAucune action | \n
| Code différent ou absence de réponse au webhook | \nPlusieurs 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. | \nPlusieurs 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é. | \n
Note
\nSi vous avez créé un Compte éditeur le 22 janvier 2025 ou avant, les bascules se trouvent dans la section Project settings > Webhooks > Testing > Payments > Advanced settings.
\n| Bascule | \nDescription | \n
|---|---|
| Envoyer paramètres utilisateur nécessaires seulement sans données sensibles | \nSeules les informations suivantes sur l'utilisateur sont passées dans le webhook :
| \n
| Envoyer paramètres personnalisés | \nLes informations relatives aux paramètres du jeton personnalisé sont passées dans le webhook. | \n
custom_parameters lors de l’appel pour obtenir un jeton de paiement.