Início rápido

Fluxo de integração

Para integrar a solução Payments:

Crie uym projeto na Conta de Distribuidor. Cada projeto corresponde a um jogo. Se você tiver diversos jogos, adicione um projeto para cada jogo.
Adicione os itens que você quiser vender a um catálogo no lado da Xsolla.
Teste a criação de um pedido que o usuário pagará.
Teste o pagamento de uma compra e configure notificações.
Assine o contrato de licenciamento com a Xsolla na Conta de Distribuidor para começar a processar pagamentos reais.

Você pode assinar o contrato de licenciamento em qualquer etapa da integração, mas tenha em mente que o processo de análise pode levar até 3 dias úteis.

Criar catálogo

Os itens virtuais são conteúdos de jogo que um usuário pode comprar com moedas reais e virtuais. Crie um catálogo de itens virtuais do lado da Xsolla para personalizar os preços e restrições regionais, bem como usar o sistema de promoções e outros recursos da Xsolla que são regularmente adicionados e atualizados.

Criar itens virtuais

Obter lista de itens

Para obter a lista de itens, chame o método API Obter lista de itens virtuais:

No cabeçalho da solicitação, passe o Xsolla Login JWT (Bearer token) usado para a autorização por padrão. Para testar esse método de chamada API, você pode usar o seguinte token de teste: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI.
No parâmetro do trajeto project_id, passe o ID do projeto que você pode encontrar na Conta de Distribuidor:

Na resposta, você receberá informações detalhadas sobre itens virtuais criados em seu projeto. Para a criação subsequente do pedido, você precisa do SKU do item que é passado no parâmetro items.sku.

Criar pedido

Um pedido consiste de itens que um usuário deseja comprar na loja. Depois que um pedido é pago, o usuário recebe os itens. Para fazer um pagamento, o usuário deve ser autorizado no jogo.

Selecione um método de integração adequado ao seu jogo para ver as instruções de configuração.

Características	Lado do servidor	Lado do cliente
Tendo um servidor	Você precisa ter seu próprio servidor para obter tokens e controlar a carga no servidor.	Você não precisa ter seu próprio servidor.
Determinação do país do usuário	Você precisa passar o país ou endereço IP no token de pagamento. Isso influencia a disponibilidade dos métodos de pagamento.	A Xsolla determina o país do usuário através do endereço IP.
Determinação da moeda de pagamento	Se você não passar a moeda no token, ela será determinada pelo país do usuário. Se você passar a moeda no token, o usuário pagará nessa moeda.	A moeda é determinada pelo país.

Chame o método de API Create payment token for purchase e passe as informações sobre um usuário e itens nesse método. Você pode usar essa chamada de API para vender um único item ou vários itens.

Para usar o modo sandbox, passe o parâmetro “sandbox”: true no corpo da solicitação para obter um token.

O valor do parâmetro user_id:

Ao testar, você pode passar qualquer símbolo nesse parâmetro.
Para aceitar pagamentos reais, passe o ID do usuário do seu sistema nesse parâmetro. Esse ID é passado no webhook Validação do usuário.

Exemplo de solicitação:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Integre o Xsolla Login:

Usando o método Login configurado, crie e salve o token de autenticação para receber um token de pagamento. O token de pagamento é usado para abrir a interface de pagamento e fazer o pagamento.

Para testar o fluxo de pagamento, crie um pedido usando a chamada de API Create order with specified item:

Se você quiser executar um teste no site de documentação da API, clique em Try it para abrir a interface e criar uma solicitação.
No bloco Security, no campo Bearer Token, insira o token obtido ao passar o procedimento de autenticação.
No bloco Body, envie detalhes do pedido, como a quantidade de itens. Para acessar o modo sandbox, passe "sandbox": true.
No bloco Parameters, passe:
- project_id — ID do projeto que você pode encontrar na Conta de Distribuidor.
- item_sku — SKU do item.

Na resposta, você receberá os dados necessários para trabalhos mais avançados:

token — ficha de pagamento

Exemplo de solicitação:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Para chamar a API Xsolla, você pode usar os métodos SDK prontos para engines e plataformas de jogos:

Efetuar teste de pagamento

O teste não requer o saque de dinheiro de contas bancárias reais. Você pode usar um dos nossos cartões de teste.

Antes de assinar um contrato com a Xsolla, o teste do processo de pagamento só fica disponível no modo sandbox.

Abra a interface de pagamento no modo sandbox

Para abrir a interface de pagamento em uma nova janela, use o seguinte URL: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, onde TOKEN é o token obtido ao criar um pedido.

Para abrir a interface de pagamento usando outros métodos, consulte a documentação.

Pagamentos de teste

Abra a interface de pagamento no modo sandbox.
Escolha o método de pagamento Cartão do banco.
Insira os dados do cartão bancário. Nos outros campos (ex.: nome ou endereço), você pode inserir qualquer dado. Você também pode especificar detalhes incorretos (número do cartão ou data de validade) para testar se um erro é gerado.
Clique em Pay.

Lista de cartões de teste

Veja a lista de cartões bancários de teste.

Informações sobre CEPs

Além dos detalhes do cartão, você precisa especificar o CEP se pelo menos uma das seguintes condições for verdadeira:

O país do usuário for os EUA ou Canadá.
O Número de Identificação Bancária (BIN) indica que um cartão foi emitido nos EUA.

Você pode especificar qualquer CEP válido (por exemplo, 12345). Isso determina a taxa de imposto sobre vendas e não afeta o andamento do pagamento do teste.
Os pagamentos com cartão bancário no modo sandbox podem ser feitos nas seguintes moedas: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

No modo sandbox, você pode testar um pagamento único e um pagamento com métodos de pagamento salvos usando cartões bancários e o PayPal.

Configurar webhooks

Se você configurar a integração no lado do servidor, você precisará validar os pedidos criados enviando o respectivo código em resposta aos webhooks. Se você configurar a integração do lado do cliente, os webhooks permitirão que você receba notificações sobre os eventos configurados (ex.: alteração do status de pagamento).

Para habilitar o recebimento de webhooks:

Abra seu projeto na Conta de Distribuidor.
Clique em Project settings no menu lateral e vá para a aba Webhooks.
No campo Webhook server, especifique o URL do seu servidor onde deseja receber os webhooks no formato https://example.com. Você também pode especificar o URL que você encontra em uma ferramenta para testar webhooks.
É gerada uma chave secreta para assinar webhooks de projeto por padrão. Se desejar gerar uma nova chave secreta, clique no ícone de atualização.
Clique em Enable webhooks.

PHP SDK

Utiliza classes prontas para o processamento de webhooks.

Para testar webhooks, você pode selecionar qualquer site dedicado, tal como webhook.site, ou uma plataforma, tal como ngrok.

Para receber notificações sobre a validação de usuários e pagamentos bem-sucedidos, configure os seguintes webhooks:

Validação do usuário — para que as notificações garantam que o usuário está cadastrado no jogo.
Pagamento — para as notificações sobre a execução do pagamento.

Consulte a documentação para obter informações detalhadas sobre como configurar e testar webhooks.

Configuração do ouvinte de webhooks

O ouvinte de webhooks é um código de programa que permite receber webhooks de entrada em um endereço URL especificado, ao gerar uma assinatura e ao enviar uma resposta para o servidor webhook da Xsolla.

Informações sobre geração de assinaturas e envio de respostas para webhook

Geração de assinatura

Ao receber um webhook, você deve garantir a segurança da transmissão de dados. Para fazer isso, você deve gerar uma assinatura a partir dos dados do webhook e verificar se ela corresponde à assinatura enviada no cabeçalho da solicitação HTTP. Para gerar uma assinatura:

Concatene o JSON do corpo da solicitação e da chave secreta do projeto.
Aplique a função de hash criptográfico SHA-1 à cadeia de caracteres obtida na primeira etapa.

