Configure o rastreamento de status de pedidos

Use aplicativos da web de teste como exemplo de implementação:

Para conceder itens ao usuário, você precisa se certificar de que o pagamento foi bem-sucedido.

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

2 opções de recebimento de webhook forma configuradas no lado da Xsolla ao comprar e retornar itens — informações com dados de pagamento, transações e informações sobre os itens comprados podem vir separadamente ou podem ser combinados em um só webhook.

Mais informações sobre opções de recebimento de webhook

Recebendo informações em webhooks combinados:

Se você se cadastrou na Conta de Distribuidor após 22 de janeiro de 2025, você recebe todas as informações nos webhooks Pagamento bem-sucedido do pedido (order_paid) e Cancelamento do pedido (order_canceled). Neste caso, você não precisa processar os webhooks Pagamento (payment) e Reembolso (refund).

Recebimento de informações em webhooks separados:

Se você se cadastrou na Conta de Distribuidor no dia 22 de janeiro de 2025 ou antes, você recebe os seguintes webhooks:

Pagamento (payment) e Reembolso (refund) com informações sobre os dados de pagamento e da transação.
Pagamento bem-sucedido do pedido (order_paid) e Cancelamento do pedido (order_canceled) com informações sobre os itens comprados.

Você precisa processar todos os webhooks recebidos.

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:

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 compra e retorno de itens usando webhooks da lista.

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 comprar e retornar itens usando webhooks combinados da lista.

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 receber pagamentos reais, você só precisa assinar o Contrato de Licenciamento e implementar o processamento dos webhooks:

Pagamento, Pagamento bem-sucedido do pedido, e Validação do usuário se você receber webhooks separados.
Pagamento bem-sucedido do pedido e Validação do usuário se você possuir webhooks combinados.

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:

Abra seu projeto na Conta de Distribuidor.
Clique em Project setttings no menu lateral e vá para a seção Webhooks.
No campo Webhook URL, especifique o URL para o qual a Xsolla enviará os webhooks.

Para receber webhooks, especifique o URL do seu servidor no formato https://example.com. O protocolo HTTPS é usado para transferir dados; o protocolo HTTP não é suportado.

Para testar webhooks, você também pode escolher qualquer site dedicado, tal como webhook.site, ou uma plataforma, tal como ngrok. Para projetos reais, você precisa adicionar uma lógica de validação de compra.

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:

Concatene o JSON do corpo da solicitação e da chave secreta do projeto.
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.

A lista completa e o mecanismo dos webhooks, juntamente com exemplos detalhados de seu processamento, estão descritos na documentação de webhooks.

Obrigado pelo seu feedback!

Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.

Última atualização: 23 de Janeiro de 2025

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.