Configurer le suivi de l’état de la commande
Pour attribuer des objets à l’utilisateur, vous devez vous assurer que le paiement est un succès.
Choisissez une méthode pour suivre l’état de la commande :
Choisissez la méthode la plus adaptée à votre projet pour accéder aux données Xsolla :
Si vous n’avez pas de serveur ou si vous implémentez la logique de traitement des achats côté client, vous pouvez utiliser les moyens suivants :
Obtenir l'état d'une commande côté client à l'aide de l'API WebSocket
La solution utilise WebSockets pour obtenir les statuts des commandes sans récupérer d’informations détaillées sur celles-ci. Cette méthode est préférable, car elle établit une seule connexion entre le client (par exemple, votre site web ou votre application mobile) et le serveur Xsolla, évitant ainsi une charge supplémentaire pour le client ou le serveur.
Effectuez les étapes suivantes:
- Pour permettre au serveur Xsolla WebSocket et à votre client d’identifier les messages d’état des commandes, créez une connexion :
- 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
- Pour recevoir de nouveaux messages sur les statuts des commandes, abonnez-vous aux événements à l'aide de la fonction
client.on
:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- Déclenchez l'établissement effectif de la connexion :
- javascript
client.connect()
- Pour recevoir l'historique des changements de statuts des commandes, connectez la méthode API d'historique.
- 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
});
});
Exemple de corps de message:
- javascript
{
order_id: 59614241,
status: 'new'
}
Les statuts de commande suivants sont possibles :
New
— la commande a été créée, mais n’est pas encore payée ;Paid
— la commande est payée ;Done
— la commande a été livrée (tous les reçus ont été envoyés, les livraisons ont été effectuées du côté de Xsolla, des plateformes externes, etc.) ;Canceled
— la commande a été annulée et le paiement a été remboursé à l’utilisateur.
Le temps nécessaire pour une réponse via websocket est de 5 minutes. Passé ce délai ou en cas de problème avec le websocket, il est recommandé d’utiliser un short-polling.
Short-polling
Pour obtenir des informations détaillées sur les biens de la commande après le passage au statut approprié, appelez l’API Get order.
La méthode XsollaCatalog.Purchase
encapsule plusieurs méthodes de suivi de l’état de la commande. Le mécanisme de suivi est détaillé dans la documentation du SDK Unity destiné aux entreprises.
Vous pouvez également implémenter le traitement de l’état et du contenu de la commande, passés à la fonction de rappel onSuccess
de la méthode d’achat.
Pour suivre l’état de la commande lorsque vous utilisez le SDK, vous pouvez :
S'abonner aux changements d'état des commandes
Pour vous abonner aux changements d’état des commandes, utilisez la méthode SDK getOrderStatus
de la bibliothèque Store et passez-lui les paramètres suivants :
listener
— objet écouteur de typeOrderStatusListener
;orderId
— ID de la commande reçu en tant que paramètre lors de l’achat via le panier, de l’achat en un clic ou de l’achat contre de la monnaie virtuelle.
Exemple d’appel à la méthode 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)
Nous recommandons d’appeler la méthode XStore.getOrderStatus
lors de l’ouverture de l’interface de paiement.
Les méthodes d’achat encapsulent plusieurs méthodes de suivi de l’état de la commande. Le suivi est effectué selon l’algorithme suivant :
- Une connexion WebSocket est établie.
- Si la connexion WebSocket est établie avec succès et que le statut de la commande passe à
done
ou àcancel
, le suivi s'arrête. Si la connexion WebSocket échoue ou si la réponse contient des données incorrectes, l'état de la commande est suivi à l'aide de short-polling. - Le suivi de l'état de la commande se poursuit à l'aide de short-polling. Une simple requête HTTP d'état de commande est envoyée toutes les 3 secondes. Le suivi s'arrête si le statut de la commande passe à
done
ou àcancel
.
Demander l'état de la commande
Pour demander le statut actuel du paiement, appelez la méthode getOrder
de la bibliothèque Store ; passez les paramètres suivants :
orderId
— ID de la commande, obtenu lors de l’achat de l’objet.callback
— fonction de rappel permettant de récupérer avec succès les informations sur la commande. Lors de l’implémentation d’une fonction de rappel, utilisez l’interfaceGetStatusCallback
et implémentez les méthodesonSuccess
etonError
.callback
— fonction de rappel permettant de récupérer avec succès les informations sur la commande. Lors de l’implémentation d’une fonction de rappel, utilisez l’interfaceGetStatusCallback
et implémentez les méthodesonSuccess
etonError
.
Le statut de la commande est passé à la méthode onSuccess
dans un objet InvoicesDataResponse
, qui contient un tableau d’objets InvoiceData
. Chaque objet InvoiceData
représente une étape du traitement de la commande et contient son statut.
Par exemple, si l’utilisateur entre initialement des données non valides, un objet avec le statut InvoicesDataResponse.CANCELED
s’affichera dans la liste InvoiceData
. Après correction et paiement réussi, un nouvel objet avec le statut InvoicesDataResponse.Status.DONE
apparaîtra dans le tableau.
Le suivi de l’état s’arrête lorsque le statut de paiement final (InvoicesDataResponse.Status.DONE
ou InvoicesDataResponse.Status.ERROR
) est reçu.
Exemple :
- 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")
}
})
Pour suivre l’état de la commande, utilisez la méthode SDK CheckPendingOrder
; passez les paramètres suivants :
AccessToken
— jeton de paiement, obtenu lors de l’achat de l’objet.OrderId
— ID de la commande, obtenu lors de l’achat de l’objet.SuccessCallback
— fonction de rappel en cas de paiement réussi.ErrorCallback
— fonction de rappel en cas d’erreur de requête.bIsUserInvolvedToPayment
— détermine l’implication de l’utilisateur dans le processus de paiement. Passeztrue
pour l’achat en monnaie réelle, etfalse
pour l’achat d’objets gratuits et l’achat en monnaie virtuelle.
Le mécanisme de suivi est détaillé dans la documentation du SDK Unreal Engine destiné aux entreprises.
Pour demander le statut actuel du paiement, appelez la méthode SDK CheckOrder
; passez les paramètres suivants :
AccessToken
— jeton de paiement, obtenu lors de l’achat de l’objet.OrderId
— ID de la commande, obtenu lors de l’achat de l’objet.SuccessCallback
— fonction de rappel en cas de vérification réussie de la commande. La réponse contient le statut de la commande.ErrorCallback
— fonction de rappel en cas d’erreur de requête.
Pour suivre l’état des commandes créées et les valider, vous devrez configurer le traitement des webhooks côté serveur de votre application.
Pour exploiter pleinement In-Game Store, il est nécessaire d’implémenter le traitement des principaux webhooks :
Webhook | Type de notification | Description |
---|---|---|
Validation utilisateur | user_validation | Est envoyé à différentes étapes du paiement pour s’assurer que l’utilisateur est bel et bien enregistré dans le jeu. |
Paiement | payment | Est envoyé lorsqu’une commande est payée, et contient les informations sur le paiement et les détails de la transaction. |
Paiement de commande réussi | order_paid | Est envoyé lorsqu’un webhook Paiement est traité avec succès, et contient les informations sur les objets achetés et l’ID de transaction. Utilisez les données du webhook pour octroyer les objets à l’utilisateur. |
Remboursement | refund | Est envoyé lorsqu’une commande est annulée, et contient les informations sur le paiement annulé et les détails de la transaction. |
Annulation de commande | order_canceled | Est envoyé lorsqu’un webhook Remboursement est traité avec succès, et contient les informations sur les objets achetés et l’ID de la transaction annulée. Utilisez les données du webhook pour supprimer les objets achetés. |
Pour accéder à la liste complète des webhooks et obtenir des informations générales sur leur utilisation, consultez la documentation sur les webhooks.
Configurer l'envoi de webhooks
Pour configurer les webhooks côté Xsolla :
- Ouvrez votre projet dans le Compte éditeur.
- Dans le menu latéral, cliquez sur Project settings et accédez à la section Webhooks.
- Dans le champ Webhook URL, spécifiez l’URL vers laquelle Xsolla enverra les webhooks.
- Cliquez sur Enable webhooks.
Ajouter un écouteur webhook
L’écouteur webhook est un code de programme qui permet de recevoir des webhooks entrants à une adresse URL spécifiée, de générer une signature et d’envoyer une réponse au serveur webhook de Xsolla.
Génération d'une signature
Lorsque vous recevez un webhook, vous devez vous assurer de la sécurité de la transmission des données. Pour cela, vous devez générer une signature à partir des données du webhook et vérifier qu’elle correspond à la signature envoyée dans l’en-tête de la requête HTTP.
Pour générer une signature :
- Concaténez le JSON du corps de la requête avec la clé secrète du projet.
- Appliquez la fonction de hachage cryptographique SHA-1 à la chaîne obtenue lors de la première étape.
Envoi de réponses au webhook
Pour confirmer la réception du webhook, votre serveur doit renvoyer :
- Un code HTTP
200
,201
ou204
en cas de réponse positive ; - Un code HTTP
400
avec description du problème au cas où l’utilisateur spécifié n’a pas été trouvé ou une signature non valide a été passée.
Votre gestionnaire de webhooks peut également renvoyer un code 5xx
en cas de problèmes temporaires sur votre serveur.
Si aucune réponse n’a été reçue pour les webhooks Successful payment of the order et Order cancellation ou si une réponse contenant un code 5xx
a été reçue, les webhooks sont renvoyés selon le calendrier suivant :
- 2 tentatives à intervalles de 5 minutes ;
- 7 tentatives à intervalles de 15 minutes ;
- 10 tentatives à intervalles de 60 minutes.
Un maximum de 20 tentatives d’envoi de webhooks sont effectuées dans les 12 heures suivant la première tentative.
Si aucune réponse n’a été reçue pour le webhook Payment ou si une réponse contenant un code 5xx
a été reçue, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectuées dans les 12 heures.
Si aucune réponse n’a été reçue pour le webhook User validation ou si une réponse contenant un code 400
ou 5xx
a été reçue, le webhook User validation n’est pas renvoyé.
Dans ce cas, une erreur est affichée à l’utilisateur et les webhooks Payment et Successful payment of the order ne sont pas envoyés.
Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.