Accueil 
Après la création d’un produit et d’un abonné, l’abonné doit être abonné à un abonnement.
Vous pouvez créer des abonnements directement via le backend. Pour cela, vous devez naviguer vers Space > Abonnement.
Figure 1. Sélectionnez un abonné et un produit dans le backend.
Vous devez d’abord sélectionner l’abonné que vous souhaitez abonner à un produit. Sur la page suivante, une boîte de dialogue supplémentaire vous sera présentée, qui demande une référence et fournit un aperçu des coûts mensuels que vous avez définis dans le produit.
Figure 2. Configurez l’abonnement pour l’abonné.
|
Note
|
Dans cet exemple, aucun token n’est présent et sélectionné. Cela déclenchera un Charge Flow au cours duquel un e-mail sera envoyé à l’abonné pour lui demander ses données de paiement. Si vous avez déjà ces informations de paiement stockées dans un token valide, il est important que vous sélectionniez le token ici. Vous trouverez plus d’informations sur la création de tokens dans la documentation sur la tokenisation. |
Un abonnement peut également être créé via l’API de service web. Il existe deux façons d’initialiser un abonnement.
Nous devons distinguer deux formes différentes d’initialisation des abonnements :
-
Vous intégrez le service d’abonnement dans votre site web avec un processus d’enrôlement où l’abonné est présent et vous souhaitez collecter ses données de paiement immédiatement. Dans ce cas, vous devrez utiliser le service
initializeSubscriberPresent. Cela créera une transaction de paiementconfirmedqui peut être utilisée pour construire l’URL de la Payment Page ou le JavaScript comme décrit dans la documentation Iframe respectivement la documentation Payment Page. -
Vous pouvez également utiliser les
Charge Flowspour initialiser un abonnement. Dans ce cas, vous utilisez le serviceinitialize. Plus d’informations sur les Charge Flows dans la documentation Charge Flow
Consultez l’exemple de requête suivant pour découvrir comment vous devez combiner les requêtes.
Il est possible de créer un abonnement avec un token spécifique. Lorsque le token est déjà initialisé et prêt à être utilisé, la création de l’abonnement ne nécessite aucune saisie de la part de l’abonné. Lorsque vous ne fournissez pas de token, nous créons un token en même temps que l’abonnement. Le token nouvellement créé n’est pas initialisé. Il nécessite donc que l’utilisateur fournisse les informations de paiement. Cela peut se faire via la transaction initiale de l’abonnement.
Outre la création du token par le système, il peut être créé manuellement et assigné à l’abonnement.
Les tokens peuvent être créés via le backend sous Space > Paiement > Tokens. Cliquez à cet endroit pour créer un nouveau token.
Les tokens peuvent également être créés via l’API de service web en utilisant l’opération create sur le
Token Service.
Requête
{
"enabledForOneClickPayment": true,
"externalId": "customer-id-1",
"tokenReference": "customer-id-1"
}|
Note
|
L'`externaId` doit être unique. Si vous envoyez à nouveau l'`externalID`, le token sera mis à jour. |
|
Note
|
Si vous mettez à jour des entités, vous devez augmenter la propriété de version afin de maintenir la cohérence. |
Un abonnement peut également être créé via l’API. Pour cela, vous devrez utiliser le Subscription Service.
{
"currency": "EUR",
"product": {
"id": 2
},
"selectedComponents": [{
"id": 4
}, {
"id": 2
}],
"subscription": {
"reference": "subscription-subscriber-101",
"subscriber": {
"id": 2
},
"token": {
"id": 3
}
}
}Cela créera un abonnement à l’état PENDING avec les composants de produit et les propriétés spécifiés.
Comme étapes suivantes, nous devons initialiser l’abonnement avec Initialize. Cela peut se faire de deux manières.
-
En général, l’abonné est présent dans votre application et vous souhaitez qu’il fournisse les données de paiement directement dans le processus d’enrôlement. Dans ce cas, vous utilisez l’opération
initializeSubscriberPresentsur le Subscription Service -
Si votre abonné n’est pas présent, vous pouvez également lui envoyer un lien de paiement via le Charge Flow, où il sera invité à fournir ses informations de paiement. Dans ce cas, vous utilisez l’opération
initializesur le Subscription Service
Une fois l’abonnement créé, nous pouvons initialiser la transaction avec l’opération initializeSubscriberPresent sur le
Subscription Service.
Requête
POST request to the following endpoint:
/api/v2.0/subscriptions/2/initialize-subscriber-present
{
"successUrl": "http://www.yoursuccessurl.com",
"failureUrl": "http://www.yourfailedurl.com"
}Réponse
{
"createdOn": "2017-04-26T12:08:37.602Z",
"discardedBy": 0,
"externalId": "subscription-2",
"failedUrl": "http://www.yourfailedurl.com",
"id": 2,
"ledgerEntries": [],
"linkedSpaceId": 1,
"plannedExecutionDate": "2017-04-26T12:08:37.152Z",
"plannedPurgeDate": "2017-05-12T12:08:37.333Z",
"processingType": "SYNCHRONOUS",
"state": "PROCESSING",
"subscription": {
"id": 2
},
"succeedOn": null,
"successUrl": "http://www.yoursuccessurl.com",
"transaction": {
"id": 2
},
"type": "AUTOMATIC",
"version": 1
}Cela créera une transaction de paiement qui est à l’état confirmed. L’ID de transaction retourné dans la
réponse peut maintenant être utilisé pour exécuter soit buildJavaScriptUrl soit buildPaymentPageUrl et créer une
autorisation IFrame ou Payment Page.
Exemple
Dans l’exemple, nous utilisons la requête GET vers buildPaymentPageURL pour obtenir l’URL vers laquelle vous redirigez votre marchand afin qu’il fournisse les informations de paiement
et termine l’initialisation de l’abonnement. Lorsque la transaction est à l’état fulfill, l’abonnement passera à
l’état Active. Cela créera également une version d’abonnement active.
Vous pouvez également initialiser un abonnement avec un Charge Flow. Dans ce cas, vous utilisez l’opération initialize sur le
Subscription Service.
Cela déclenchera automatiquement un Charge Flow et demandera les informations de paiement à votre abonné si vous n’avez pas fourni de token ou si le token n’est pas valide.
|
Note
|
Vous avez maintenant un abonné abonné à un produit ! En coulisses, nous créons un grand livre (ledger) dans lequel nous suivons les débits qui surviennent pendant une période. À chaque période, le ledger est rapproché et le montant en souffrance est débité au client. Cela créera une transaction et une facture associée. La facture détaille ce que le client doit, indique quand il sera ou a été débité et suit le statut du paiement. Vous pouvez ajouter des débits supplémentaires sur ce ledger via l’API ou dans le backend. Vous trouverez plus d’informations dans la section sur la facturation. |
Les abonnements peuvent être résiliés avec l’opération terminate dans le Subscription Service.
Vous avez la possibilité de respecter le délai de résiliation ou de résilier l’abonnement immédiatement.
Lorsque le délai de résiliation est respecté, l’abonnement poursuivra le nombre spécifié de périodes de résiliation sur la version du produit
jusqu’à ce que l’abonnement se termine définitivement. Lorsque vous choisissez de résilier l’abonnement immédiatement, l’abonnement sera arrêté,
les frais de période seront calculés au prorata et un débit du montant en souffrance sera déclenché.
Si vous résiliez un abonnement, l’abonnement sera déplacé
vers l’état terminating, dans lequel les montants en souffrance seront débités. Une fois le dernier débit terminé avec succès, nous déplaçons
l’abonnement vers l’état terminated.
Requête
spaceId=1&subscriptionId=2&respectTerminationPeriod=trueEn général, un abonnement change au fil du temps. Il existe plusieurs raisons pour un changement. Soit l’utilisateur souhaite un autre
plan (p. ex. passer du basic plan au pro plan), soit le produit lui-même change. Un changement de produit peut exiger
que l’abonnement soit mis à jour vers la dernière version du produit.
Un changement peut être appliqué immédiatement ou conformément au délai de résiliation. Lorsqu’un changement immédiat est demandé, la période en cours est terminée et les montants en souffrance sont débités. Les frais de période sont calculés au prorata dans ce cas. Les frais d’installation sont traités de manière particulière, voir Upgrade & Downgrade.
Un changement peut être appliqué soit via l’API, soit via le backend.
Les abonnements peuvent être modifiés via le backend en éditant les abonnements. Vous pouvez sélectionner le nouveau produit et définir si le délai de résiliation doit être pris en compte. Cela conduit à la création d’une nouvelle version d’abonnement pour l’abonné qui sera active en fonction du paramètre de résiliation.
Vous pouvez également lancer un changement d’abonnement via l’API de service web en utilisant l’opération applyChanges sur le
Subscription Service
La requête ci-dessous mettra à jour mon abonnement avec l’ID 8 vers le nouveau produit pro avec l’ID 3. Ces changements prendront effet immédiatement.
Requête
{
"currency": "CHF",
"product": {
"id": 3
},
"respectTerminationPeriod": false,
"selectedComponents": [{
"id": 14
}],
"subscription": {
"id": 8
}
}Les frais d’installation fidélisent l’abonné. Toutefois, la contrainte lors du passage d’un produit à un autre devrait être réduite. C’est pourquoi
les frais d’installation sont généralement remboursés lors du passage d’un produit à un autre. Par exemple, lors du passage du basic plan au
pro plan, l’abonné n’a pas besoin de payer à nouveau l’intégralité des frais d’installation du pro plan. Une remise est accordée. Nous
appelons ce processus de passage entre des produits avec frais d’installation upgrade resp. downgrade. Une mise à jour de la version du produit
peut également conduire à un upgrade ou à un downgrade.
Les sections suivantes ne sont pertinentes que lorsque le produit a des frais d’installation.
L’illustration ci-dessous aide à montrer comment les downgrades et les upgrades sont calculés.
Figure 3. Comment les upgrades ou les downgrades sont-ils calculés.
Le fait que vous effectuiez un upgrade ou un downgrade est déterminé par deux paramètres :
-
weight : le poids peut être défini sur le composant du produit.
-
product-reference : la référence du produit est également définie sur le composant du produit.
Si vous modifiez un abonnement, nous comparons les composants de l’ancienne et de la nouvelle version du produit.
-
Dans un premier temps, les frais d’installation de la nouvelle version du produit seront débités à l’abonné. Dans l’illustration ci-dessus, vous voyez que la nouvelle version du produit a des frais d’installation de 150 EUR pour le composant Support Pro. Ceux-ci seront donc débités immédiatement après l’exécution du changement.
-
Sur la base du poids et des paramètres du composant dans l’ancienne version du produit, un crédit d’upgrade ou de downgrade sera appliqué à son ledger. Dans l’illustration ci-dessus, nous avons défini sur le composant Support qu’il y aura un crédit de 50 EUR en cas d’upgrade.
-
Tout d’abord, nous vérifions si le composant était déjà présent dans l’ancienne version du produit dans le même groupe de composants. Si nous trouvons la référence, nous comparons les poids pour déterminer s’il s’agit d’un upgrade ou d’un downgrade.
-
Comme le weight du composant Support Pro est plus élevé, le changement est considéré comme un upgrade et les 50 EUR seront crédités au ledger de l’abonné.
-
Si un nouveau composant est ajouté au groupe de composants qui n’était pas présent dans l’ancienne version du produit, aucun crédit ne sera appliqué.
Le changement de la version d’abonnement de l’abonné entraîne un crédit qui peut être vu sur le ledger d’abonnement de l’abonné.
Figure 4. Voyez les 50 EUR qui sont crédités au ledger de l’abonné.