Automaten-API v2.0

Spielekatalog-API

Die API dient zur Bereitstellung eines Spielkatalogs, d. h. eine Liste aller verfügbaren Projekte im Xsolla-System. Die API liefert zu jedem Projekt grundlegende Informationen wie Projektname, Projektsymbol und Zahlungsparameter, usw. Die zuvor genannten Informationen können genutzt werden, um Zahlungsseiten für Projekte zu erstellen.

Die Spielekatalog-API kann für Zahlungen an Automaten und für die Platzierung von sogenannten “Spiel-Schaltflächen” auf der grafischen Benutzeroberfläche genutzt werden. Das Ersetzen der üblichen Xsolla-Schaltfläche durch eine “Spiel-Schaltfläche” auf dem Automatenbildschirm ermöglicht es dem Benutzer, Zahlungen für sein Lieblingsprojekt auf einfache und gewohnte Weise vorzunehmen.

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

Anfrageformat

Anfrageparameter zum Abrufen der Spielliste

Signatur generieren

Die Signatur gewährleistet die Sicherheit bei der Überprüfung und Durchführung der Zahlung. Sie wird mittels MD5-Hash-Algorithmus aus dem String gebildet, welcher durch Verknüpfung der zuvor genannten Parameter erzeugt wird. Die Parameter sind dabei mittels “|” in der nachfolgend dargestellten Reihenfolge voneinander getrennt.

1md5(<ID>|<secret_key>)

secret_key: Geheimer Schlüssel der Gegenpartei.

Beispiel: Die Signatur für die Gegenpartei #184 mit dem geheimen Schlüssel “SecretKey” wird wie folgt gebildet:

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

Beispiel einer Anfrage:

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

Antwortformat

Die Antwort erfolgt im XML-Format und enthält sowohl die Spielliste als auch grundlegende Informationen zu jedem Spiel. Das XML hat folgende Struktur:

 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>

Beschreibung der Felder

Antwortformat im Fehlerfall

Im Fehlerfall antwortet die API mit einer XML-Nachricht.

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

Fehlerbeschreibung

Interaktion mit dem Agenten

Überblick

Es gibt zwei mögliche Interaktionsoptionen:

• Xsolla-Schaltfläche. Diese Schaltfläche wird aufseiten des Agenten platziert. Nach einem Klick auf die Schaltfläche wird der Nutzer aufgefordert, eine zuvor erhaltene Nummer einzugeben und eine Zahlung an diese Nummer vorzunehmen. Damit Zahlungen über die Xsolla-Schaltfläche möglich sind, muss das Feld account ausgefüllt (die Felder project, v1, v2, v3 müssen leer bleiben) werden. Im Feld account muss die 9-stellige Xsolla-Nummer angegeben sein. Wenden Sie sich zur Einrichtung der Xsolla-Schaltfläche an Ihren Customer Success Manager, um Logo und Nummer zu erhalten.

• Spiel-Schaltflächen. Diese Schaltfläche wird aufseiten des Agenten platziert und beziehen sich jeweils auf ein anderes Spiel. Der Nutzer klickt auf die Schaltfläche eines bestimmten Spiels und meldet sich anschließend an, um eine Zahlung über sein eigenes Konto vorzunehmen. Damit Zahlungen über spielspezifische Schaltflächen möglich sind, müssen die Felder project, v1, v2 und v3 ausgefüllt werden (das Feld account muss leer bleiben). Sie können die Felder project, v1, v2 und v3 erst dann übermitteln, nachdem die jeweilige Projekt-/Spiel-Schaltfläche am Automaten konfiguriert wurde. Die Felder project und v1 sind Pflichtfelder, während v2 und v3 optional sind und vom jeweiligen Projekt abhängen. Wenden Sie sich zur Einrichtung der Spiel-Schaltflächen an den Manager, um Spiellogos, die internen IDs der Spiele, Autorisierungsmethoden (Regeln zum Ausfüllen der Felder v1, v2, v3) sowie weitere Informationen für das jeweilige Spiel zu erhalten.

Bei einer Schaltfläche handelt es sich um ein Element des Agentensystems, dessen Betätigung eine Zahlung über das Xsolla-System initiiert.

