Démarrage rapide

Flux d'intégration

Pour intégrer la solution Payments :

Créez un projet dans le Compte éditeur. Un projet correspond à un jeu. Si vous avez plusieurs jeux, ajoutez un projet pour chaque jeu.
Ajoutez les objets que vous souhaitez vendre au catalogue côté Xsolla.
Testez la création d’une commande pour laquelle un utilisateur paiera.
Testez en réalisant un achat test et configurez les notifications.
Signez le contrat de licence avec Xsolla dans le Compte éditeur pour commencer à traiter les paiements réels.

Vous pouvez signer le contrat de licence à n’importe quelle étape de l’intégration, mais gardez à l’esprit que le processus d’examen peut prendre jusqu’à trois jours ouvrables.

Créer un catalogue

Les objets virtuels sont du contenu en jeu que l’utilisateur peut acheter contre des devises réelles ou de la monnaie virtuelle. La création d’un catalogue d’objets virtuels côté Xsolla vous permet de personnaliser les prix et les restrictions régionales, ainsi que d’utiliser le système de promotions et d’autres fonctionnalités de Xsolla, qui sont régulièrement enrichies et mises à jour.

Créer des objets virtuels

Obtenir la liste des objets

Pour obtenir la liste des objets, appelez la méthode API Lire une liste d’objets virtuels :

Dans l’en-tête de la requête, passez le JWT Xsolla Login (jeton Bearer) utilisé par défaut pour l’autorisation. Pour tester l’appel à cette méthode API, utilisez le jeton de test suivant : Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI ;
Dans le project_id paramètre de chemin, passez l’ID du projet, qui se trouve dans le Compte éditeur :

En réponse, vous recevrez des informations détaillées sur les objets virtuels créés dans votre projet. Pour créer une commande aux étapes qui suivent, vous aurez besoin du SKU de l’objet, qui est passé dans le paramètre items.sku.

Créer une commande

Une commande comprend les objets que souhaite acheter un utilisateur dans le magasin. Une fois que la commande est payée, l’utilisateur reçoit les objets. Pour effectuer un paiement, l’utilisateur doit être connecté à son compte de jeu.

Sélectionnez une méthode d’intégration adaptée à votre jeu pour voir les instructions de configuration.

Caractéristiques	Côté serveur	Côté client
Disposer d’un serveur	Vous devez disposer de votre propre serveur pour obtenir des jetons et contrôler la charge du serveur.	Vous n’avez pas besoin de disposer de votre propre serveur.
Détermine le pays de l’utilisateur	Veillez à indiquer le pays ou l’adresse IP dans le jeton de paiement ; cela influe sur les modes de paiement disponibles.	Xsolla détermine le pays de l’utilisateur en fonction de l’adresse IP.
Détermine la devise de paiement	Si la devise n’est pas passée dans le jeton, elle est déterminée en fonction du pays. Si la devise est passée dans le jeton, l’utilisateur paie dans cette devise.	La devise est déterminée en fonction du pays.

Appelez la méthode API Create payment token for purchase et passez dans cette dernière les informations sur l’utilisateur et les objets. Cet appel API peut être utilisé pour vendre un ou plusieurs objets.

Pour utiliser le mode bac à sable, passez le paramètre “sandbox”: true dans le corps de la requête pour obtenir un jeton.

La valeur du paramètre user_id :

Lors des tests, vous pouvez passer n’importe quel symbole dans ce paramètre.
Pour accepter des paiements réels, passez l’ID de l’utilisateur dans votre système en tant que valeur de ce paramètre. Cet ID est passé dans le webhook Validation utilisateur.

Exemple de requête :

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Intégrez la solution Xsolla Login :

À l’aide de la méthode de Login configurée, créez et enregistrez un jeton d’authentification afin de recevoir un jeton de paiement. Le jeton de paiement est utilisé pour ouvrir l’interface de paiement et effectuer le paiement.

Pour tester le flux de paiement, créez une commande à l’aide de la méthode API Create order with specified item :

