Obtenir des informations d’abonnement

Pour obtenir des informations sur l’activité liée aux abonnements, procédez comme suit :

• demandez des informations à l’aide des appels API (adapté à l’intégration sans serveur) ;
• obtenez des informations lorsque le statut de l’abonnement change automatiquement à l’aide de webhooks (adapté à l’intégration serveur).

Configuration via API

Spécifiez projectId, l’ID de projet, comme paramètre de chemin. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.

Spécifiez comme paramètres de requête :

• limit — limite du nombre d’éléments sur la page (15 éléments sont affichés par défaut) ;
• offset — numéro de l’élément à partir duquel la liste est générée (le décompte commence à 0) ;
• locale — langue de l’interface (anglais par défaut). Accepte des valeurs selon la norme ISO 639-1.

1curl -X 'GET' \
2  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "id": 11111111,
 5      "plan_id": 11111,
 6      "plan_external_id": "TestChangePlanBase",
 7      "plan_name": "package_recurrent_name_66053",
 8      "plan_description": "package_recurrent_description_66053",
 9      "product_id": null,
10      "product_external_id": null,
11      "product_name": null,
12      "product_description": null,
13      "status": "active",
14      "date_create": "2021-03-11T13:50:11+03:00",
15      "date_next_charge": "2031-04-11T13:51:02+03:00",
16      "date_last_charge": "2021-03-11T13:51:02+03:00",
17      "charge": {
18        "amount": "0.2500",
19        "currency": "USD"
20      },
21      "period": {
22        "value": 1,
23        "unit": "day"
24      }
25    }
26  ],
27  "has_more": true
28}

Configurer des webhooks

La solution Subscriptions prend en charge les webhooks pour les événements suivants :

• Paiement d’un abonnement :
  • Validation utilisateur ;
  • Paiement ;
  • Created Subscription.

• Renouvellement d'un abonnement :
  • Validation utilisateur ;
  • Paiement ;
  • Abonnement mis à jour.
• Annullation d'un abonnement : Abonnement annulé (l'abonnement a été annulé dans le Compte éditeur ou tous les paiements ont été annulés pour toutes les périodes de validité).

• Remboursement :
  • Remboursement (le paiement a été annulé dans le Compte éditeur) ;
  • Abonnement mis à jour (le paiement a été annulé, mais l'abonnement est toujours actif, ce qui est possible si l'utilisateur a accidentellement payé l'abonnement deux fois et n'a annulé que le dernier paiement) ;
  • Abonnement annulé (le paiement a été annulé dans le Compte éditeur ou tous les paiements ont été annulés pour toutes les périodes de validité).

Pour activer la réception des webhooks :

1. Dans le projet dans le Compte éditeur, accédez à la section Project settings > Webhooks.
2. Dans le champ Webhook server, spécifiez l’URL du serveur où vous souhaitez recevoir les webhooks au format https://example.com. Vous pouvez également utiliser une URL fournie par un outil de test de webhooks.

3. Générez une clé secrète :

1. Dans la section Secret keys, appuyez sur Add key.
2. Dans la fenêtre modale qui s'affiche, entrez le nom de la clé qui vous permettra de l'identifier dans la liste générale.
3. Appuyez sur Create key.
4. Appuyez sur Copy secret et enregistrez la clé créée de votre côté.
5. Appuyez sur Done.
6. Confirmez que vous avez enregistré la clé et appuyez sur Ok, close.

4. Appuyez sur Enable webhooks.

Rotation de la clé secrète

Créez jusqu'à 5 clés secrètes dans votre projet afin de permettre leur rotation.

Une seule clé secrète peut être active par projet. Pour la modifier, appuyez sur Set as active sur la ligne d'une autre clé, puis confirmez l'action. Une fois la migration vers une nouvelle clé effectuée, nous vous recommandons de supprimer les clés désactivées.

5. Testez les webhooks dans le Compte éditeur.
6. Testez l'achat d'un abonnement.
7. Testez le renouvellement d'un abonnement.
8. Testez l'annulation d'un abonnement.

Tester les webhooks dans le Compte éditeur

Dans l’onglet Subscriptions, vous pouvez tester les webhooks suivants :

• Validation utilisateur (user_validation)
• Paiement (payment)

Pour tester les webhooks :

1. Dans la section de test, accédez à l’onglet Subscriptions.
2. Remplissez les champs nécessaires :
   • User ID — lors des tests, utilisez n’importe quelle combinaison de lettres et de chiffres.
   • Xsolla invoice ID — ID de transaction côté Xsolla. Lors des tests, utilisez n’importe quelle valeur numérique.
   • Public user ID — ID connu de l’utilisateur, par exemple, un e-mail ou un pseudo. Ce champ s’affiche si vous avez coché la case Use public user ID dans le projet dans la section Project settings > Integration settings.
   • Amount — montant du paiement. Lors des tests, utilisez n’importe quelle valeur numérique.
   • Currency — sélectionnez une devise dans la liste déroulante.
   • Plan ID — un plan d’abonnement. Choisissez un plan dans la liste déroulante.
   • Subscription product — choisissez un produit dans la liste déroulante (facultatif). La liste s’affiche si des produits sont configurés dans le projet.
   • Invoice ID — ID de transaction côté de votre jeu. Lors des tests, utilisez n’importe quelle combinaison de lettres et de chiffres. Ce n’est pas un paramètre requis pour un paiement réussi, mais vous pouvez le passer pour lier l’ID de transaction de votre côté à l’ID de transaction côté Xsolla.
   • Trial period. Pour tester l’achat d’un abonnement sans période d’essai ou pour tester le renouvellement d’un abonnement, spécifiez la valeur 0.
