Perguntas Frequentes

Integração

Como posso abrir o Pay Station em um iframe?

Recomendamos que você use o script Pay Station Embed para abrir a interface de pagamento em uma lightbox. O uso desse script permitirá:

  • determinar automaticamente o tamanho da interface de pagamento e o tipo de dispositivo (desktop, celular)
  • receber automaticamente eventos da interface de pagamento
  • alterar o tema da interface

Para abrir a interface de pagamento em um iframe:

  1. Implemente o mecanismo postMessage para receber eventos da interface de pagamento.
  2. Abra a interface de pagamento seguindo o link https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, onde TOKEN é o token recebido.

Problema em potencial: se um botão para copiar um código de confirmação de pagamento exigido por alguns sistemas de pagamento não for exibido ao abrir a interface de pagamento em um iframe, passe o atributo allow=“clipboard-read; clipboard-write; payment” ao iframe.

Exemplo:

Copy
Full screen
Small screen
  • html
<iframe
  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
  width="800"
  height="700"
  allow="clipboard-read; clipboard-write; payment"
></iframe>

Quais endereços IP da rede Xsolla preciso adicionar à lista de permissões para configurar webhooks?

Você precisa receber e processar webhooks dos seguintes endereços IP:

  • 185.30.20.0/24
  • 185.30.21.0/24
  • 185.30.23.0/24

Se você integrou o produto Login, adicione o processamento de webhooks a partir do seguinte endereço IP:

  • 35.236.32.131
  • 34.94.154.26
  • 34.94.14.95
  • 34.102.48.30
  • 34.94.115.185
  • 34.94.173.132
  • 35.236.35.100
  • 35.236.117.164
  • 34.94.0.85
  • 35.235.99.248
  • 34.94.25.33

Existe SDK para Node.JS/C#/Ruby/Java/ASP, etc.?

Atualmente existem SDKs para PHP e Android. Você pode criar seu próprio SDK usando qualquer linguagem/plataforma, desde que tenha funcionalidade de solicitação HTTPS.

Validação do usuário

O que é o ID de usuário?

O ID do usuário é um parâmetro que permite identificar um usuário em um jogo. Você pode armazenar IDs de usuário em um banco de dados. Ao receber IDs de usuário inválidos, lance uma exceção. Consulte o repositório do GitHub para obter um exemplo de validação do usuário.

Quais dados devo retornar após a conclusão da validação?

Quando a validação for bem-sucedida, retorne o código HTTP 200. Em caso de erro, o código 400 (INVALID_USER).

Configurações do projeto

Preciso criar novos projetos para cada ambiente (QA, staging, produção)?

Para testes, recomendamos que você use projetos separados para evitar afetar o ambiente de produção.

Qual é a diferença entre uma chave secreta, chave de projeto e chave de API?

Uma chave secreta e uma chave de projeto são as mesmas. Ele é usado para a assinatura digital que é necessária ao processar pagamentos seguros. O corpo JSON da solicitação é concatenado com essa chave e, em seguida, o resultado é hashed com SHA-1.

A chave de API é usada para chamadas de API enviadas ao servidor Xsolla. Essa chave deve ser mantida em seu próprio servidor e nunca dentro de arquivos binários ou frontend. Para obter mais informações sobre como trabalhar com chaves de API, consulte a referência de API.

Qual é a diferença entre um URL de webhook e um URL de retorno?

Um URL de webhook é o endereço URL do seu servidor webhook para onde as notificações são enviadas. Um URL de retorno é o endereço URL para o qual um usuário é redirecionado após concluir um pagamento.

Onde posso encontrar o ID do projeto?

Abra seu projeto na Conta de Distribuidor e vá para as configurações do Project settings > General settings.

Onde posso encontrar o ID do comerciante?

Abra a Conta de Distribuidor e vá para as configurações da Company settings > Company.

Observação
O ID do comerciante é o mesmo que o ID do distribuidor.

Onde posso encontrar a chave de API?

A API key é mostrada na Conta de Distribuidor apenas uma vez, durante a criação, e deve ser armazenada por você. Você pode criar uma nova chave na seguinte seção:

  • Company settings > API keys
  • Project settings > API keys

Aviso

Para obter mais informações sobre como trabalhar com chaves de API, consulte a Referência de API.

Principais recomendações:

  • Salve a chave de API gerada cuidadosamente. Você pode visualizar a chave de API na Conta de Distribuidor apenas uma vez, durante sua criação.
  • Mantenha sua chave de API em segredo. Ela fornece acesso à sua conta pessoal e aos seus projetos na Conta de Distribuidor.
  • A chave de API deve ser armazenada em seu servidor, e jamais em arquivos binários ou no frontend.

Se uma chamada de API que você precisa não contiver o trajeto-parâmetro project_id, use a chave de API que for válida em todos os projetos da empresa para configurar a autorização.

Configurações de webhook

Preciso usar HTTPS para um protocolo webhook?

Sim.

Por que a notificação Xsolla não foi enviada para o URL do webhook?

Certifique-se de que o servidor webhook suporta os tipos necessários de solicitações HTTP (POST, GET).