Vor der Einbindung des Agenten in das Xsolla-System muss folgendes geklärt werden:

1. Partnernummer (Typ) im Xsolla-System. Wenden Sie sich dafür an Ihren Customer Success Manager bei Xsolla.
2. secret_key, vertraulicher String-Parameter, der für die Generierung der digitalen Signatur (MD5-String) benötigt wird. Dieser befindet sich in Ihrem Kundenportal, andernfalls wenden Sie sich bitte an Ihren Customer Success Manager.

Die Interaktion mit der API erfolgt durch das Senden eine HTTP-Anfrage an die API-Gateway:

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

Die API akzeptiert GET- und POST-Anfragen. Alle Parameter müssen in UTF-8 kodiert werden. Bitte beachten Sie, dass die Verwendung von UTF-8-Kodierung entscheidend ist, da bei der Verwendung verschiedener Zeichensätze Signaturprobleme auftreten können.

Anfrageformat

Anfragen an Xsolla können in folgenden Fällen gestellt werden:

• um zu prüfen, ob eine Zahlung möglich ist (command = check)
• um eine Zahlung durchzuführen (command = pay)
• um zu prüfen, ob die Zahlung erfolgreich war (command = status)
• um Kosten und Betrag der Spielwährung zu berechnen (command = calculate)

Befehl “Check”

Befehl “Check”: Nutzer anhand von Xsolla-Nummer identifizieren

Befehl “Check”: Nutzer anhand von project/v1/v2/v3 identifizieren

Befehl “Pay”

Befehl “Pay”: Abonnent anhand von account identifizieren

Befehl “Pay”: Abonnent anhand von project/v1/v2/v3 identifizieren

Befehl “Status”

Sie können prüfen, ob die Zahlung erfolgreich war, entweder anhand der Transaktions-ID in Ihrem System (Parameter id) oder anhand der Transaktions-ID aufseiten von Xsolla (Parameter invoice). Wenn Sie beide Parameter übermitteln, müssen diese zur selben Zahlung gehören; andernfalls gibt Xsolla einen Validierungsfehler zurück.

Befehl “Status”: Zahlungsstatus anhand der Transaktions-ID in Ihrem System prüfen

Beispiel:

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

Befehl “Status”: Zahlungsstatus anhand der bei Xsolla hinterlegten Transaktions-ID prüfen

Beispiel:

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

Befehl “Calculate”

MD5-Feld generieren

Die Signatur kommt beim Prüfen und Leisten von Zahlungen zum Einsatz und dient dazu, die Sicherheit zu gewährleisten. Sie wird mithilfe des MD5-Hash-Algorithmus aus dem String generiert und aus der Verknüpfung aller übertragenen Parameterwerte abgeleitet. Die Verknüpfung der Werte erfolgt in der gleichen Reihenfolge, in der die Parameter bei der Anfrage aufgelistet werden. Im Falle von optionalen Parametern gilt: Wurde der Parameter übermittelt, so ist er Bestandteil der Signaturerstellung. Außerdem ist ein geheimer Zahlungssystem-Schlüssel an der Signaturerstellung beteiligt, den Sie von Ihrem Customer Success Manager erhalten können.

Befehl “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?>

Zeile:

check1234567150.7515120110117000516test

MD5:

1cad5a2c3457cffa8e857a507a7050ba

Befehl “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?>

Zeile:

pay1234567150.7538495715120110117000516test

MD5:

7cfa05abde4ae2464142bf2ac7a72f32

Befehl “Status”: Signaturgenerierung (Prüfung anhand der Transaktions-ID in Ihrem System)

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

Zeile:

statusxsollaid215120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (Beispiel)

Befehl “Status”: Signaturgenerierung (Prüfung anhand der bei Xsolla hinterlegten Transaktions-ID)

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

Zeile:

status98765432115120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (Beispiel)

Befehl “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?>

Zeile:

calculate47831215120110117000516test

MD5:

e73e11a9cad00e205358e05254905af5

Antworten

Antwortcodes

Xsolla generiert ein XML mit dem Statuscode in result und der Beschreibung in comment.

