Cash Kiosks API v2.0

API Game catalog

L’API fournit un catalogue de jeux, c’est-à-dire la liste de tous les projets disponibles dans le système Xsolla. Elle présente les informations de base de chaque projet, comme son nom, son icône et ses paramètres de paiement. Ces informations peuvent servir à créer des pages de paiement pour les projets.

L’API du catalogue des jeux peut faciliter les paiements sur les bornes de paiement en espèces et l’ajout de « boutons de jeu » à leurs interfaces. Remplacer le bouton Xsolla habituel par un « bouton de jeu » sur l’écran d’une borne permet aux utilisateurs d’effectuer des paiements dans leurs projets préférés de manière simple et familière.

API URL: https://api.xsolla.com/projects/list/index.php

Format de requête

Paramètres de requête pour obtenir la liste des jeux

Génération de la signature

La signature sécurise la vérification et l’exécution des paiements. Elle est générée en calculant le hachage MD5 d’une chaîne composée des paramètres ci-dessus, séparés par « | » et concaténés dans l’ordre indiqué ci-dessous.

1md5(<ID>|<secret_key>)

secret_key : clé secrète de la contrepartie.

Exemple : La signature pour la contrepartie #184 avec la clé secrète « SecretKey » est générée comme suit :

$sign=md5(“184|SecretKey”)=0a8d9fb24fcbac2efafec5e51045d05c

Exemple de requête :

https://api.xsolla.com/projects/list/index.php?id=184&sign=0a8d9fb24fcbac2efafec5e51045d05c

Format de la réponse

La réponse au format XML contient la liste des jeux et les informations de base de chacun. Sa structure est la suivante :

 1<projectlist>
 2   <project>
 3       <id>12345</id>
 4       <name>Game</name>
 5       <virtual_currency>Game of currency</virtual_currency>
 6       <logo>http://static.xsolla.com/img/game/12345.gif</logo>
 7       <limits>
 8           <min>Minimum of amount game of currency</min>
 9           <max>max of amount game of currency</max>
10       </limits>
11       <prompt>enter nickname of personage</prompt>
12       <v1>nickname of personage</v1>
13   </project>
14   ...
15</projectlist>

Description des champs

Format de réponse en cas d’erreur

En cas d’erreur, l’API renvoie un message XML.

1<error>
2    <description>Incorrect signature</description>
3</error>

Description des erreurs

Interaction avec l’agent

Aperçu

Deux options d’interaction sont possibles :

• Bouton Xsolla. Ce bouton est placé côté agent. Lorsque l’utilisateur appuie dessus, il est invité à entrer un numéro reçu au préalable, puis à effectuer le paiement associé à ce numéro. Pour activer les paiements via le bouton Xsolla, renseignez le champ account. Renseignez le champ account avec le numéro Xsolla à 9 chiffres et laissez les champs project, v1, v2, v3 vides. Pour configurer ce bouton, contactez un responsable de compte afin d’obtenir un logo et le numéro.

• Boutons de jeu. Ces boutons sont placés côté agent et correspondent chacun à un jeu différent. L’utilisateur appuie sur le bouton d’un jeu, puis se connecte pour effectuer un paiement sur son compte. Pour activer les paiements via ces boutons, renseignez les champs project, v1, v2 et v3 et laissez le champ account vide. Vous pourrez passer les champs project, v1, v2 et v3 une fois le bouton du projet (jeu) configuré sur le terminal. Les champs project and v1 sont obligatoires ; v2 and v3 sont facultatifs et dépendent du projet. Pour configurer les boutons de jeu, contactez un responsable de compte afin d’obtenir les logos, les ID internes, les méthodes d’autorisation (règles de saisie des champs v1, v2, v3) et les autres informations propres à chaque jeu.

Un bouton est un élément du système de l’agent qui déclenche un paiement via le système Xsolla.

Avant de connecter l’agent au système Xsolla, confirmez les éléments suivants :

1. Numéro de partenaire (type) dans le système Xsolla. Pour l'obtenir, contactez un responsable de la réussite client Xsolla.
2. secret_key : chaîne de caractères confidentielle nécessaire à la génération de la signature numérique (chaîne MD5). Vous pouvez l'obtenir dans le Compte éditeur par l'intermédiaire d'un responsable de la réussite client.

Pour interagir avec l’API, envoyez des requêtes HTTP à sa passerelle, à l’adresse suivante :

1https://ps.xsolla.com/api/gate

L’API accepte les requêtes GET et POST. Tous les paramètres doivent être encodés en UTF-8 pour éviter les erreurs de signature.

Format de la requête

Les requêtes vers Xsolla sont possibles dans les cas suivants :

• vérifier si le paiement est possible (command = check)
• effectuer un paiement (command = pay)
• vérifier si le paiement a réussi (command = status)
• calculer le coût et le montant de monnaie de jeu (command = calculate)

Commande check

Commande check : identifier l’utilisateur par numéro Xsolla

Commande check : identifier l’utilisateur par project/v1/v2/v3

Commande pay

Commande pay : identifier l’abonné à l’aide du paramètre account

Commande pay : identifier l’abonné à l’aide des paramètres project/v1/v2/v3

Commande status

Vous pouvez vérifier si le paiement a réussi soit par l’ID de transaction dans votre système (paramètre id), soit par l’ID de transaction côté Xsolla (paramètre invoice). Si vous passez les deux paramètres, ils doivent appartenir au même paiement ; sinon, Xsolla renvoie une erreur de validation.

Commande status : vérifier la réussite du paiement par ID de transaction dans votre système

Exemple :

1https://ps.xsolla.com/api/gate?command=status&id=xsollaid2&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

Commande status : vérifier la réussite du paiement par ID de transaction côté Xsolla

Exemple :

1https://ps.xsolla.com/api/gate?command=status&invoice=987654321&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

Commande calculate

Génération du champ MD5

La signature sécurise les paiements et leur vérification. Elle est générée en calculant le hachage MD5 d’une chaîne formée des valeurs de tous les paramètres transmis, concaténées dans l’ordre de la requête, y compris les paramètres facultatifs présents, puis de la clé privée du système de paiement. Vous pouvez obtenir cette clé auprès d’un responsable de la réussite client Xsolla.

Commande check

 1<?php
 2  $request['command']='check';
 3  $request['account']=1234567;
 4  $request['sum']=150.75;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

Chaîne :

check1234567150.7515120110117000516test

MD5 :

1cad5a2c3457cffa8e857a507a7050ba

Commande pay

 1<?php
 2$request['command']='pay';
 3$request['account']=1234567;
 4$request['sum']=150.75;
 5$request['id']=384957;
 6$request['type']=151;
 7$request['date']='20110117000516';
 8$md5='';
 9foreach ($request as $value) {
10$md5.=$value;
11}
12$request['md5']=md5($md5.$secret_key);
13?>

Chaîne :

pay1234567150.7538495715120110117000516test

MD5 :

7cfa05abde4ae2464142bf2ac7a72f32

Génération de la signature pour la commande status (vérification par ID de transaction dans votre système)

 1$request['command'] = 'status';
 2$request['id']      = 'xsollaid2';
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

Chaîne :

statusxsollaid215120110117000516+secret_key

MD5 :

7cfa05abde4ae2464142bf2ac7a72f32 (exemple)

Génération de la signature pour la commande status (vérification par ID de transaction côté Xsolla)

 1$request['command'] = 'status';
 2$request['invoice'] = 987654321;
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

Chaîne :

status98765432115120110117000516+secret_key

MD5 :

7cfa05abde4ae2464142bf2ac7a72f32 (exemple)

Commande calculate

 1<?php
 2  $request['command']='calculate';
 3  $request['project']=4783;
 4  $request['out']=12;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

Chaîne :

calculate47831215120110117000516test

MD5 :

e73e11a9cad00e205358e05254905af5

Réponses

Codes de réponse

Xsolla génère un XML contenant le code de statut dans result et la description dans comment.

Exemple de réponse contenant une erreur :

1<response>
2  <result>7</result>
3  <comment>md5 error</comment>
4</response>

Codes de réponse en cas de succès

Si 0 est renvoyé dans result, la réponse contient également le bloc payment avec des informations détaillées sur le paiement. Le statut du paiement est passé dans le code via le paramètre status.