3. Appuyez sur Test.

À l’URL spécifiée, vous recevrez des webhooks contenant les données renseignées. Les résultats des tests de chaque webhook, en cas de succès comme en cas d’erreur, s’affichent sous le bouton Test.

Tester l'achat d'un abonnement

Lorsque vous testez un paiement, les webhooks Validation utilisateur, Paiement et Created Subscription sont envoyés à l’URL que vous avez spécifiée à l’étape de configuration des webhooks. Pour tester le processus de paiement, vous pouvez :

• Utiliser le mode bac à sable (pour les abonnements sans période d’essai) ;
• Effectuer un paiement réel, puis initier un remboursement dans le Compte éditeur (pour les abonnements avec période d’essai).

Mode bac à sable

1. Obtenez un jeton pour le mode bac à sable. Passez la valeur 0 au paramètre Trial period (trial_days).
2. Choisissez le groupe de modes de paiement Carte de crédit/débit.
3. Entrez les informations de la carte bancaire de test. Entrez des valeurs aléatoires dans les autres champs. Pour générer une erreur, spécifier des informations incorrectes (numéro de carte, date d'expiration ou CVV).

4. Recevez les webhooks Validation utilisateur, Paiement et Abonnement mis à jour à l'URL que vous avez spécifiée à l'étape de configuration des webhooks.

Paiement réel

1. Complétez Tester les webhooks dans le Compte éditeur.
2. Signez le contrat de licence.

3. Obtenez un jeton pour les paiements réels.

4. Ouvrez l'interface de paiement avec le lien suivant : https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, où ACCESS_TOKEN est le jeton obtenu à l'étape précédente.
5. Choisissez le groupe de méthodes de paiement Carte de crédit/débit.
6. Entrez les informations d'une carte bancaire valide.

7. Recevez les webhooks Validation utilisateur, Paiement et Abonnement mis à jour à l'URL du webhook spécifiée à l'étape de configuration des webhooks.
8. Initiez un remboursement. Pour ce faire, accédez à la section Publisher Account > Player support > Transaction search dans le Compte éditeur.
9. Sélectionnez la transaction de test et appuyez sur le bouton de menu More (•••). Dans le menu contextuel, appuyez sur Refund (la transaction doit avoir le statut Complete). L'envoi des webhooks Abonnement annulé et Remboursement sera déclenché.

Tester le renouvellement d'un abonnement

1. Obtenez un jeton pour le mode bac à sable. Passez la valeur 0 au paramètre Trial period (trial_days).
2. Payez l’abonnement en utilisant n’importe quel mode de paiement.
3. Rouvrez l’interface de paiement en mode bac à sable.
4. Payez à nouveau pour renouveler votre abonnement en utilisant n’importe quel mode de paiement.
5. Recevez les webhooks Validation utilisateur, Paiement et Abonnement mis à jour sur l’URL du webhook que vous avez spécifiée à l’étape de configuration des webhooks.

Tester l'annulation d'un abonnement

Pour tester l’annulation d’un abonnement, utilisez :

• Recherche par abonnement ;
• Recherche par transactions récentes ;
• Appels API.

Recherche par abonnement

1. Ouvrez le projet le Compte éditeur et accédez à la section Player support > Subscribers.
2. Trouvez l'abonnement que vous souhaitez annuler.
3. Ouvrez le menu d'état de l'abonnement et sélectionnez :
   1. Cancel and refund pour recevoir les webhooks Abonnement annulé et Remboursement ;
   2. Cancel without refund pour recevoir le webhook Abonnement annulé.

Recherche par transactions récentes

1. Ouvrez le Compte éditeur et accédez à la section Player support > Transaction search.
2. Trouvez les dernières transactions annulées.
3. Cliquez sur l'icône More (•••). Dans le menu contextuel, cliquez sur Refund pour recevoir les webhooks Abonnement annulé et Remboursement.

Via appels API

Ouvrir l'interface de paiement en mode bac à sable

Pour ouvrir l’interface de paiement en mode bac à sable, obtenez un jeton dans le mode sandbox. Le jeton requis peut être obtenu :

• dans le Compte éditeur ;
• via appel API.

Dans le Compte éditeur

1. Testez les webhooks dans le Compte éditeur. Pour tester un abonnement sans période d'essai, spécifiez la valeur 0 dans le champ Trial period. Après avoir reçu un message de confirmation de réussite du test, un lien contenant le jeton requis apparaît sous le titre Sandbox URL.

2. Suivez le lien Sandbox URL.

Via appel API

1. Passez le paramètre "settings":{"mode":"sandbox"} à la méthode Créer un jeton. Pour tester un abonnement sans période d'essai, passez le paramètre "purchase": {"subscription":{"trial_days": 0}}.
2. Utilisez le lien suivant : https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, où ACCESS_TOKEN est le jeton obtenu à l'étape précédente.