Por que os webhooks não são enviados para meu aplicativo móvel?

Os webhooks são enviados para apenas um único endereço URL especificado nas configurações do projeto. Sendo servidor para servidor, os webhooks não podem ser enviados para vários endereços URL. Se você gostaria de receber notificações em seu jogo, site ou aplicativo móvel, configure o envio de webhooks em seu servidor para passar dados entre a Xsolla e seu jogo.

Personalização

Posso personalizar o tema da interface de pagamento?

Você pode habilitar um tema escuro enviando o parâmetro settings.ui.theme = default_dark no token. O tema escuro permite que você defina a imagem de fundo ou altere a cor do plano de fundo (como é na demonstração). Para alterar outras configurações, entre em contato com o Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Posso alterar a aparência dos e-mails enviados aos usuários?

Sim. Siga as instruções sobre como personalizar e-mails para os usuários. A ordem dos elementos de e-mail não pode ser alterada, pois eles fazem parte de um modelo padrão. Isso é exigido de acordo com o contrato de licenciamento com a Xsolla, que atua como comerciante legal de registros.

Testes

Posso usar cartões de teste para testar o processo de pagamento?

Sim, mas somente quando você executa seu aplicativo ou a demonstração do Pay Station no modo sandbox. Consulte a lista geral de cartões de teste de diferentes marcas e países emissores.

Posso testar o fluxo de pagamento PayPal no modo sandbox?

Sim. Veja informações detalhadas na instrução.

Como posso testar os reembolsos de pagamento?

Você pode testar reembolsos por meio da chamada de API Solicitar reembolso. Consulte as instruções para obter mais informações.

O que é o Xsolla Invoice ID e o Invoice ID na aba de teste do webhook na Conta de Distribuidor?

O Xsolla Invoice ID é o ID da transação do lado Xsolla. Para testes, você pode usar qualquer valor numérico.

O Invoice ID é um ID de transação opcional no seu jogo. Para o teste, você pode inserir qualquer combinação de letras e números.

Payments

Como posso validar uma solicitação de pagamento recebida em um webhook?

Primeiro, verifique se existe um ID de usuário especificado em seu projeto. Em seguida, retorne o código 200 para validar o pagamento.

Posso redirecionar um usuário para uma forma de pagamento específica?

Ao abrir a interface da loja, você pode passar o ID da forma de pagamento no parâmetro settings.payment_method. Nesse caso, os usuários são redirecionados para a forma de pagamento do método de pagamento selecionado. Você pode encontrar a lista de IDs de forma de pagamento na Conta de Distribuidor na seção Pay Station > Payment methods.

Posso redirecionar automaticamente um usuário para uma página de pagamento bem-sucedida/falha após o processamento de um pagamento, dependendo do resultado?

Sim, você pode configurar condições de redirecionamento. Consulte as instruções para obter mais informações.

Nosso sistema de faturamento define automaticamente o order_id para cada pedido. Posso usar order_id em vez de user_id ao receber um token?

Não, você precisa user_id para tudo funcionar corretamente.

Você também pode passar o order_id no parâmetro external_id. Para fazer isso:

  1. Abra a Conta de Distribuidor.
  2. Vá para a seção Pay Station > Settings.
  3. No bloco Additional settings, defina a opção Transaction external ID como On.

Posso substituir o URL do webhook para cada transação?

Não, o URL do webhook para todas as transações é definido nas configurações do projeto na Conta de Distribuidor.

Receberei os detalhes das transações falhas?

Não, a Xsolla só envia webhooks para transações bem-sucedidas. Se você recebeu uma notificação sobre um pagamento, isso significa que a transação foi bem-sucedida.

Como posso adicionar o VAT ao valor total do pagamento?

As configurações de VAT são definidas no lado da Xsolla por padrão. Entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com se quiser alterar as configurações e adicionar o VAT ao valor total do pagamento de um usuário.

O que significa PID?

PID é o identificador do método de pagamento do lado da Xsolla.

O que é um ID Externo?

O ID Externo é o ID de uma transação no jogo que é atribuído a um pedido em seu sistema. No lado da Xsolla, o ID Externo está vinculada a um ID de transação. É por isso que um ID Externo habilitado permite que a Xsolla impeça pagamentos repetidos para a mesma transação. O ID Externo deve ser exclusivo para cada pagamento de usuário.

Para habilitar o ID Externo em seu projeto:

  1. Abra seu projeto na Conta de Distribuidor e vá para a seção Pay Station > Settings.
  2. Defina a opção Transaction external ID como On.

Preciso gerar um novo ID Externo para cada transação?

Sim. O ID Externo tem que ser exclusivo para cada pagamento.

Que valor preciso definir para o método setExternalPaymentId?

O método setExternalPaymentId deve ter o mesmo valor que o external_id, se você tiver um.

O que são os portais?

Depois de assinar um contrato com sistemas de pagamento, você pode usar portais para exibir essas opções de pagamento na interface de pagamento. Os jogadores ainda podem pagar por suas compras usando métodos de pagamento selecionados, e você receberia pagamentos diretamente desses provedores de sistema de pagamento. Para conectar portais, abra seu projeto na Conta de Distribuidor e vá para a seção Pay Station > Gateways.

A Xsolla atua como um provedor de serviços técnicos e tem uma participação de receita reduzida: 1,25% do valor da transação + US$ 0,10. Você terá acesso total a todas as soluções Xsolla, mas deve fazer o seguinte:

  • gerenciar questões relacionadas a impostos
  • assinar contratos separados com cada sistema de pagamento
  • reter o fluxo de dinheiro direto dos sistemas de pagamento
  • gerenciar taxas de sistema de pagamento, estornos, reembolsos, comissões de proventos e custos operacionais

Por exemplo, se você trabalha com PayPal e deseja defini-lo como uma forma de pagamento direto, você pode conectar um portal. A interface de pagamento não será alterada — as alterações afetarão apenas o processo de pagamento. Depois de processar um pagamento, o dinheiro de um jogador será transferido para a sua conta PayPal. Neste caso, a Xsolla não está envolvida no processo de pagamento de proventos.

Como posso migrar os dados do usuário (contas de pagamento salvas, assinaturas, etc.) para a Xsolla?

Entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com. Certifique-se de usar a criptografia PGP para fornecer segurança de dados.

Parâmetros-chave Xsolla PGP:

  • Key ID: FBA38225
  • Tipo de chave: RSA
  • Comprimento da chave: 4096
  • Assinatura digital: 4D63 4B67 B265 5464 D39D 7228 67B0 672A FBA3 8225
  • ID de usuário: admins@xsolla.com

Copy
Full screen
Small screen
  • html
-----BEGIN PGP PUBLIC KEY BLOCK-----
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
=7AyM
-----END PGP PUBLIC KEY BLOCK-----

Como é determinado o país de um usuário?

Ao usar a chamada de API do lado do cliente para gerar o token de pagamento, a Xsolla determina o país do usuário a partir do endereço IP da solicitação.

Ao utilizar a chamada de API do lado do servidor para gerar o token de pagamento, o país é determinado pela conferência sequencial de:

  • o valor do parâmetro user.country.value no corpo da solicitação
  • o endereço IP no cabeçalho X-User-Ip

Se nenhum desses valores for passado, aparecerá um erro. Se ambos esses valores forem passados, a informação do corpo de solicitação será utilizada.

Mensagens de erro

Observação
Consulte a documentação para obter mais informações sobre possíveis erros ao abrir a interface de pagamento.

O que devo fazer quando recebo o erro 0004-0008?

Confira se você usa os endereços URL corretos:

O que devo fazer quando recebo os erros 2205 ou 2207 (erro de ID de usuário)?

  • Passe um ID de usuário válido que seja user_id do seu banco de dados.
  • Recomendações sobre o uso de webhooks:
    • Se você não quiser usar webhooks, certifique-se de que eles estejam desativados em seu projeto. Para fazer isso, vá para a Conta de Distribuidor e, na seção Project settings > Webhooks, defina a opção como Off.
    • Se você quiser usar webhooks, implemente o processamento bem-sucedido do webhook Validação do usuário.

O que devo fazer quando recebo o erro 1000-0003?

Ative o respectivo módulo para o seu projeto.

O que devo fazer quando recebo o erro 0002-0004?

Assine o contrato de licenciamento com a Xsolla para receber os seus proventos. Se precisar de ajuda, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para onboarding@xsolla.com.

O que devo fazer quando recebo o erro 3032?

Envie informações sobre tokens de pagamento com erros ou IDs de usuário e IDs de projeto para a equipe de integração por meio de qualquer um dos canais de comunicação disponíveis.
Observação
Você pode encontrar o token de pagamento no endereço URL da interface de pagamento aberta. Se a interface de pagamento for aberta em um iframe, clique com o botão direito do mouse no iframe e selecione uma opção que permita visualizar a origem do iframe na lista suspensa.

Por que o cabeçalho Authorization está ausente da solicitação webhook?

Para corrigir esse erro, você precisa editar os arquivos Apache .htaccess ou httpd.conf. Consulte a documentação do SDK para obter mais informações.

Informações de contato

Se você não encontrou uma resposta para suas perguntas nas Perguntas Frequentes (FAQ), entre em contato conosco através de outros canais:
  • Clique no ícone de bate-papo no canto inferior direito e entre em contato com a equipe de integração por meio de um chat. Você receberá uma resposta em tempo real com a solução para o seu problema.
  • Envie um e-mail para integration@xsolla.com.
  • Entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.
  • Entre em contato com o especialista em integração via Basecamp.
Guia de integração do Atendimento ao Cliente (PDF)
Conheça as opções para integrar com nossa Equipe de Atendimento ao Cliente.
Este artigo foi útil?
Obrigado!
Podemos melhorar alguma coisa? Mensagem
Que pena ouvir isso
Explique porque este artigo não foi útil para você. Mensagem
Obrigado pelo seu feedback!
Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.
Última atualização: 30 de Agosto de 2024

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

Conteúdos
Relatar um problema
Nós sempre avaliamos nossos conteúdos. Seu feedback nos ajuda a melhorá-los.
Forneça um e-mail para que possamos responder
Obrigado pelo seu feedback!