Cash Kiosks API v2.0

API del catálogo de juegos

La API está diseñada para proporcionar un catálogo de juegos, es decir, la lista de todos los proyectos disponibles en el sistema de Xsolla. La API proporciona información básica sobre cada proyecto, como el nombre y el icono del proyecto, los parámetros de pago, etc. Esta información puede usarse para crear páginas de pago para los proyectos.

La API del catálogo de juegos puede resultar útil para pagar en terminales de pago en efectivo y para incluir los llamados “botones de juego” en la interfaz de dichos terminales. Sustituir el botón habitual de Xsolla por un “botón de juego” en la pantalla de un terminal de pago en efectivo permite a los usuarios pagar en sus proyectos favoritos de forma sencilla.

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

Formato de la solicitud

Parámetros de solicitud para obtener la lista de juegos

Generar la firma

La firma garantiza la seguridad al comprobar y realizar pagos. Se genera calculando el hash MD5 de una cadena formada por la concatenación de los parámetros anteriores, separados por “|”, en el orden que se indica a continuación.

1md5(<ID>|<secret_key>)

secret_key: clave secreta de la contraparte.

Ejemplo: La firma de la contraparte #184 con la clave secreta “SecretKey” se forma de la siguiente manera:

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

Ejemplo de solicitud:

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

Formato de la respuesta

La respuesta está en formato XML y contiene tanto la lista de juegos como información básica sobre cada juego. El XML tiene la siguiente estructura:

 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>

Descripción de los campos

Formato de la respuesta en caso de error

En caso de error, la API responde con un mensaje XML.

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

Descripción de errores

Interacción con el agente

Descripción general

Hay dos opciones de interacción:

• Botón de Xsolla. Este botón se coloca en la interfaz del agente. Tras pulsarlo, se solicita al usuario que introduzca un número que recibió previamente y que pague a ese número. Para habilitar los pagos mediante el botón de Xsolla, rellene el campo account (los campos project, v1, v2, v3 deben permanecer vacíos). El campo account debe contener el número de Xsolla de 9 dígitos. Para configurar un botón de Xsolla, contacte con el gestor para obtener un logotipo y el número.

• Botones de juego. Estos botones se colocan en la interfaz del agente y cada uno corresponde a un juego distinto. El usuario pulsa el botón de un juego en particular y, a continuación, inicia sesión para pagar en su propia cuenta. Para habilitar pagos mediante botones específicos de juego, rellene los campos project, v1, v2 y v3 (deje vacío el campo account). Podrá enviar los campos project, v1, v2 y v3 una vez configurado el botón del proyecto (juego) en el terminal. Los campos project y v1 son obligatorios, mientras que v2 y v3 son opcionales y dependen de cada proyecto. Para configurar botones de juego, contacte con el gestor para obtener los logotipos de los juegos, los ID internos de los juegos y los métodos de autorización (reglas para rellenar los campos v1, v2, v3) y otra información para cada juego.

Un botón es un elemento del sistema del agente que inicia un pago mediante el sistema de Xsolla.

Antes de conectar el agente al sistema de Xsolla, asegúrese de confirmar lo siguiente:

1. Número de socio (type) en el sistema de Xsolla. Puede obtenerlo poniéndose en contacto con su gestor de éxito del cliente de Xsolla.
2. secret_key, un parámetro de cadena confidencial que se necesita para generar la firma digital (cadena MD5). Puede obtenerlo en Cuenta del editor a través de su gestor de éxito del cliente.

Puede interactuar con la API enviando solicitudes HTTP a la pasarela de la API en la siguiente dirección:

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

La API acepta solicitudes GET o POST. Todos los parámetros deben estar codificados en UTF-8, ya que usar una codificación distinta provoca problemas con la firma.

Formato de la solicitud

Puede enviar solicitudes a Xsolla para:

• comprobar si el pago es posible (command = check)
• pagar (command = pay)
• comprobar si el pago se ha realizado correctamente (command = status)
• calcular el coste y la cantidad de moneda del juego (command = calculate)

Comando check

Comando check: identificación del usuario por número de Xsolla

Comando check: identificación del usuario por project/v1/v2/v3

Comando pay

Comando pay: identificación del suscriptor por número de Xsolla

Comando pay: identificación del suscriptor por project/v1/v2/v3

Comando status

Puede comprobar si el pago se ha realizado correctamente mediante el ID de transacción en su sistema (el parámetro id) o mediante el ID de transacción en el sistema de Xsolla (el parámetro invoice). Si transmite ambos parámetros, deben pertenecer al mismo pago; de lo contrario, Xsolla devuelve un error de validación.