Si vous souhaitez effectuer un test sur le site Web de la documentation API, cliquez sur Try it pour ouvrir l'interface de création de requête.
Dans le champ Bearer Token du bloc Security, entrez le jeton obtenu en passant la procédure d'authentification.
Dans le bloc Body, passez les détails de la commande, par exemple la quantité de l'objet. Pour accéder au mode bac à sable, passez "sandbox": true.
Dans le bloc Parameters, passez :
- project_id — l'ID du projet que vous trouverez dans votre Compte éditeur ;
- item_sku — UGS de l'objet.

En réponse, vous recevrez les données dont vous aurez besoin aux étapes qui suivent :

token — jeton de paiement.

Exemple de requête :

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Pour appeler les API de Xsolla, vous pouvez utiliser les méthodes SDK prêtes à l’emploi pour les moteurs de jeu et les plateformes :

Effectuer un achat test

Les tests n’impliquent pas de retrait d’argent d’un compte bancaire réel : vous pouvez utiliser l’une de nos cartes de test.

Avant la signature d’un contrat avec Xsolla, le test du processus de paiement n’est disponible qu’en mode bac à sable.

Ouvrir l'interface de paiement en mode bac à sable

Pour ouvrir l’interface de paiement dans une nouvelle fenêtre, utilisez l’URL suivante : https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, où TOKEN est le jeton obtenu lors de la création de la commande.

Pour ouvrir l’interface de paiement à l’aide d’autres méthodes, reportez-vous à la documentation.

Effectuer un paiement test

