Obtenir des informations d’abonnement

Si vous envisagez de vendre des abonnements dans le magasin en ligne, implémentez la réception d’informations sur les actions liées aux abonnements de l’une des manières suivantes :

• via API (adaptée à une intégration sans serveur) ;
• via des webhooks (notifications automatiques, adaptées à l’intégration serveur).

Configuration via des appels API

Côté client de votre application, implémentez l’obtention d’informations sur les abonnements de l’utilisateur au moyen d’une requête HTTP GET.

L’API Xsolla utilise l’authentification d’accès HTTP. La requête doit contenir un en-tête Authorization: Bearer <client_user_jwt>, où <client_user_jwt> est un jeton unique encodé conformément à la norme Base64. Pour l’obtenir :

• Lors de l’autorisation par nom d’utilisateur et mot de passe, utilisez les appels API Register new user et Auth by username and password ;
• Lors de l’autorisation via les réseaux sociaux, utilisez l’appel API Auth via social network.

Spécifiez comme paramètre de chemin projectId — l’ID de projet. 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.

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

Exemple de réponse :

{
  "items": [
    {
      "id": 11111111,
      "plan_id": 11111
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      },
      "period": {
        "value": 1,
        "unit": "day"
      }
    }
  ],
  "has_more": true
}

Configuration via des webhooks

1. Configurez les paramètres de réception des webhooks :
   1. Ouvrez le projet dans le Compte éditeur.
   2. Dans le menu latéral, cliquez sur Project settings et accédez à l'onglet Webhooks.
   3. Dans le champ Webhook server, spécifiez l'URL du serveur où vous souhaitez recevoir les webhooks, dans le format https://example.com. Vous pouvez également spécifier l'URL que vous trouvez dans un outil de test de webhooks.
   4. Une clé secrète pour signer les webhooks du projet est générée par défaut. Si vous souhaitez générer une nouvelle clé secrète, cliquez sur l'icône d'actualisation.
   5. Cliquez sur Enable webhooks.

2. Implémentez le traitement des types de webhooks suivants dans votre application :
   • Pour acheter et renouveler un abonnement :
     • User Validation ;
     • Payment ;
     • Created Subscription ;
     • Updated Subscription.
   • Pour annuler un abonnement :Canceled Subscriptionannulé.
   • Pour rembourser :Refund.

3. Testez les webhooks :
   1. Dans le Compte éditeur, accédez à la section Project settings > Webhooks, puis à l'onglet Subscriptions.

2. Indiquez les valeurs de votre projet (ID utilisateur, ID de facture) à envoyer dans la requête à l'URL spécifiée. En l'absence de valeurs réelles, saisissez des valeurs arbitraires. Remplissez les champs suivants du formulaire :
   • ID utilisateur ;
   • ID de facture côté Xsolla ;
   • Montant ;
   • Devise ;
   • ID de plan ;
   • Produit d'abonnement (facultatif) ;
   • ID de facture — numéro de commande interne (facultatif) ;
   • Période d'essai (pour tester l'achat d'un abonnement en mode bac à sable ou tester le renouvellement d'un abonnement, définissez la valeur 0).

3. Cliquez sur Test.
4. Vérifiez que vous avez reçu un message de réussite de test. Si votre test est réussi, votre serveur doit renvoyé :
   • Un code HTTP 204 sans corps de message ;
   • Un code HTTP 400 ou 500 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.

4. Testez la réception des webhooks restants :
   1. Utilisez le mode bac à sable pour tester l'achat et le renouvellement d'un abonnement afin de recevoir les webhooks Created Subscription, Updated Subscription et Canceled Subscription.
   2. Utilisez le mode de production pour tester l'achat d'abonnements avec des paiements réels afin de recevoir les webhooks Refund et Canceled Subscription.

Étapes suivantes

1. Configurez l'authentification utilisateur.
2. Testez le magasin en ligne en mode bac à sable.

Liens utiles

Flux d’intégration