Se você não tiver nenhum servidor ou implementar a lógica para processamento de compras no lado do cliente, você poderá usar as seguintes maneiras:

1. WebSocket API.
2. Short-polling.

3. API de evento da Xsolla.

Obtenção de status de pedido no lado do cliente usando API WebSocket

A solução utiliza websockets para obter diversos status do pedido sem obter informações detalhadas sobre ele. Esse método é preferível: apenas uma conexão é criada entre o cliente (por exemplo, seu site ou aplicativo móvel) e o servidor Xsolla, e portanto não há carga adicional no cliente ou no servidor.

Conclua as seguintes etapas:

1. Para permitir que o servidor de websocket Xsolla e o seu cliente identifiquem mensagens de status de pedido, crie uma conexão:

 1const client = new Centrifuge(
 2connectionURL,
 3{
 4data: {
 5  user_external_id: user_external_id,
 6  auth: auth,
 7  project_id: project_id
 8}
 9}
10)
11connectionURL - wss://ws-store.xsolla.com/connection/websocket
12auth - user JWT token

2. Para receber novas mensagens sobre status de pedidos, inscreva-se em eventos usando a função client.on:

1client.on('publication', (ctx) => {
2   //handle the status
3});

3. Acione o estabelecimento de uma conexão:

1client.connect()

4. Para receber o histórico de alterações nos status de pedidos, conecte o método API de histórico.

 1client.on('subscribed', function (ctx) {
 2   client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
 3resp.publications.forEach((ctx) => {
 4   /handle the status
 5});
 6
 7   }, function (err) {
 8       //handle the status
 9   });
10});

Exemplo de corpo de mensagem:

1{
2order_id: 59614241,
3status: "new"
4}

Os seguintes status de pedido são possíveis:

• New — o pedido foi criado mas não pago
• Paid — o pedido foi pago
• Done — o pedido foi entregue (todos os recibos enviados, entregas feitas do lado da Xsolla, plataformas externas, etc.)
• Canceled — o pedido é cancelado e o pagamento reembolsado a um usuário

Recomendações de uso de websocket:

• O tempo máximo de espera por uma resposta via websocket é de 5 minutos.
• A conexão deve ser estabelecida ao abrir a interface de pagamento.
• A conexão deve ser abortada quando o status final do pedido for recebido, seja ele Canceled ou Done.
• Se o tempo de vida útil do websocket expirar, ou se houver qualquer problema com a conexão, utilize short-polling.

Short-polling

Para obter informações detalhadas sobre itens no pedido depois de alternar para o status, chame a API Obter pedido.

API de evento da Xsolla

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

O método XsollaCatalog.Purchase engloba diversos métodos para rastrear status de pedidos. O mecanismo de rastreamento é detalhado na documentação do SDK para Unity.

Adicionalmente, você pode implementar o gerenciamento do status e conteúdo do pedido, que são passados à função de retorno de chamada onSuccess do método comprado.

Você pode rastrear o status do pedido usando o método SDK CheckPendingOrder. Passe os seguintes parâmetros ao método:

• AccessToken — o token de pagamento, que foi recebido ao comprar o item.
• OrderId o ID de pedido, que foi recebido ao comprar o item.
• SuccessCallback — o retorno de chamado de pagamento bem-sucedido.
• ErrorCallback — o retorno de chamada de erro de solicitação.
• bIsUserInvolvedToPayment — se o usuário está envolvido no processo de pagamento. Passe true para comprar com moedas reais, e false para a compra de itens grátis e compras com moedas virtuais.

O mecanismo de rastreamento é detalhado na documentação SDK de nível empresarial do Unreal Engine.

Para solicitar o status e conteúdo de um pedido, chame o método SDK CheckOrder, passe os seguintes parâmetros a ele:

• AccessToken — o token de pagamento, que foi recebido ao comprar o item.
• OrderId o ID de pedido, que foi recebido ao comprar o item.
• SuccessCallback — o retorno de chamada de verificação de pedido bem-sucedido. A resposta contém o status de pedido.
• ErrorCallback — o retorno de chamada de erro de solicitação.

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

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Payment webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback (optional)
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Refund webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment