Xsolla-logoXsolla Developers
ou
Vers le Compte éditeur

PaiementWebhook POST

Lorsque l'utilisateur effectue un paiement, Xsolla envoie les informations sur le paiement via un webhook de type payment à l'URL du webhook.

Si une réponse contenant un code 5xx est reçue, Xsolla renvoie un webhook avec un intervalle de temps prolongé jusqu'à ce que votre écouteur confirme la réception. Le nombre maximum de tentatives est de 12.

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 > Webhooks > 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 > Webhooks > Testing > Payments > 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.

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.

Request
Request Body schema: application/json
notification_type
required
string

Type de notification.

required
object

Détails de la transaction (objet).

agreement
integer

ID de contrat.

dry_run
integer

Transaction test. Le paramètre a la valeur 1 s'il s'agit d'une transaction test ou n'est pas envoyé si la transaction est réelle.

external_id
string

External ID de la transaction. Pour obtenir des informations détaillée, reportez-vous à la FAQs.

id
integer

ID de transaction.

payment_date
string

Date de paiement.

payment_method
integer

ID de mode de paiement.

payment_method_name
string

Nom de mode de paiement.

payment_method_order_id
string

ID de paiement dans le système de paiement.

required
object

Informations sur le paiement (objet).

object

Retenue à la source appliquée dans certains pays pour les transactions transfrontalières (objet).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

percent
number <float>

Taux de retenue à la source du pays, en %.

object

Retenue à la source directe.

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

percent
number <float>

Taux de retenue à la source directe.

object

Montant payé par l'utilisateur (objet).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Frais du système de paiement.

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Montant débité du système de paiement.

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Détails de virement (objet).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

payout_currency_rate
string

Taux de change entre les devises de paiement et de virement.

object

Données sur les frais de rapatriement imposés à Xsolla par des tiers.

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Taxe de vente (objet ; États-Unis et Canada uniquement).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

percent
number <float>

Taux de taxe de vente.

object

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).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

percent
number <float>

Taux de la commission d'acquisition de l'utilisateur, en %.

object

Informations sur la TVA (objet ; UE uniquement).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

percent
number <float>

Taux de TVA.

object

Montant débité du solde Xsolla.

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Frais Xsolla (objet).

amount
number <float>

Montant.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

custom_parameters
object

Vos paramètres personnalisés.

object

Informations sur l'achat (objet).

required
object

Prix total d'achat (objet).

amount
number <float>

Montant total du paiement.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Informations au moment du paiement (objet).

amount
number <float>

Montant de l'achat.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

object

Informations sur le coupon (objet ; si un coupon a été utilisé lors de la création de l'abonnement).

campaign_code
string

Code de campagne.

coupon_code
string

Code de coupon.

object

Informations sur le cadeau (objet).

giver_id
string

ID du donneur.

hide_giver_from_receiver
string

Détermine l'affichage de l'identité du donneur au destinataire.

message
string

Message du donneur.

receiver_email
string

Adresse e-mail du destinataire du cadeau.

receiver_id
string

ID du destinataire du cadeau.

object

Objet contenant des informations sur une commande. Pour recevoir ces informations, réglez la bascule Ajouter l'objet de la commande au webhook sur On dans le Compte éditeur dans la section Project settings > Webhooks > Advanced settings.

id
integer

ID de commande.

object

Informations sur l'objet.

object

Informations sur le prix de l'objet.

amount
number <float>

Prix total de l'objet dans la devise sélectionnée.

currency
string

Devise du prix de l'objet.

quantity
integer

Quantité de l'objet.

sku
string

UGS de l'objet.

Array of objects

Promotions appliquées à cette transaction.

Array
id
integer

ID de promotion.

technical_name
string

Nom technique de la promotion.

object

Informations de l'abonnement (objet).

amount
number <float>

Prix en monnaie réelle.

currency
string

Devise. Code de devise à trois lettres selon la norme ISO 4217.

date_create
string

Date de création de l'abonnement. Date et heure selon la norme ISO 8601.

date_next_charge
string

Prochaine date de facturation. Date et heure selon la norme ISO 8601.

plan_id
string

ID de plan (externe si le plan a été créé via API).

product_id
string

ID de produit (s'il est passé dans le jeton d'accès).

subscription_id
integer

ID d'abonnement dans la base de données Xsolla.

tags
Array of strings

Balises du plan.

object

Paramètres personnalisés de projet (objet).

merchant_id
integer

ID de commerçant.

project_id
integer

ID de projet. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.

object

Informations sur l'utilisateur (objet).

id
required
string

ID utilisateur.

country
string

Pays de l'utilisateur. Code pays à deux lettres majuscules selon la norme ISO 3166-1 alpha-2.

email
string

Adresse e-mail de l'utilisateur.

ip
string

IP de l'utilisateur.

name
string

Nom d'utilisateur.

phone
string

Téléphone de l'utilisateur.

zip
string

ZIP ou code postal de l'utilisateur.

Responses
204

Renvoyez pour indiquer un traitement réussi.

400

Renvoyez en cas d'erreur dans les informations fournies (par exemple, un paramètre requis manquant, une autorisation échouée, etc.). Dans ce cas, l'utilisateur est débité, mais l'achat échoue. Pour procéder au remboursement, contactez le service client Xsolla à support@xsolla.com.

500

Renvoyez pour indiquer des erreurs temporaires liées à vos serveurs.

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
      "project_id": 18404,
      "merchant_id": 2340
    },
    "purchase": {
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "com.xsolla.item_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_name": "PayPal",
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0,
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "payout_currency_rate": "1",
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "country_wht": {
            "currency": "USD",
            "amount": 2,
            "percent": 10
        },
        "user_acquisition_fee": {
            "currency": "USD",
            "amount": 2,
            "percent": 1
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": 10
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'
Response samples
application/json
{
  • "error": {
    }
}
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.