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:

Implemente o mecanismo postMessage para receber eventos da interface de pagamento.
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

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

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

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:

Abra a Conta de Distribuidor.
Vá para a seção Pay Station > Settings.
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 precisa ser único para cada pagamento de usuário entre ambos os ambientes de teste (modo sandbox) e ativo. Exemplo: se você tem um pagamento de teste com “external_id”: “1”, você não tem como fazer um pagamento real com “external_id”: “1”.

Para habilitar o ID Externo em seu projeto:

Abra seu projeto na Conta de Distribuidor e vá para a seção Pay Station > Settings.
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

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

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:

Para abrir a interface de pagamento no modo sandbox, siga o link: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, onde ACCESS_TOKEN é o token recebido.
Para fazer pagamentos reais, siga o link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, onde ACCESS_TOKEN é o token recebido.

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.

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.

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.