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 des appels 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.

curl -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'

{
  "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
}

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é).

1. Dans le Compte éditeur, accédez à Project settings > Webhooks.
2. Réglez la bascule dans le bloc Webhooks sur On.

3. Spécifiez l'URL de votre webhook. Cliquez sur Save settings.

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

Tester les webhooks dans le Compte éditeur

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, spécifiez la valeur 0).

3. Cliquez sur Test.
4. Vérifiez que vous avez reçu un message de réussite du test. Si votre test est réussi, votre serveur renverra un code d'état HTTP 204. En cas d'échec, le serveur renverra un code d'état HTTP 400 ou 500 ainsi qu'une description de l'erreur.

Tester l'achat d'un abonnement

• 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 le test des webhooks dans le Compte éditeur et activez le module Subscriptions.
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 Support > Transaction search dans le Compte éditeur.
9. Sélectionnez la transaction de test et cliquez sur le bouton de menu More (•••). Dans le menu contextuel, cliquez sur Refund (la transaction doit avoir le statut Complete). Cela enverra les webhooks Abonnement annulé et Remboursement.

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

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

Recherche par abonnement

1. Dans le Compte éditeur, accédez à la section 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. Dans le Compte éditeur, accédez à 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

• 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.