Antwort mit Fehlermeldung (Beispiel):

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

Erfolgreiche Antwortcodes

Wird in result der Wert 0 zurückgegeben, enthält die Antwort zudem den Block payment mit detaillierten Informationen zur Zahlung. Der Zahlungsstatus wird als Code im Parameter status übermittelt.

Erfolgreiche Antwort auf den Befehl “Status” (Beispiel):

 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 für das Zahlungssystem-Transaktionsregister

Das Dokument ist für Entwickler bestimmt, die die API für das Transaktionsregister des Zahlungssystems nutzen möchten, um Benutzern die Möglichkeit zu bieten, für virtuelle Gegenstände und Dienste des Projekts zu bezahlen. Das Dokument setzt grundlegende Kenntnisse über APIs, HTTP-Anfragen und Softwarearchitektur voraus.

Interaktion mit der API

• Die Zusammenarbeit erfolgt ausschließlich nach dem Schema der Server-zu-Server-Integration;

• Sämtliche Parameter sollten in UTF-8-Codierung vorliegen;

• Die Daten werden im CSV-Format zurückgegeben.

Beschreibung der API-Methoden

• Get – Zahlungsdaten abrufen.

API-URL

Basic-URL: https://api.xsolla.com/payments/

URL-Maske

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

Abrufen

Erstellt eine Anfrage zum Abruf von Zahlungsdaten der letzten 24 Stunden aus allen Zahlungssystemen der jeweiligen Gegenpartei.

API-Zugriff erhalten

Um Zugriff auf die API zu erhalten, müsse Sie sich an Ihren Customer Success Manager wenden oder eine E-Mail an [email protected] senden und eine individuelle Partner-ID sowie einen geheimen Schlüssel beantragen.

Beispielanfrage

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

Eingabeparameter

Antwort

Die Antwort erfolgt im csv-Format (Komma “,” fungiert als Trennzeichen):

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

Feldbeschreibung:

Signatur generieren

Die Parameter sind in alphabetischer Reihenfolge nach Schlüsseln sortiert. Die Signatur wird mit Hilfe des MD5-Hash-Algorithmus aus dem String gebildet, der aus der Verknüpfung der Parameterwerte und dem geheimen Schlüssel resultiert (Sie können den geheimen Schlüssel bei Ihrem Account Manager in Erfahrung bringen). Als Trennzeichen kommt “|” zum Einsatz.

Beispielanfrage

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

Der String sieht folgendermaßen aus:

2013-08-20|1234|password

MD5 des oben dargestellten Strings:

e8df0ff2e4360300a5142cc28d86b422

Liste der Abschlusscodes

Transaktionsabgleich mit den Zahlungssystemen

Abgleich per E-Mail-Benachrichtigung

Der Transaktionsabgleich basiert darauf, dass das Zahlungssystem eine E-Mail mit einem Anhang in einem bestimmten Format versendet. Die Abgleich-Häufigkeit muss im Voraus vereinbart werden.

Format des Abgleichsdokuments

Format des Abgleichdokuments:

• UTF8-Codierung
• CSV-Format (Komma oder Semikolon fungieren als Trennzeichen)
• Gesendet von einer vorher vereinbarten E-Mail-Adresse an [email protected]
• Betreffzeile der E-Mail: “stats registry”
• Name der angehängten Datei: stats_registry_period. Zeitraum: 2 Datumsangaben gemäß folgendem Format JJJJ-MM-TT: start_dateTend_date. Beträgt der Zeitraum lediglich einen Tag (24 Stunden), kann der Abschnitt ab “T” weggelassen werden

Dokumentinhalt

Register (Beispiel)

Beispiel 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]

Beispiel 2 (falls keine pid-Parameter Im Zahlungssystem vorhanden ist)

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]

Beispiel 3 (falls kein desc-Parameter vorhanden ist. Bitte beachten Sie das Semikolon am Ende)

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;

Abgleich über die Zahlungssystem-API

Der Transaktionsabgleich kann außerdem durch den Einsatz der HTTP-/HTTPS-API des Zahlungssystems erfolgen. Nach Abfrage der API muss Xsolla folgende Parameter erhalten: