Automaten-API v2.0

Spielkatalog-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 für den Abruf der Spielliste

Generierung der Signatur

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>

Feldbeschreibung

Antwortformat bei einem Fehler

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öglichkeiten der Interaktion:

• Xsolla-Schaltfläche: Diese Schaltfläche wird auf Seiten des Agenten platziert. Nach Betätigung der Schaltfläche wird der Nutzer aufgefordert, eine zuvor erhaltene Nummer einzugeben und die Zahlung vorzunehmen. Um das Bezahlen über die Xsolla-Schaltfäche zu ermöglichen, müssen Sie das Feld account auszufüllen (die Felder project, “v1”, “v2”, “v3” müssen leer bleiben). Das Feld account muss die 9-stellige Xsolla-Nummer enthalten. Wenden Sie sich zur Einrichtung einer Xsolla-Schaltfläche an Ihren Account Manager, um ein Logo und eine Nummer zu erhalten.
• Schaltflächen für Spiele: Diese Schaltflächen werden auf Seiten des Agenten platziert. Jede Schaltfläche repräsentiert ein bestimmtes Spiel. Der Nutzer klickt auf die Schaltfläche eines Spiels, meldet sich an und zahlt anschließend über sein Konto. Um das Bezahlen über spielspezisfische Schaltflächen zu ermöglichen, müssen Sie die Felder project, “v1”, “v2” und “v3” auszufüllen (das Feld account muss leer bleiben). Sie können die Felder “Projekt”, “v1”, “v2” und “v3” senden, nachdem die jeweilige Projekt-/Spiel-Schaltfläche am Automaten konfiguriert wurde. Bei project und “v1” handelt es sich um Pflichtfelder, während “v2” und “v3” wahlweise ausgefüllt werden können und vom konkreten Projekt abhängen. Wenden Sie sich zur Einrichtung der Spiel-Schaltflächen an den Account Manager, um Logos & interne IDs der Spiele, Autorisierungsmethoden (Richtlinien zum Ausfüllen der Felder “v1”, “v2”, “v3”) und weitere Informationen zum jeweiligen 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

Das Xsolla-Gateway akzeptiert drei Arten von Anfragen:

• Prüfen, ob Zahlung möglich ist (command = check)
• Zahlung leisten (command = pay)
• Berechnung der Kosten und des Betrages der Spielwährung (command = calculate)

Befehl Check: Benutzeridentifikation anhand der Xsolla-Nummer

Befehl Check: Benutzeridentifikation anhand von Project/v1/v2/v3

Befehl Pay: Abonnentenidentifikation anhand des Kontos

Befehl Pay: Abonnentenidentifikation über Project/v1/v2/v3

Befehl Calculate

Generierung des MD5-Felds

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

Statuscodes

Das System generiert ein XML mit dem Statuscode in result und dessen Beschreibung unter comment.

API für das Transaktionsregister des Zahlungssystems

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.

Zusammenspiel 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

Get

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 csm@xsolla.com senden und eine individuelle Partner-ID sowie einen geheimen Schlüssel beantragen.

Beispiel einer Anfrage

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

Eingangsparameter

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:

Generierung der Signatur

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.

Beispiel einer Anfrage

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 Zahlungssystemen

Abgleich via 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 Abgleichdokuments

Format des Abgleichdokuments:

• UTF8-Codierung
• CSV-Format (Komma oder Semikolon fungieren als Trennzeichen)
• Gesendet von einer vorher vereinbarten E-Mail-Adresse an stats@xsolla.com
• 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

Dokumenteninhalt

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;vassilliy@mail.ru

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;vassilliy@mail.ru

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 API des Zahlungssystems

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