Ouvrez l'interface de paiement en mode bac à sable.
Choisissez le mode de paiement Carte bancaire.
Entrez les informations de la carte bancaire. Dans les autres champs (par exemple, le nom ou l'adresse), entrez n'importe quelle donnée. Vous pouvez également indiquer des informations incorrectes (numéro de carte ou date d'expiration) pour vérifier si une erreur est générée.
Cliquez sur Pay.

Liste des cartes de test

Voir la liste des cartes bancaires de test.

Informations sur les codes postaux

Outre les informations de la carte, vous devez indiquer le code postal si au moins l’une des conditions suivantes est vraie :

Le pays de l’utilisateur est les États-Unis ou le Canada.
Le numéro d’identification bancaire (BIN) indique que la carte a été émise aux États-Unis.

Vous pouvez indiquer n’importe quel code postal valide (par exemple, 12345). Il détermine le taux de la taxe de vente, mais n’affecte pas la progression du paiement test.
Les paiements par carte bancaire en mode bac à sable peuvent être effectués dans les devises suivantes : USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

En mode bac à sable, vous pouvez tester le paiement unique et le paiement par modes de paiement enregistrés en utilisant des cartes bancaires ou PayPal.

Configurer des webhooks

Si vous avez configuré l’intégration côté serveur, vous devez valider les commandes créées en en répondant avec le code approprié aux webhooks. Si vous configurez l’intégration côté client, les webhooks vous permettront de recevoir des notifications sur les événements configurés, tels que le changement de statut de paiement.

Pour activer la réception des webhooks :

Ouvrez le projet dans le Compte éditeur.
Dans le menu latéral, cliquez sur Project settings et accédez à l’onglet Webhooks.
Dans le champ Webhook server, spécifiez l’URL du serveur où vous souhaitez recevoir les webhooks, dans le format https://example.com. Vous pouvez également spécifier l’URL que vous trouvez dans un outil de test de webhooks.
Une clé secrète pour signer les webhooks du projet est générée par défaut. Si vous souhaitez générer une nouvelle clé secrète, cliquez sur l’icône d’actualisation.
Cliquez sur Enable webhooks.

PHP SDK

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

Pour tester les webhooks, vous pouvez choisir n’importe quel site dédié, tel que webhook.site, ou une plateforme, telle que ngrok.

Pour recevoir des notifications sur la validation de l’utilisateur et les paiements réussis, configurez les webhooks suivants :

Validation utilisateur — pour les notifications afin de s’assurer que l’utilisateur est enregistré dans le jeu ;
Paiement — pour les notifications indiquant que le paiement a été effectué.

Référez-vous à la documentation pour obtenir des informations détaillées sur la configuration et le test des webhooks.

Configurer l'écouteur Webhook

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

Informations sur la génération de signature et l’envoi de réponses au webhook

Génération d'une signature

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

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

Envoi de réponses au webhook

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

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

Votre gestionnaire de webhooks peut également renvoyer un code 5xx en cas de problèmes temporaires sur votre serveur. Si aucune réponse n’a été reçue pour les webhooks Successful payment of the order et Order cancellation ou si une réponse contenant un code 5xx a été reçue, les webhooks sont renvoyés selon le calendrier suivant :

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

Un maximum de 20 tentatives d’envoi de webhooks sont effectuées dans les 12 heures suivant la première tentative. Si aucune réponse n’a été reçue pour le webhook Payment ou si une réponse contenant un code 5xx a été reçue, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectuées dans les 12 heures. Si aucune réponse n’a été reçue pour le webhook User validation ou si une réponse contenant un code 400 ou 5xx a été reçue, le webhook User validation n’est pas renvoyé. Dans ce cas, une erreur est affichée à l’utilisateur et les webhooks Payment et Successful payment of the order ne sont pas envoyés.

Lancer

Avant la signature du contrat de licence, vous ne pouvez ouvrir l’interface de paiement qu’en mode bac à sable.

Signer un contrat de licence

La signature du contrat de licence vous permettra de recevoir des paiements réels via tous les modes de paiement pris en charge par Xsolla. Pour signer le contrat de licence :

Ouvrez votre Сompte éditeur.
Dans le menu latéral, accédez à la section Agreements and taxes > Agreements.
Dans l’onglet Licensing Agreement, cliquez sur Fill out application form.
Entrez vos informations dans les champs correspondants.

Votre demande sera examinée dans un délai de 3 jours ouvrables. Si des questions surviennent pendant le processus de vérification, Xsolla contactera la personne de contact spécifiée dans la demande. Une fois que Xsolla a terminé la procédure de vérification, le statut de votre contrat passera à Signed.

Passer à l'environnement de production

Après le premier paiement réel, une politique de paiement stricte entre en vigueur. Effectuer des paiements en mode bac à sable ne sera disponible qu’aux utilisateurs spécifiés dans le Compte éditeur, sous la section Company settings > Users.

Après avoir effectué les étapes précédentes, vous pouvez commencer à recevoir des paiements réels :

Assurez-vous que vous avez signé le contrat de licence avec Xsolla.
Supprimez “sandbox”: true du corps de votre requête de jeton.
Ouvrez l’interface de paiement en utilisant le lien suivant : https://secure.xsolla.com/paystation4/?token=TOKEN.

Ce guide décrit les configurations minimales requises pour démarrer rapidement l’intégration. Si vous avez des questions, contactez-nous via Xsolla Chat en bas à droite de la page ou envoyez un e-mail à votre responsable de la réussite client à l’adresse csm@xsolla.com.

Merci pour votre commentaire !

Nous examinerons votre message et l'utiliserons pour améliorer votre expérience.

Évaluer cette page

Préfère ne pas répondre

Merci pour votre commentaire !

Dernière mise à jour: 18 Mars 2024

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.

Your browser is not supported. Please try a different browser

Payments

Démarrage rapide

Flux d'intégration

Créer un catalogue

Créer des objets virtuels

Obtenir la liste des objets

Créer une commande

Effectuer un achat test

Ouvrir l'interface de paiement en mode bac à sable

Effectuer un paiement test

Configurer des webhooks

Configurer l'écouteur Webhook

Génération d'une signature

Envoi de réponses au webhook

Lancer

Signer un contrat de licence

Passer à l'environnement de production

Cet article vous a été utile ?

Évaluer cette page

Merci pour votre commentaire !