Enviando respostas ao webhook

Para confirmar o recebimento do webhook, seu servidor deve retornar:

O código HTTP 200, 201 ou 204 no caso de uma resposta bem-sucedida.
O código HTTP 400 com uma descrição do problema se o usuário especificado não for encontrado ou uma assinatura inválida for passada.

Seu manipulador de webhook também pode retornar um código 5xx em caso de problemas temporários em seu servidor. Se uma resposta não foi recebida para os webhooks Successful payment of the order e Order cancellation, ou se uma resposta com um código 5xx for recebida, os webhooks são reenviados de acordo com o seguinte cronograma:

2 tentativas com um intervalo de 5 minutos
7 tentativas com um intervalo de 15 minutos
10 tentativas com intervalo de 60 minutos

No máximo 20 tentativas de envio de webhooks são feitas dentro de 12 horas a partir da primeira tentativa. Se uma resposta não for recebida pelo webhook Pagamento ou se uma resposta com um código 5xx for recebida, os webhooks também são reenviados com um intervalo de tempo maior. São feitas 12 tentativas no máximo dentro de 12 horas. Se uma resposta não for recebida pelo webhook Validação do usuário ou for recebida uma resposta com um código 400 ou 5xx, o webhook Validação do usuário não é reenviado. Nesse caso, um erro é exibido ao usuário e os webhooks Pagamento e Successful payment of the order não são enviados.

Iniciar

Antes de assinar o contrato de licenciamento, você só pode abrir a interface de pagamento no modo sandbox.

Assine o contrato de licenciamento

A assinatura do contrato de licenciamento permitirá que você receba pagamentos reais através de quaisquer métodos de pagamento suportados pela Xsolla. Para assinar o contrato de licenciamento:

Abra sua Conta de Distribuidor.
No menu lateral, vá para a seção Agreements and taxes > Agreements.
Na guia Licensing Agreement, clique em Fill out application form.
Forneça suas informações nos campos correspondentes.

Seu pedido será analisado em até 3 dias úteis. Se houver alguma dúvida durante o processo de verificação, a Xsolla notificará a pessoa de contato indicada na inscrição. Depois que o procedimento de verificação for concluído do lado da Xsolla, o status do seu contrato mudará para Signed.

Troque para o ambiente de produção

Depois que o primeiro pagamento real é feito, uma política rigorosa de pagamento sandbox entra em vigor. Os pagamentos feitos no modo sandbox estão disponíveis apenas para usuários especificados na Conta de Distribuidor na seção Company settings > Users.

Depois de concluir as etapas anteriores, você pode começar a receber pagamentos reais:

Certifique-se de que você assinou o contrato de licenciamento com a Xsolla.
Remova o parâmetro “sandbox”: true do corpo da solicitação ao obter um token.
Abra a interface de pagamento usando o seguinte link: https://secure.xsolla.com/paystation4/?token=TOKEN.

Este guia descreve as configurações mínimas necessárias para iniciar rapidamente a integração. Se você tiver alguma dúvida, entre em contato conosco via Xsolla Chat no canto inferior direito da página ou envie um e-mail para um Gerente de Sucesso do Cliente pelo endereço csm@xsolla.com.

Obrigado pelo seu feedback!

Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.

Avalie esta página

Não quero responder

Obrigado pelo seu feedback!

Última atualização: 18 de Março de 2024

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Your browser is not supported. Please try a different browser

Payments

Início rápido

Fluxo de integração

Criar catálogo

Criar itens virtuais

Obter lista de itens

Criar pedido

Efetuar teste de pagamento

Abra a interface de pagamento no modo sandbox

Pagamentos de teste

Configurar webhooks

Configuração do ouvinte de webhooks

Geração de assinatura

Enviando respostas ao webhook

Iniciar

Assine o contrato de licenciamento

Troque para o ambiente de produção

Este artigo foi útil?

Avalie esta página

Obrigado pelo seu feedback!