Exemple de réponse réussie à la commande status :

 1<response>
 2  <payment>
 3    <invoice>123456789</invoice>
 4    <id>xsollaid2</id>
 5    <sum>100.98</sum>
 6    <project>4783</project>
 7    <v1>XsollaUser</v1>
 8    <date>2026-01-23 12:34:56</date>  <!-- present only when status is succeeded -->
 9    <status>1</status>
10    <comment>succeeded</comment>
11    <statusKioskUrl>https://secure.xsolla.com/pages/status-kiosk?id=123456789&key=9e07b3…</statusKioskUrl>
12  </payment>
13  <result>0</result>
14</response>

API du registre des transactions du système de paiement

Ce document s’adresse aux développeurs souhaitant utiliser l’API du registre des transactions du système de paiement pour permettre aux utilisateurs d’acheter des objets et services virtuels dans leur projet. Il suppose une connaissance de base des API, des requêtes HTTP et des architectures logicielles.

Interaction avec l’API

• Le fonctionnement nécessite une intégration serveur à serveur ;

• Tous les paramètres doivent être encodés en UTF-8 ;

• Les données sont renvoyées au format CSV.

Description des méthodes API

• Get – recevoir les données de paiement.

URL de l’API

URL de base : https://api.xsolla.com/payments/

Masque d’URL

1https://api.xsolla.com/payments/v<number versions>/<command>?<parameter1=value1>&<parameter2=value2

Get

Crée une requête pour récupérer les données des paiements effectués au cours des dernières 24 heures via tous les systèmes de paiement de la contrepartie indiquée.

Obtenir l’accès à l’API

Pour accéder à l’API, contactez un responsable de la réussite client ou envoyez un e-mail à [email protected] afin d’obtenir un ID de partenaire unique et une clé secrète.

Exemple de requête

https://api.xsolla.com/payments/v1/Get?date=2013-08-20&id=1234&sign=8f683701c03b03fe49e6ef7bbfafb8fb

Paramètres d’entrée

Réponse

La réponse est fournie au format CSV, avec « , » comme séparateur :

69927355,95188933,394,2013-08-01T06:49:25+04:00,91.0000,RUB,done

Description des champs :

Génération de la signature

Les paramètres sont triés par ordre alphabétique de leurs clés. La signature correspond au hachage MD5 d’une chaîne formée des valeurs des paramètres, suivies de la clé secrète, avec « | » comme séparateur. Vous pouvez obtenir cette clé auprès d’un responsable de la réussite client.

Exemple de requête

1date = 2013-08-20;
2id=1234;
3secret_key=password.

La chaîne se présente sous la forme suivante :

2013-08-20|1234|password

MD5 de la chaîne ci‑dessus :

e8df0ff2e4360300a5142cc28d86b422

Liste des codes de complétion

Rapprochement des transactions avec les systèmes de paiement

Rapprochement via notification par e-mail

Le rapprochement des transactions consiste, pour le système de paiement, à envoyer un e-mail accompagné d’une pièce jointe dans un format précis. La fréquence du rapprochement doit être convenue à l’avance.

Format du document de rapprochement

Le document de rapprochement doit respecter les exigences suivantes :

• Encodage UTF-8
• Format CSV, avec une virgule ou un point-virgule comme séparateur
• Envoi à [email protected] depuis une adresse e-mail convenue à l’avance
• Objet de l’e-mail : « stats registry »
• Nom du fichier joint : stats_registry_period, où period correspond à start_dateTend_date, avec les dates au format YYYY-MM-DD. Si la période couvre un seul jour (24 heures), la partie commençant par T peut être omise

Contenu du document

Exemple de registre

Exemple 1

197035765;6654448;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
397035766;6634558;150.00;145.00;RUB;done;2011-09-01 16:43:54;[email protected]

Exemple 2 (si le système de paiement ne contient pas de pid)

1564;;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
3456;;150.00;145.00;RUB;done;2011-09-01 16:43:54;[email protected]

Exemple 3 (en l’absence de desc, notez le point-virgule final)

1564;6654855;10.00;9.50;RUB;done;2011-09-01 13:30:45;
2
3456;4588554;150.00;145.00;RUB;done;2011-09-01 16:43:54;

Rapprochement via l’API du système de paiement

Le rapprochement des transactions peut également s’effectuer via l’API HTTP (HTTPS) du système de paiement. Après avoir interrogé l’API, celle-ci doit renvoyer à Xsolla les paramètres suivants :