Comando status: comprobación del pago por ID de transacción en su sistema

Ejemplo:

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

Comando status: comprobación del pago por ID de transacción en el sistema de Xsolla

Ejemplo:

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

Comando calculate

Generar el campo MD5

La firma garantiza la seguridad de los pagos y de las comprobaciones de pago. Se genera calculando el hash MD5 de una cadena obtenida al concatenar los valores de todos los parámetros transmitidos, en el mismo orden en que aparecen en la solicitud (incluidos los parámetros opcionales, si los hay), y la clave privada del sistema de pago, que puede obtener a través de su gestor de éxito del cliente de Xsolla.

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

Cadena:

check1234567150.7515120110117000516test

MD5:

1cad5a2c3457cffa8e857a507a7050ba

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

Cadena:

pay1234567150.7538495715120110117000516test

MD5:

7cfa05abde4ae2464142bf2ac7a72f32

Generar la firma del comando status (comprobación por ID de transacción en su sistema)

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

Cadena:

statusxsollaid215120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (ejemplo)

Generar la firma del comando status (comprobación por ID de transacción en el sistema de 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);

Cadena:

status98765432115120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (ejemplo)

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

Cadena:

calculate47831215120110117000516test

MD5:

e73e11a9cad00e205358e05254905af5

Respuestas

Códigos de respuesta

Xsolla genera un XML que contiene el código de estado en result y la descripción en comment.

Ejemplo de respuesta con error:

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

Códigos de respuesta correcta

Si en result se devuelve 0, la respuesta también contiene el bloque payment con información detallada sobre el pago. El estado del pago se transmite como código en el parámetro status.

Ejemplo de respuesta correcta al comando 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 del registro de transacciones del sistema de pago

Este documento está dirigido a desarrolladores que quieran usar la API del registro de transacciones del sistema de pago para permitir a sus usuarios pagar artículos virtuales y servicios de su proyecto. Se requieren conocimientos básicos de API, solicitudes HTTP y arquitecturas de software.

Interacción con la API

• La interacción solo es posible mediante una integración de servidor a servidor.

• Todos los parámetros deben estar codificados en UTF-8.

• Los datos se devuelven en formato CSV.

Descripción de las llamadas API

• Get: obtiene los datos de pago.

URL de la API

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

Máscara de la URL

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

Get

Crea una solicitud para obtener datos sobre los pagos realizados mediante todos los sistemas de pago de la contraparte indicada durante las últimas 24 horas.

Obtener acceso a la API

Para obtener acceso a la API, contacte con su gestor de éxito del cliente o envíe un correo a [email protected] para recibir un ID de socio único y una clave secreta.

Ejemplo de solicitud

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

Parámetros de entrada

Respuesta

La respuesta se proporciona en formato CSV, con “,” como separador:

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

Descripción de los campos:

Generar la firma

Los parámetros se ordenan alfabéticamente por nombre. La firma es el hash MD5 de una cadena formada por la concatenación de los valores de los parámetros y la clave secreta (puede obtenerla a través del gestor). El separador es “|”.

Ejemplo de solicitud

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

La cadena resultante es la siguiente:

2013-08-20|1234|password

MD5 de la cadena anterior:

e8df0ff2e4360300a5142cc28d86b422

Lista de códigos de finalización

Conciliación de transacciones con los sistemas de pago

Conciliación mediante notificación por correo electrónico

La conciliación de transacciones consiste en que el sistema de pago envíe un correo electrónico con un archivo adjunto en un formato determinado. La frecuencia de la conciliación debe acordarse con antelación.

Formato del documento de conciliación

El documento de conciliación tiene el siguiente formato:

• Codificación UTF-8.
• Formato CSV (con coma o punto y coma como delimitador).
• Enviado desde una dirección de correo electrónico acordada previamente a [email protected].
• Asunto del correo electrónico: “stats registry”.
• Nombre del archivo adjunto: stats_registry_period, donde period corresponde a start_dateTend_date en formato YYYY-MM-DD. Si el periodo es de un día (24 horas), puede omitirse la parte que va desde la T (incluida) en adelante.

Contenido del documento

Ejemplo de registro

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

Ejemplo 2 (si el sistema de pago no tiene 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]

Ejemplo 3 (si no hay desc, observe el punto y coma al 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;

Conciliación mediante la API del sistema de pago

La conciliación de transacciones también puede hacerse mediante la API del sistema de pago, por HTTP (HTTPS). Tras consultar la API, Xsolla debe recibir los siguientes parámetros: