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 trocar à nova opção de recebimento de webhooks combinados, contate seus Gerentes de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Para a operação completa da loja no jogo e gerenciamento de pagamento, é necessário implementar o processamento dos webhooks principais:

• Se você recebe webhooks combinados
• Se você recebe webhooks separados

Nome do webhook	Descrição
User validation > User validation (user_validation)	É enviado em diferentes estágios do processo de pagamento para confirmar se o usuário está registrado no jogo.
Serviços de jogo > Webhooks combinados > Pagamento bem-sucedido do pedido (order_paid)	Contém dados de pagamento, dados de transação e informações sobre os itens comprados. Use os dados do webhook para adicionar itens ao usuário.
Game services > Combined webhooks > Order cancellation (order_canceled)	Contém dados do pagamento cancelado, dados de transação e informações sobre os itens comprados. Use os dados do webhook para remover os itens comprados.

O esquema abaixo demonstra o processo de comprar e retornar itens usando webhooks combinados.

Nome do webhook	Descrição
User validation > User validation (user_validation)	É enviado em diferentes estágios do processo de pagamento para confirmar se o usuário está registrado no jogo.
Payments > Payment (payment)	Contém dados de pagamento e dados da transação.
Serviços de jogo > Webhooks separados > Pagamento bem-sucedido do pedido (order_paid)	Contém informações sobre os itens comprados e os dados da transação. Use os dados do webhook para adicionar itens ao usuário.
Payments > Refund (refund)	Contém dados de pagamento e dados da transação.
Game services > Separate webhooks > Order cancellation (order_canceled)	Contém informações sobre os itens comprados e o ID da transação cancelada. Use os dados do webhook para remover os itens comprados.

O esquema abaixo demonstra o processo de compra e retorno de itens usando webhooks separados.

Se a personalização do catálogo de itens for implementada no lado do 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 configurar webhooks no lado Xsolla:

1. Abra seu projeto dentro da Conta de Distribuidor e acesse a seção Payments > Webhooks.
2. No campo Webhook server, especifique o URL para o qual a Xsolla enviará os webhooks.

3. Clique em Enable webhooks.

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.

Se o servidor da Xsolla não receber uma resposta ao webhook Pagamento ou Reembolso, ou se receber uma resposta com um código 5xx, os webhooks também são reenviados com um intervalo de tempo maior. São feitas 12 tentativas no máximo dentro de 12 horas.

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.

Visão geral

A API de evento Xsolla permite que você use o serviço GetUpdates para receber e gerenciar informações de pagamento diretamente do seu aplicativo cliente sem precisar usar webhooks no seu servidor. Use essa poção de integração se desejar acelerar e simplificar sua integração eliminando a necessidade de configurar e manter seu próprio servidor para processar webhooks.

Integração entre seu jogo e a Xsolla:

Como configurar

Para receber eventos da Xsolla via API:

1. Na sua Conta de Distribuidor, acesse a seção Payments > Webhooks.
2. Clique em Use API. As configurações são salvas automaticamente.

3. Do aplicativo cliente, envie uma solicitação para https://getupdate.xsolla.com/events para obter informações de pagamento. Consulte as referências API para obter informações detalhadas. Na resposta, você receberá dados de pagamento no mesmo formato que o webhook Pagamento.
4. Se o pagamento for bem-sucedido, conceda a compra ao usuário.

Referência da API

Obter a lista de eventos não processados para os usuários

1GET https://getupdate.xsolla.com/events

Segurança: Token JWT do usuário portador

Amostra de resposta:

 1{
 2  "events": [
 3   {
 4     "id": 49, // event_id
 5     "status": 0,
 6     "created_at": "2025-04-03T21:21:27Z",
 7     "data": {
 8       "notification_type": "payment",
 9       "purchase": {
10         "order": {
11           "id": 000000001,
12           "lineitems": [
13             {
14               "quantity": 1,
15               "sku": "skill"
16             }
17           ]
18         }
19       },
20       ...
21     }
22   }
23 ]
24}

Marque o evento como processado

1POST https://getupdate.xsolla.com/events/<event_id>/processed

event_id é o parâmetro events.id obtido na resposta da chamada de API Obter lista de eventos não processados do usuário.

Segurança: Token JWT do usuário portador