Configuração de pagamentos

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

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 bancários 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 bancários 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 Payments > 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ê pode adicionalmente passar o order_id no parâmetro external_id. Para fazer isso:

1. Abra seu projeto dentro da Conta de Distribuidor e acesse a seção Project settings > Integration settings.
2. Marque a caixa Use external ID.
3. Selecione Save.

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?

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

1. Abra seu projeto dentro da Conta de Distribuidor e acesse a seção Project settings > Integration settings.
2. Na seção Payments, selecione a caixa de seleção necessária:
   • Use external ID — para tornar a validação do ID Externo obrigatória ao criar um token.
   • Skip verification for external ID — para desativar a validação do ID Externo ao criar um token.

3. Selecione Save.

Observação

Quando a configuração Use external ID está ativada, não é possível fazer um pagamento de teste pela Conta de Distribuidor. Para fazer um pagamento de teste com sucesso, desative essa configuração temporariamente.

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 Payments > Payments settings > 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: DA1E62CB
• Tipo de chave: RSA
• Comprimento da chave: 4096
• Assinatura digital: 0209 8489 757F 4451 F431 FB0C FBFC 4D97 DA1E 62CB
• ID de usuário: admins@xsolla.com

 1-----BEGIN PGP PUBLIC KEY BLOCK-----
 2
 3mQINBGnZA+8BEACtu+pO73jhG/5sjmkJRpMxftcQeNZRpB1QUMYYNcB6MFVuU3Oo
 4HO/hOuXWIbh1S5LWQOok5cY3eiQOKwjhwV/IpM0DJ5pxi5YlCAHwkSWO4b2J4lXF
 5pu27bb9whbaC+V1g1gE0TmLtiqKfX0QF6NZop4SrQ3f4yDoV50JKHGtW9XWL4Bfz
 6JWNyM9H4PFdzy5Pwhu5/642XSZf9MClpQzUjwPw+zSfxnweF6je3lbWvH+2fqBG/
 7Y1SeMuFW9Vo9QNCdBX9ws98CrS9bN3frXywh6B1cEEVoBbOvH/T3foKUmlr5gdHi
 8ijTKiFKHTsBcfHcaQgM1cCD0qrRCLrQ2j6KjJOjRevHLJLzdmZFiCDD11+eL338k
 9o4GVdoQR4aNeXfJEICN+79kwz/AVa6d8O934Nnfbz7e7Xx10KR/ObLt6Xnp57GmE
10zWqvtkJ/GGivCyyHR632Nb4yoj/lgf6s0Z0oTQ4Dx8u+as2T+OG+zNo4xRcU8fE2
11F2FBbYXtzp6ySrWu0YcOjS+YhH5tjJBz1dndEQ+FwfA9MWmQgNDuHfdub0CcQqb2
12AfipbGzU+cPucmiyown1WzqP824xmr2JOVJ28DD8CkuAtGQW+kGQqZzHohWgM5WS
13nZlX6rfIYtrygJFrbULGb7A4Ekj9IDzUjnpiHSf8D1jtcHPNPZ2zRvrC3wARAQAB
14tCFYc29sbGEgQWRtaW5zIDxhZG1pbnNAeHNvbGxhLmNvbT6JAlQEEwEIAD4WIQQC
15CYSJdX9EUfQx+wz7/E2X2h5iywUCadkD7wIbLwUJAeEzgAULCQgHAgYVCgkICwIE
16FgIDAQIeAQIXgAAKCRD7/E2X2h5iyxvVD/wLxBbYrNLPuEAJwL8UWDu1naQuaZHl
17/6yDUBV70l7Cxla6KEUqipuJDeD+Vgn85CqVui9eHgZpgXSxG5WogtO+Fkw3n/Ww
18gJkbZQTufWCuW/A82+aHaD0GNCLYqV6EEHQQ4hko6Z3E3zuuI0EoP9hB1BgUq0W1
19qhwrb1Q6Y8nQMgmhCgoRC8EvVFQwk6isvxDczym02/edjxgWuDZJOmZ5WMeN3Vzz
20QoYaGuChoyemigwGvJBKJKAMlgCRZNKlX7L3fOebT16jq1i5ByUqmmngq3YnBnmv
21j76HXP+MQioVr1FC4lkTkD4wWAw/l0gO0B3zLbPY8KQO4gcfLdH6wWPsfcQDmYWK
221vT9AhSPcIQCEcPCZnDBsf6FbiO3KMp0mFCJ0dZdaRJrem/7eL+P3I//H3HKo8RR
23BBGHJZCcm6MSwztUxZW2+6YiMCP9oQVU2zRnUfl/+J6maj83vz9cFQEqYyhbKjTu
24kRkAowUUA54GXnmul+sCvuJXHoKeC4EyZzNYCDxd9Y2u0jAnng2qT09b66IguOZW
250FPSzsRSeHGigwcK+/ChLk0+1CTXmO1fweIsaE1RcqgNLCR4Drtpup2Be8PA3B7i
26Uu8hDz77Lzz8M4O7jDUpS+plUrJEJ1dY+Uiav8jvkeqT9wc89jwKHxNUFNiPhFRb
27cSPnPI9I1QziyLkCDQRp2QPvARAApfXCw+EkrxXY+kOC/WKTen5Z/5hsTlupq2XR
28uF9S//LzVmgPXuVHqMUWUoNs/nfRLwDbJ7CjygL1DKMDSBzPkovaLOhnr4EMvmsP
29CUgQPXP0YUpSYBkAe5idrK2RPegNe68+wEz5r6azHS9r1QjSy+ekXGdTMrAs/On2
30FxxMLWYrEJ8M8iBDQVVOOK8YowcNV44U+ljf5VkJ8TpdNXOATLxuhNXvYTzuDGi6
31J0XCMa3CkIzxC3E4U2qWrHOjU7DjsvqiL5PbtiHjHhCoS6emdPsvqViaIafzcuE5
32eAGiHMyLRl5uwSdAmuW04W+IPM1PM3lwFjFB2lM2f1qHTJXZvG6mXYcBZgrA25te
33dRBgGgpofXutem0jM1lMDLzhAYHhAw8/uJR8yrq2A6t+rIDa1RxP8WJzLASG9rn/
34NmEgor27yhC2RIX4GwJsJ5xSCRkQPxbllVYCVpB6nFfTORbkaWdo7LSwXzUjrJBG
35++m4zQ+rcKRx9XjErls/hYXPB0tZXOP6vYM1zTLqAKtRPeQxJPK5/TbWrVgphvSi
36Yu6qMfnp2IYfyr1Zv0QjxvMUS/A9yVoH1ObY2SJDTa2Wtz1zBX76+vGj4FfeMn2C
37ROIzdvt9ndSYRk2bu/7XtflG7HomE9a/ATqOHalmLykLDgfsQLhSyLKnhOq7MmQw
38ZaQt7hkAEQEAAYkEcgQYAQgAJhYhBAIJhIl1f0RR9DH7DPv8TZfaHmLLBQJp2QPv
39AhsuBQkB4TOAAkAJEPv8TZfaHmLLwXQgBBkBCAAdFiEENKTXmM5UXELlwc4NJVnA
40zu7wAJMFAmnZA+8ACgkQJVnAzu7wAJOsLQ/9Fr7qfXD4EHX/IBrtLvhFiFRoQsUQ
41wp0aI8N2UrGfcWjRCHg7qdYfS5jZTuntNQQIHkVjs3Uqy9K06Va5pbJGCAQv50MW
42qZVKKGuaJ0aM2BsgEzCIIZYAcJpQilcU16A7FIUETMcE7HbubfD6NRW3DDYTBMLd
43Jn9idvd7bRmYCQuCwDMnLfa9JFjt+paCuySUfyCDvFqnO6EXIYQd2JFYptECFEkQ
44crZEfFlA5ygrpUSCsf5lDHgykoVziLbnW1R25dv84OV/Xu3hsjJFAY/TPP1Nh8M6
45JqZjGz5kOcIRThmT28jZdfgeqOnwIAc3rnr4B3NiXuuIJawfltnV5ujmnipcKLK8
46wPJlUAMcCOg3UD5tXjGwPBU8ryHkAZfXsqcUDllA7bGCRMPnQtfTnAr7xrieCjfn
47FDElBPsSg5C2jV9E23/n7+M0MuL/73fYGe8tDleEQHwyRbTEmI+5v4gwt1IOUlg7
485znJdXkp/Kwhmgv4GnFTB78pD+lx3CB0vPFsufhATCY8lDP+xMvUeURDF6jhGP/F
497waM/sOh9/zd4RaOxHMxGZHNs7g9rVca2AbwCTKuTvV7blUz10/j80prEyJwNj5e
50n+td7m4xLHRhSYeSXMteXIowWPE1nshYpV5sZbywE8pOwzBXbqHoNClDQh5szyFB
51CyHQR8sowp+42FLUFw/+PdDSjmI7/Z3vmtRsi+VgqbDM7CW2T8rIR/sUizBOCRah
52mBM1aA7IyJ2GerdMFGVeCRcCljUEiGnw+IvPdS72bTpfvk+8fU2o7PXsQSJfmhQS
53cA4k9uhLm87S3Ng5SX50+qTsgZgc7qywoSqCs4KC7p5zmsc+hfmdpFFmBYTP24Ai
54WdCXt1fqAAsbbO9dU5mos2Hs/L6qANKaN0wJBwf/cRnrewdV6zVhLCvkDYuXADf8
55SmgzXCESVNZNEFLWC2+syl3McSaRbjaInf1ijB8oMI7zR32bonqTEw4Vxc+mcc7H
56ck3ZtYyE8iA8TU5yyNzv0bmD5b8S7EquXekhbckC6tZw/i+O6xt6sZNnczkGbvup
57v5MNf4h8bcCkMFZ1jD27wpLUyGbxyr9t0D4DJeDYaAIyDF2IWd4kAeHvUyRvJt+b
58mbDI6b00PHMlW5JGebVvaV5opeBn2/aYTAMg5T7ohHxksM6jWfIVJPMRTik6RsGC
5937yLy8U7gcxebRwty6GxZuDdRjaBz/JcC9TshTgvbWJ392t8O3ZU6mezV2yDHTAO
60dE30NoqxiX+sZTYsyL5hkSW44LiH5sd30HxyXLQQ1Q+k3y0drKbp9UNc3E79l/mX
61r6jr1egiuYyCUk2zjaUx+UfI7Xrk2uttanFgJsTTX2wIGic5iFEecfe45V/YgOM=
62=naL7
63-----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.