Xsolla-logo

Visão geral

Webhooks são notificações sobre eventos que ocorrem no sistema. Quando ocorre um evento específico, a Xsolla envia uma solicitação HTTP na qual os dados do evento são transmitidos para seu aplicativo. Isso geralmente é uma solicitação POST no formato JSON.

Exemplos de eventos:

  • interação do usuário com um catálogo de itens
  • pagamento ou cancelamento de um pedido

Quando um evento definido acontece, a Xsolla notifica o seu sistema sobre o pagamento através de um webhook. Como resultado, você pode executar ações como:

  • repor o saldo do usuário
  • fazer um reembolso de pagamento
  • creditar ou debitar novos itens da conta do usuário
  • começar a fornecer uma assinatura
  • bloquear um usuário em caso de suspeita de fraude

Exemplo de um fluxo de trabalho de webhook de processamento de pagamentos:

Webhook de processamento de 
pagamentos

Configurações de webhooks ao trabalhar com produtos e soluções Xsolla:

Produto/Solução Obrigatório/Opcional Para que servem os webhooks
Pagamentos Obrigatório
  • Validação do usuário.
  • Receber informações sobre dados da transação em casos de pagamento bem-sucedido ou reembolso de pagamento.
  • Creditar itens comprados a um usuário e debitar itens em caso de cancelamento do pedido.
In-Game Store Obrigatório
  • Validação do usuário.
  • Receber informações sobre dados da transação em casos de pagamento bem-sucedido ou reembolso de pagamento.
  • Creditar itens comprados a um usuário e debitar itens em caso de cancelamento do pedido.
Botão Comprar Opcional Para vender chaves de jogo, a validação do usuário e o ato de creditar itens não são necessários. Você pode conectar webhooks se quiser receber informações sobre eventos, como pagamento ou cancelamento de pedido.
Se você conectar webhooks, é importante processar todos os webhooks necessários acionados.
Subscriptions Opcional Para receber informações sobre criação, atualização ou cancelamento de uma assinatura. Como alternativa, você pode solicitar informações por meio da API.
Web Shop Opcional Para a autenticação de usuários, se você usa autenticação via ID de usuário. Como alternativa, você pode usar autenticação de usuários via Xsolla Login.
Digital Distribution Hub Opcional
  • Validação do usuário.
  • Vinculando o ID de transação no lado da Xsolla com o ID da transação em seu sistema.
  • Transferência de parâmetros de transação adicionais no pedido.
  • Creditar itens comprados ao usuário e debitar itens em caso de cancelamento do pedido.

Você pode aprender mais nas instruções de configuração de webhooks para o Digital Distribution Hub.

Lista de webhooks necessários

Se você usa produtos e soluções que exijam webhooks, habilite e teste os webhooks em sua Conta de Distribuidor e configure o processamento deles. Quando ocorrem eventos específicos, os webhooks são enviados sequencialmente. Portanto, se você não processar um dos webhooks, os webhooks subsequentes não serão enviados. A lista de webhooks necessários é apresentada abaixo.

In-Game Store/Payments

Para operar plenamente a loja no jogo, é necessário implementar o processamento dos principais webhooks:

  • User validation (user_validation) — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
  • Payment (payment) — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
  • Successful payment of the order (order_paid) — é enviado quando um webhook Payment foi processado com êxito e contém informações sobre itens comprados e o ID da transação. Use os dados do webhook para adicionar itens ao usuário.
  • Refund (refund) — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
  • Order cancellation (order_canceled) — é enviado quando um webhook Refund foi processado com êxito e 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.

Se a personalização do catálogo de itens for implementada no lado do aplicativo, configure o processamento do webhook Catalog personalization on the partner’s side.

Observação

Para receber pagamentos reais, você só precisa implementar os webhooks Payment, Successful payment of the order e User validation, bem como assinar o contrato de licenciamento.

Subscriptions

Para gerenciar automaticamente os planos de assinatura, é necessário implementar o processamento dos principais webhooks:

  • User validation (user_validation) — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
  • Payment (payment) — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
  • Created subscription (create_subscription) — é enviado quando um webhook Payment foi processado com êxito ou o usuário comprou uma assinatura com um período de avaliação. Ele contém os dados da assinatura comprada e os do usuário. Use os dados do webhook para adicionar uma assinatura ao usuário.
  • Updated subscription (update_subscription) — é enviado quando uma assinatura é renovada ou alterada, quando um webhook Payment foi processado com êxito. Ele contém os dados da assinatura comprada e os dados do usuário. Use os dados do webhook para estender a assinatura do usuário ou alterar os parâmetros de assinatura.
  • Refund (refund) — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
  • Canceled subscription (cancel_subscription) — é enviadao quando um webhook Refund foi processado com êxito ou a assinatura foi cancelada por outro motivo. Ele contém informações sobre a assinatura e os dados do usuário. Use os dados do webhook para deduzir assinaturas compradas do usuário.

Configure webhooks na Conta de Distribuidor

Para habilitar o recebimento de webhooks:

  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 servidor onde você deseja receber webhooks no formato 'https://example.com'. Você também pode especificar o URL encontrado em uma ferramenta para testar webhooks.
  4. Uma chave secreta para assinar webhooks de projeto é gerada por padrão. Se quiser gerar uma nova chave secreta, clique no ícone de atualização.
  5. Clique em Enable webhooks.

Observação

Para testar webhooks, você pode selecionar qualquer site dedicado, como webhook.site, ou uma plataforma, como ngrok.

Observação

Não é possível enviar webhooks simultaneamente para URLs diferentes. O que você pode fazer na Conta de Distribuidor é especificar um URL para teste primeiro e, em seguida, substituí-lo pelo real.

Para desativar o recebimento de webhooks:

  1. Abra seu projeto na Conta de Distribuidor.
  2. Clique em Project settings no menu lateral e vá para a aba Webhooks.
  3. Clique em Desativar webhooks.

Teste webhooks na Conta de Distribuição

Testar webhooks ajuda a garantir a configuração correta do projeto tanto do seu lado quanto do lado da Xsolla.

Você pode testar o recebimento dos seguintes webhooks:

Nome do webhook Tipo de webhook
Validação do usuário user_validation
Pagamento payment
Cancelamento do pedido order_canceled
Pagamento bem-sucedido do pedido order_paid

Se os webhooks forem configurados com êxito, uma seção de teste de webhooks será exibida abaixo da seção de configuração de webhooks.

Seção de teste de 
webhooks

Observação

Se um aviso de que o teste não passou aparecer na seção de testes, verifique as configurações de resposta do webhook no ouvinte do webhook. As razões para os erros no teste são indicadas nos resultados do teste.

Exemplo:

Você usa o site especializado webhook.site para teste.

Um erro é exibido na seção Testing response to invalid signature.

Isso acontece porque a Xsolla envia um webhook com uma assinatura incorreta e espera que seu manipulador responda com um código HTTP 4xx especificando o código de erro INVALID_SIGNATURE.

webhook.site envia um código HTTP 200 em resposta a todos os webhooks, incluindo um webhook com uma assinatura incorreta. O código HTTP 4xx esperado não pode ser obtido e, portanto, um erro é exibido no resultado do teste.

Erro de teste

Loja

Na aba Loja, você pode testar os seguintes webhooks:

Para testar:

  1. Na seção de teste de webhooks, vá para a aba Loja.
  2. No menu suspenso, selecione o tipo de item. Se o item do tipo selecionado não estiver configurado na Conta de Distribuidor, clique em:
    • Connect – se o módulo com itens desse tipo não estiver conectado
    • Configure – se você conectou o módulo anteriormente, mas não concluiu a configuração
      Ao clicar no botão, você será redirecionado para a seção de Conta de Distribuidor correspondente ao tipo do item selecionado. Depois de criar o item, retorne à seção de teste de webhook e prossiga para a próxima etapa.
  3. Insira qualquer valor no campo ID do Pedido Xsolla.
  4. Selecione o SKU dos itens na lista suspensa e indique o valor. Você pode escolher vários itens do mesmo tipo clicando em + e adicionando-os em uma nova linha.
  5. Escolha a moeda em que o pedido será pago.
  6. Clique em Test.

Os webhooks Successful payment of the order e Order cancellation com os dados especificados são enviados para o URL fornecido. Os resultados do teste de cada tipo de webhook são exibidos abaixo do botão Test webhooks.

Seção de teste da 
loja

Pagamentos

Na aba Payments, você pode testar os seguintes webhooks:

Para testar:

  1. Na seção de testes, vá para a aba Paymenys.
  2. Preencha os campos necessários:
    1. User ID — ao testar, você pode usar qualquer combinação de letras e dígitos.
    2. Public user ID — ID conhecido por um usuário, como um e-mail ou um apelido. Esse campo será exibido se o ID de usuário público estiver habilitado em seu projeto na seção Pay Station > Settings > Additional settings.
    3. Currency — selecione uma moeda na lista suspensa.
    4. Xsolla Invoice ID — ID da transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
    5. Amount — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
    6. Invoice ID — ID da transação no lado do jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro necessário para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação do seu lado ao ID da transação no lado da Xsolla.
  3. Clique em Test webhooks.

No URL especificado, você receberá webhooks com dados preenchidos. Os resultados do teste de cada webhook, tanto para um cenário bem-sucedido quanto para um cenário com um erro, são exibidos no botão Test webhooks. Se o ID de usuário público estiver habilitado em seu projeto, você também verá os resultados de uma verificação de pesquisa de usuário.

Para cada webhook, você precisa configurar o processamento de ambos os cenários: um bem-sucedido e outro com um erro.

Seção de testes de 
pagamentos

Ao salvar o URL no campo Webhook server, você pode ver a seção Advanced settings, onde você pode conceder permissões para receber informações detalhadas em webhooks. Para fazer isso, defina as respectivas opções como On. Na linha de cada permissão, você pode ver a lista de webhooks afetados pelas configurações.

Opção Descrição
Exibir informações sobre a conta de pagamento salva As informações sobre a forma de pagamento salva são passadas no objeto personalizado payment_account.
Exibir informações sobre transações pelos métodos de pagamento salvos

As informações são passadas nos seguintes parâmetros personalizados do webhook:

  • saved_payment_method:
    • 0 — o método de pagamento guardado não foi utilizado
    • 1 — o método de pagamento foi salvo ao efetuar o pagamento atual
    • 2 — o método de pagamento previamente guardado é utilizado
  • payment_type:
    • 1 — pagamento único
    • 2 — pagamento recorrente
Adicionar objeto de ordem ao webhook As informações sobre o pedido são passadas no objeto order do webhook Payment .
Enviar apenas os parâmetros de usuário necessários sem dados confidenciais

Somente as seguintes informações sobre o usuário são passadas no webhook:

  • ID
  • país
Enviar parâmetros personalizados As informações sobre os parâmetros de token personalizados são passadas no webhook.
Exibir BIN e sufixo do cartão

As seguintes informações sobre o número do cartão bancário são passadas no webhook:

  • os primeiros 6 dígitos no parâmetro card_bin
  • os últimos 4 dígitos no card_suffix
Exibir marca do cartão A bandeira do cartão utilizado para efetuar o pagamento. Por exemplo, Mastercard ou Visa.

Configurações 
avançadas

Subscriptions

Na aba Subscriptions, você pode testar os seguintes webhooks:

Observação

Na Conta de Distribuidor, você só pode testar webhooks básicos de User Validation e Payment. Para testar outros tipos de webhook, vá para:

Observação

Para testar webhooks, você deve ter pelo menos um plano de assinatura criado na seção Publisher Account > Subscriptions > Subscription Plans.

Para testar:

  1. na seção de testes, vá para a aba Subscriptions.
  2. Preencha os campos necessários:

    1. User ID — ao testar, você pode usar qualquer combinação de letras e dígitos.
    2. Xsolla Invoice ID — ID da transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
    3. Public user ID — ID conhecido por um usuário, como um e-mail ou um apelido. Esse campo será exibido se o ID de usuário público estiver habilitado em seu projeto na seção Pay Station > Settings > Additional settings.
    4. Currency — selecione uma moeda na lista suspensa.
    5. Plan ID — um plano de assinatura. Escolha um plano na lista suspensa.
    6. Produto de subscription — escolha um produto na lista suspensa (opcional).
    7. Amount — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
    8. Invoice ID — ID da transação no lado do jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro necessário para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação do seu lado ao ID da transação no lado da Xsolla.
    9. Período experimental. Para testar a comp ra de uma assinatura sem um período de avaliação ou para testar a renovação de uma assinatura, especifique o valor 0.
  3. Clique em Test webhooks.

No URL especificado, você receberá webhooks com dados preenchidos. Os resultados do teste de cada webhook, tanto para um cenário bem-sucedido quanto para um cenário com um erro, são exibidos no botão Test webhooks.

Ouvinte webhook

Ouvinte webhook é o código de programa que permite receber webhooks acionados em um endereço URL especificado, gerando uma assinatura e enviando uma resposta para o servidor webhook Xsolla.

Observação

Você pode usar a biblioteca Pay Station PHP SDK, que contém classes prontas para processar webhooks.

No lado do seu aplicativo, implemente a recepção de webhooks dos seguintes endereços IP: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 35.236.90.90, 34.102.38.178.

Limitações:

  • Não deve haver várias transações bem-sucedidas com o mesmo ID no banco de dados do aplicativo.
  • Se o ouvinte do webhook recebeu um webhook com um ID que já existe no banco de dados, você precisará retornar o resultado do processamento anterior dessa transação. Não é recomendável creditar o usuário com uma compra duplicada e criar registros duplicados no banco de dados.

Geração de assinatura

Ao receber um webhook, você deve garantir a segurança da transmissão de dados. Para conseguir isso, uma assinatura deve ser gerada 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.
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

Enviando respostas ao webhook

Para confirmar o recebimento do webhook, o servidor deve retornar:

  • Código HTTP '200', '201' ou '204' em caso de resposta bem-sucedida.
  • 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 webhooks também pode retornar um código HTTP '5xx' em caso de problemas temporários em seu servidor.

Se uma resposta não for recebida para os webhooks Successful payment of the order e Order cancellation do pedido ou se uma resposta com um código '5xx' foi recebida, os webhooks são reenviados de acordo com o seguinte cronograma:

  • 2 tentativas com intervalo de 5 minutos
  • 7 tentativas com 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 uma resposta não foi recebida nem no webhook Payment, nem no webhook Refund, ou se uma resposta com um código '5xx' foi recebida, os webhooks também são reenviados com um intervalo de tempo maior. Há um limite de 12 tentativas dentro de 12 horas.

Observação

Se o reembolso do pagamento foi iniciado pela Xsolla e uma resposta com um código HTTP '5xx' veio em resposta ao webhook Refund, o pagamento ainda será reembolsado.

Se uma resposta não foi recebida para o webhook User validation ou uma resposta com um código de '400' ou '5xx' foi recebida, o webhook User validation não é reenviado. Nesse caso, um erro é mostrado ao usuário e os webhooks Payment e Successful payment of the order não são enviados.

Erros

Códigos de erro para o código HTTP 400:

Código Mensagem
INVALID_USER Usuário inválido
INVALID_PARAMETER Parâmetro inválido
INVALID_SIGNATURE Assinatura inválida
INCORRECT_AMOUNT Quantia incorreta
INCORRECT_INVOICE Invoice incorreto
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Lista de webhooks

Observação

O tipo de notificação é enviado no parâmetro notification_type.

Webhook Tipo de notificação Descrição
Validação do usuário user_validation Enviado para verificar se um usuário existe no jogo.
Pesquisa do usuário user_search Enviado para obter as informações do usuário com base no ID de usuário público.
Pagamento payment Enviado quando um usuário conclui um pagamento.
Reembolso refund Enviado quando um pagamento precisa ser cancelado por qualquer motivo.
Reembolso parcial partial_refund Enviado quando um pagamento deve ser parcialmente cancelado por qualquer motivo.
Transação rejeitada pelo AFS afs_reject Enviado quando uma transação é recusada durante uma verificação AFS.
Lista de bloqueios atualizada do AFS afs_black_list Enviado quando a lista de bloqueio do AFS é atualizada.
Assinatura criada create_subscription Enviado quando um usuário cria uma assinatura.
Assinatura atualizada update_subscription Enviado quando uma assinatura é renovada ou alterada.
Assinatura cancelada cancel_subscription Enviado quando uma assinatura é cancelada.
Assinatura não renovável non_renewal_subscription Enviado quando o status é definido como não renovável.
Adicionar conta de pagamento payment_account_add Enviado quando um usuário adiciona ou salva uma conta de pagamento.
Remover conta de pagamento payment_account_remove Enviado quando um usuário remove a conta de pagamento das contas salvas.
Validação de usuário na Web Shop - Enviado de um site Web Shop para verificar se um usuário existe no jogo.
Personalização de catálogo no lado do parceiro partner_side_catalog Enviado quando um usuário interage com a loja.
Pagamento bem-sucedido do pedido order_paid Enviado quando um pedido é pago.
Cancelamento do pedido order_canceled Enviado quando um pedido é cancelado.
Disputa dispute Enviado quando uma nova disputa é aberta.