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

Configuração de webhooks na Conta de Distribuidor

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Project settings no menu lateral e vá para a aba Webhooks.
3. No campo Webhook server, especifique o URL do seu servidor onde deseja receber os webhooks no formato https://example.com. Você também pode especificar o URL que você encontra em uma ferramenta para testar webhooks.
4. É gerada uma chave secreta para assinar webhooks de projeto por padrão. Se desejar gerar uma nova chave secreta, clique no ícone de atualização.
5. Clique em Enable webhooks.

Teste de webhooks na Conta de Distribuidor

Se os webhooks forem configurados com êxito, um bloco de teste de webhook será exibido abaixo do bloco de configuração do webhook.

A seção de testes na Conta de Distribuidor varia dependendo da opção de recebimento de webhook.

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. Implemente a obtenção de informações de assinatura.
2. Configure a autenticação do usuário.

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
 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      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

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

Fluxo de integração