Configure o rastreamento de status de pedidos
Para conceder itens ao usuário, você precisa se certificar de que o pagamento foi bem-sucedido.
Escolha um método para rastrear o status do pedido:
Escolha o método mais adequado para o seu projeto para acessar os dados Xsolla:
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:
Obtenção de status de pedido no lado do cliente usando WebSocket API
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:
- Para permitir que o servidor de websocket Xsolla e o seu cliente identifiquem mensagens de status de pedido, crie uma conexão:
- javascript
const client = new Centrifuge(
connectionURL,
{
data: {
user_external_id: user_external_id,
auth: auth,
project_id: project_id
}
}
)
connectionURL - wss://ws-store.xsolla.com/connection/websocket
auth - user JWT token
- Para receber novas mensagens sobre status de pedidos, inscreva-se em eventos usando a função
client.on
:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- Acione o estabelecimento de uma conexão:
- javascript
client.connect()
- Para receber o histórico de alterações nos status de pedidos, conecte o método API de histórico.
- javascript
client.on('subscribed', function (ctx) {
client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
resp.publications.forEach((ctx) => {
/handle the status
});
}, function (err) {
//handle the status
});
});
Exemplo de corpo de mensagem:
- javascript
{
order_id: 59614241,
status: 'new'
}
Os seguintes status de pedido são possíveis:
New
— o pedido foi criado mas não pagoPaid
— o pedido foi pagoDone
— 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
O tempo necessário para uma resposta via websocket é de 5 minutos. Depois disso ou se houver algum problema com o websocket, recomenda-se usar short-polling.
Short-polling
Para obter informações detalhadas sobre itens no pedido depois de alternar para o status, chame a API get order.
O método XsollaCatalog.Purchase
encapsula diversos métodos para rastrear o status do pedido. O mecanismo de rastreamento é detalhado na documentação do SDK de nível empresarial 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.
Ao usar o SDK, você pode rastrear o status do pedido das seguintes maneiras:
Inscrevendo-se nas alterações de status do pedido
Para se inscrever nas alterações de status de pedido, use o método SDK getOrderStatus
da biblioteca Store e passe os seguintes parâmetros ao método:
listener
— objeto do ouvinte do tipoOrderStatusListener
.orderId
— ID do pedido recebido da compra através do carrinho de compras, compras com um clique ou compras com moedas virtuais como parâmetro.
Exemplo de chamada do método XStore.getOrderStatus:
- kotlin
XStore.getOrderStatus(object : OrderStatusListener() {
override fun onStatusUpdate(status: OrderResponse.Status) {
if(status == OrderResponse.Status.DONE) {
Log.d("MainActivity", "Success")
}
}
override fun onFailure() {
Log.d("MainActivity", "Failure")
}
}, orderId)
Recomendamos chamar o método XStore.getOrderStatus
ao abrir a interface de pagamento.
Esses métodos de compra encapsulam vários métodos para controlar o status do pedido. O rastreamento é realizado de acordo com o seguinte algoritmo:
- Uma conexão de websocket é estabelecida.
- Se a conexão for estabelecida com sucesso e o status do pedido for alterado para
done
oucancel
, o rastreamento é interrompido. Se uma conexão de websocket falhar ou a resposta contiver dados incorretos, o status do pedido é rastreado usando short-polling. - O rastreamento do status do pedido continua com short-polling. Uma solicitação de status de pedido HTTP simples é enviada a cada 3 segundos. O rastreamento é interrompido se o status do pedido for alterado para
done
oucancel
.
Solicitando o status do pedido
Para solicitar o status atual da transação de pagamento, chame o método getOrder
da biblioteca Store, passando os seguintes parâmetros a ele:
orderId
— o ID de pedido, que foi recebido ao comprar o item.callback
— o retorno de chamada por receber as informações do pedido com sucesso. Ao implementar um retorno de chamada, use a interfaceGetStatusCallback
e implemente os métodosonSuccess
eonError
.callback
— o retorno de chamada por receber as informações do pedido com sucesso. Ao implementar um retorno de chamada, use a interfaceGetStatusCallback
e implemente os métodosonSuccess
eonError
.
As informações de status do pedido são passadas ao método onSuccess
em um objeto do tipo InvoicesDataResponse
. Esse objeto contém uma matriz de objetos InvoiceData
. Cada objeto InvoiceData
corresponde a um estágio específico no processamento de pedidos e contém o status dessa etapa.
Por exemplo, se o usuário inicialmente inserir dados inválidos ao fazer um pedido, um objeto com o status InvoicesDataResponse.CANCELED
aparecerá na lista InvoiceData
. Se o usuário corrigir posteriormente os dados e pagar o pedido com sucesso, um novo objeto InvoiceData
aparecerá na matriz, agora com o status InvoicesDataResponse.Status.DONE
.
O rastreamento de status é interrompido se o status de pagamento final (InvoicesDataResponse.Status.DONE
ou InvoicesDataResponse.Status.ERROR
) for recebido.
Exemplo:
- kotlin
XPayments.getStatus(<token>, <isSandbox>, object : GetStatusCallback {
override fun onSuccess(data: InvoicesDataResponse?) {
Log.d(TAG, "onSuccess is fired. Result data = $data")
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
Log.d(TAG, "onError is fired. ErrorMessage = $errorMessage")
}
})
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. Passetrue
para comprar com moedas reais, efalse
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.
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 operar plenamente uma loja no jogo, é necessário implementar o processamento dos principais webhooks:
Webhook | Tipo de notificação | Descrição |
---|---|---|
User validation | user_validation | É enviado em diferentes estágios do processo de pagamento para confirmar se o usuário está 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 sucesso e contém informações sobre os 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. |
Cancelamento de pedido | 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. |
Para obter a lista completa de webhooks e informações gerais sobre trabalhar com eles, consulte a documentação 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 Weboks.
- No campo Webhook URL, especifique o URL para o qual a Xsolla enviará os webhooks.
- 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
ou204
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 uma resposta não foi recebida para os webhooks Successful payment of the order e Order cancellation, ou se uma resposta com um código 5xx
for recebida, 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 uma resposta não for recebida pelo webhook Pagamento ou se uma resposta com um código 5xx
for recebida, 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 uma resposta não for recebida pelo webhook Validação do usuário ou for recebida 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 Successful payment of the order não são enviados.
Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.