Conceda compras ao usuário

Implemente a concessão de compras ao usuário em seu aplicativo usando informações recebidas em webhooks da Xsolla sobre os dados de transação e itens comprados.

Para o funcionamento completo da loja no jogo e gerenciamento de pagamentos, é necessário implementar o processamento dos principais webhooks:

O esquema abaixo mostra o processo de compra e devolução de itens usando webhooks combinados.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as Usuário
    participant GameClient as Cliente do jogo
    participant Xsolla as Xsolla
    participant GameServer as Servidor do jogo
    %% Item Purchase
    rect rgb(243, 243, 241)
        Note over User, GameServer: Compra de itens
    end
        User ->> GameClient: Faz login
        activate GameClient
        GameClient ->> Xsolla: Envia solicitação de autenticação de usuário
        activate Xsolla
        Xsolla -->> GameClient: Retorna o token JWT / OAuth 2.0
        deactivate Xsolla
        GameClient ->> Xsolla: Envia JWT, ID de projeto, parâmetros de paginação
        activate Xsolla
        Xsolla -->> GameClient: Retorna uma matriz de itens
        deactivate Xsolla
        GameClient -->> User: Exibe a vitrine
        deactivate GameClient
        User ->> GameClient: Selecione o item e clica em Comprar
        activate GameClient
        GameClient ->> Xsolla: Cria uma solicitação de pedido
        deactivate GameClient
        activate Xsolla
        Xsolla -->> GameClient: Retorna um token de pagamento
        deactivate Xsolla
        activate GameClient
        GameClient ->> Xsolla: Abre o URL de interface de pagamento com o token recebido
        deactivate GameClient
        activate Xsolla
        Xsolla ->> GameServer: Envia o webhook Validação do usuário
        activate GameServer
        GameServer -->> Xsolla: Retorna o código do status de sucesso
        deactivate GameServer
        Xsolla -->> User: Exibe a interface de pagamento
        deactivate Xsolla
        User ->> Xsolla: Escolha o método de pagamento e clica em Pagar
        activate Xsolla
        Xsolla ->> GameServer: Envia o webhook Pagamento bem-sucedido do pedido
        activate GameServer
        activate GameServer
        Note right of GameServer: Concede as compras ao usuário
        deactivate GameServer
        GameServer -->> Xsolla: Retorna o código do status de sucesso
        deactivate GameServer
        Xsolla -->> User: Exibe a tela de compra bem-sucedida
        deactivate Xsolla
    %% Refund / Chargeback
    rect rgb(243, 243, 241)
        Note over User, GameServer: Reembolso / Estorno
    end
        User ->> Xsolla: Solicita reembolso ou estorno
        activate Xsolla
        Xsolla ->> GameServer: Envia o webhook Cancelamento de pedido
        activate GameServer
        activate GameServer
        Note right of GameServer: Remove itens do inventário do usuário
        deactivate GameServer
        GameServer -->> Xsolla: Retorna o código do status de sucesso
        deactivate GameServer
        Xsolla -->> User: Reembolso do pagamento
        deactivate Xsolla

Se a personalização do catálogo de itens for implementada no lado do seu aplicativo, configure o processamento da personalização do catálogo no lado do parceiro.

Configuração de webhooks na Conta de Distribuidor

Para habilitar o recebimento de webhooks:

1. No projeto na Conta de Distribuidor, acesse a seção Configurações do projeto > Webhooks.
2. No campo Servidor de Webhooks, especifique o URL do seu servidor onde você deseja receber webhooks no formato https://example.com. Você também pode especificar o URL que encontrar em uma ferramenta para testar webhooks.

3. Gere uma chave secreta:

1. Na seção Chaves secretas, selecione Adicionar chave.
2. Na janela modal que surgir, insira o nome da chave que permitirá identificá-la na lista geral.
3. Selecione Criar chave.
4. Selecione Copiar segredo e salve a chave criada do seu lado.
5. Pressione Pronto.
6. Confirme que você salvou a chave e pressione Ok, fechar.

4. Selecione Enable webhooks.

Rotação de chave secreta

Você pode criar até 5 chaves secretas no seu projeto para habilitar a rotação delas.

Pode haver apenas uma chave secreta ativa por projeto. Se você quiser alterá-la, selecione Definir como ativa na linha de outra chave e confirme a ação. Assim que você migrar com sucesso para uma nova chave, recomendamos excluir as chaves desativadas.

Teste de webhooks na Conta de Distribuidor

Uma seção para testar webhooks é exibida na Conta de Distribuidor abaixo das configurações avançadas depois que você ativar webhooks no seu projeto.

Você pode testar os seguintes webhooks:

Na ausência de valores reais, você pode inserir valores arbitrários.

Você também pode testar webhooks ao fazer compras no modo sandbox ou online. O reembolso de teste está disponível apenas no modo online.

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.

Próximos passos

1. Configure a venda de assinaturas (opcional).
2. Configure a autenticação de usuários.

Configurando informações de item em webhooks

Você pode configurar quais dados de itens são inclusos nos webhooks Pagamento do pedido bem-sucedido e Cancelamento do pedido pela matriz items.

Habilitação da inclusão de parâmetros adicionais

Habilite a inclusão de parâmetros adicionais que indicam:

• se o item é grátis (is_free)
• se o item é um bônus (is_bonus)
• se o item faz parte de um conjunto (is_bundle_content)

Para receber esses parâmetros, você deve trocar seus webhooks para a versão 2 usando a chamada de API Atualizar informações sobre as configurações do webhook. Na versão 1 (padrão), esses parâmetros não estão disponíveis.

Exemplo de uma matriz de items com parâmetros adicionais:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Desativação da inclusão de conteúdos de conjunto

Por padrão, webhooks incluem todos os tipos de itens do conjunto como uma lista de itens individuais. Você pode configurar o webhook para incluir apenas o conjunto em si, sem listar seus conteúdos.

Nesse caso, os itens inclusos no conjunto não são inclusos na matriz items. Na matriz exibida acima, o item com o SKU com.xsolla.gold_1, que é parte do conjunto, é excluído.

Exemplo de uma matriz de items quando o conteúdo do conjunto está desativado:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Para desativar a inclusão de conteúdos do conjunto, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Links úteis