Cash Kiosks API v2.0

API do catálogo de jogos

A API foi projetada para fornecer um catálogo de jogos, ou seja, a lista de todos os projetos disponíveis no sistema da Xsolla. A API retorna informações básicas sobre cada projeto, como o nome do projeto, Ícone do projeto, parâmetros de pagamento, etc. Essas informações podem ser usadas para criar páginas de pagamento para os projetos.

A API do catálogo de jogos pode ser útil para pagamentos via quiosques de dinheiro e para colocar os chamados “botões de jogo” em suas interfaces. Substituir o botão padrão da Xsolla por um “botão de jogo” na tela do quiosque permite que os usuários façam pagamentos em seus projetos favoritos de forma simples e familiar.

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

Formato da requisição

Parâmetros da requisição para obter a lista de jogos

Geração da assinatura

A assinatura garante a segurança na verificação e na execução de pagamentos. Ela é criada aplicando MD5 a uma string que concatena os parâmetros acima, separados por “|”, na ordem mostrada abaixo.

1md5(<ID>|<secret_key>)

secret_key: chave secreta da contraparte.

Exemplo: a assinatura para a contraparte #184 com a chave secreta “SecretKey” é formada assim:

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

Exemplo de solicitação:

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

Formato da resposta

A resposta vem em formato XML e contém a lista de jogos e informações básicas sobre cada jogo. O XML tem a seguinte estrutura:

 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>

Descrição dos campos

Formato da resposta em caso de erro

Em caso de erro, a API responde com uma mensagem em XML.

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

Descrição do erro

Interação com o agente

Visão geral

Há duas opções de interação:

• Botão da Xsolla. Esse botão é colocado no lado do agente. Após clicar no botão, o usuário é solicitado a informar um número que recebeu anteriormente e efetuar o pagamento para esse número. Para habilitar pagamentos via o botão da Xsolla, preencha o campo account (os campos project, v1, v2, v3 devem ficar vazios). O campo account deve conter o número Xsolla de 9 dígitos. Para configurar um botão da Xsolla, entre em contato com o gerente para obter um logotipo e o número.

• Botões de jogo. Esses botões são colocados no lado do agente, cada um correspondente a um jogo diferente. O usuário seleciona o botão de um jogo específico e faz login para efetuar o pagamento para a própria conta. Para habilitar pagamentos via botões específicos por jogo, preencha os campos project, v1, v2 e v3 (deixe o campo account vazio). Você poderá enviar os campos project, v1, v2 e v3 após o botão do projeto (jogo) específico ser configurado no terminal. Os campos project e v1 são obrigatórios, enquanto v2 e v3 são opcionais e dependem de cada projeto. Para configurar os botões de jogo, entre em contato com o gerente para obter os logotipos dos jogos, os IDs internos dos jogos e os métodos de Autorização (regras de preenchimento dos campos v1, v2, v3), além de outras informações de cada jogo.

Um botão é um elemento do sistema do agente que inicia um pagamento pelo sistema da Xsolla.

Antes de conectar o agente ao sistema da Xsolla, verifique o seguinte:

1. Número de Parceiro (type) no sistema da Xsolla. Você pode obtê-lo entrando em contato com seu Gerente de Sucesso do Cliente na Xsolla.
2. secret_key, um parâmetro confidencial do tipo string necessário para gerar a assinatura digital (string MD5). Você encontra esse valor na Conta de Distribuidor por meio do seu Gerente de Sucesso do Cliente.

Você pode interagir com a API enviando solicitações HTTP para o gateway da API em:

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

A API aceita solicitações GET ou POST. Todos os parâmetros devem ter a codificação UTF-8, pois qualquer codificação não correspondente resultará em problemas na assinatura.

Formato da requisição

As requisições para a Xsolla podem ser feitas nos seguintes casos:

• verificar se o pagamento é possível (command = check)
• efetuar um pagamento (command = pay)
• verificar se o pagamento foi bem-sucedido (command = status)
• calcular o custo e a quantidade de moeda do jogo (command = calculate)

Comando de verificação

Comando de verificação: identificar usuário pelo número Xsolla

Comando de verificação: identificar usuário por projeto/v1/v2/v3

Comando de pagamento

Comando de pagamento: identificar usuário por conta

Comando de pagamento: identificar usuário por projeto/v1/v2/v3

Comando de status

Você pode verificar se o pagamento foi bem-sucedido pelo ID da transação no seu sistema (o parâmetro id), ou pelo ID da transação no lado da Xsolla (o parâmetro invoice). Se você passar ambos os parâmetros, eles devem pertencer ao mesmo pagamento; caso contrário, a Xsolla retorna um erro de validação.

Comando de status: verificar sucesso do pagamento pelo ID da transação no seu sistema

Exemplo:

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

Comando de status: verificar sucesso do pagamento pelo ID da transação no lado da Xsolla

Exemplo:

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

Comando de cáclulo

Geração do campo MD5

A assinatura garante a segurança dos pagamentos e das verificações de pagamento. Ela é gerada calculando o hash MD5 de uma string obtida pela concatenação dos valores de todos os parâmetros transmitidos, na mesma ordem em que aparecem na solicitação, incluindo os parâmetros opcionais, se houver, e a chave privada do sistema de pagamento, que você obtém com seu Gerente de Sucesso do Cliente da Xsolla.

Comando de verificação

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

Linha:

check1234567150.7515120110117000516test

MD5:

1cad5a2c3457cffa8e857a507a7050ba

Comando de pagamento

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

Linha:

pay1234567150.7538495715120110117000516test

MD5:

7cfa05abde4ae2464142bf2ac7a72f32

Geração da assinatura do comando de status (verificação pelo ID da transação no seu 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);

Linha:

statusxsollaid215120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (exemplo)

Geração da assinatura do comando de status (verificação pelo ID da transação no lado da 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);

Linha:

status98765432115120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (exemplo)

Comando de cálculo

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

Linha:

calculate47831215120110117000516test

MD5:

e73e11a9cad00e205358e05254905af5

Respostas

Códigos de resposta

A Xsolla gera um XML contendo o código do status em result e a descrição em comment.

Exemplo de resposta contendo erro:

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

Códigos de resposta de sucesso

Se 0 for retornado em result, a resposta também contém o bloco payment com informações detalhadas sobre o pagamento. O status do pagamento é enviado no código no parâmetro status.

Exemplo de resposta bem-sucedida ao 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 de registro de transações do sistema de pagamento

Este documento é destinado a desenvolvedores que desejam usar a API do registro de transações do sistema de pagamento para permitir que seus usuários paguem por itens virtuais e serviços de seus projetos. O documento pressupõe conhecimento básico de APIs, solicitações HTTP e arquiteturas de software.

Interagindo com a API

• O funcionamento só é possível por integração servidor-servidor.

• Todos os parâmetros devem estar codificados em UTF-8;

• Os dados são retornados em formato CSV.

Descrição dos métodos API

• Get – recebe dados de pagamento.

URL da API

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

Máscara de URL

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

Obter

Cria uma solicitação para obter dados de pagamentos de todos os sistemas de pagamento da contraparte informada nas últimas 24 horas.

Obtendo acesso à API

Para obter acesso à API, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para [email protected] para receber um ID exclusivo de parceiro e a chave secreta.

Exemplo de requisição

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

Parâmetros de entrada

Resposta

A resposta é fornecida no formato CSV, usando “,” como separador:

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

Descrição dos campos:

Geração da assinatura

Os parâmetros são ordenados alfabeticamente pelas chaves. A assinatura é um hash MD5 de uma string formada pela concatenação dos valores dos parâmetros e da Chave Secreta (que você obtém com seu Gerente de Sucesso do Cliente). O separador é “|”.

Exemplo de requisição

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

A string fica assim:

2013-08-20|1234|password

MD5 da string acima:

e8df0ff2e4360300a5142cc28d86b422

Lista de códigos de conclusão

Conciliação de transações com sistemas de pagamento

Conciliação via notificação por e-mail

A conciliação de transações consiste no envio, pelo sistema de pagamento, de um e-mail com um anexo em um formato específico. A frequência da conciliação deve ser acordada previamente.

Formato do documento de conciliação

O documento de conciliação tem o seguinte formato:

• codificação UTF-8
• formato CSV (vírgula ou ponto e vírgula como delimitador)
• enviado de um e-mail previamente acordado para [email protected]
• assunto do e-mail: “stats registry”
• nome do arquivo em anexo: stats_registry_period, em que o período é definido por start_dateTend_date no formato YYYY-MM-DD. Se o período for de um dia (24 horas), a parte a partir de T pode ser omitida

Conteúdo do documento

Exemplo de registro

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

Exemplo 2 (se não houver pid no sistema de pagamento)

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]

Exemplo 3 (se não houver desc — observe o ponto e vírgula no 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;

Conciliação via API do sistema de pagamento

A conciliação de transações também pode ser feita pela API HTTP (HTTPS) do Sistema de Pagamento. Após consultar a API, a Xsolla deve receber os seguintes parâmetros: