Configure o rastreamento de status de pedidos

Para rastrear o status dos pedidos criados e validá-los, você precisará configurar o processamento de webhooks no lado do servidor do seu aplicativo.

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.

Para obter a lista completa de webhooks e informações gerais sobre trabalhar com eles, consulte a documentação de webhooks.

PHP SDK

Utiliza classes prontas para o processamento de webhooks

Configure o envio de webhooks

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.

Adicionar ouvinte do webhook

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.

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:

1. Concatene o JSON do corpo da solicitação e da chave secreta do projeto.
2. 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 o servidor da Xsolla não receber uma resposta aos webhooks Pagamento bem-sucedido do pedido e Cancelamento de pedido, ou receber uma resposta com um código 5xx, 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.

A lógica de retorno para os webhooks Pagamento e Reembolso é descrita na respectiva página de webhook.

Se o servidor da Xsolla não receber uma resposta ao webhook Validação do usuário ou receber 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 Pagamento bem-sucedido do pedido não são enviados.

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.