Prélèvements : Dates et montants

Dans le cas de tunnel de vente avec des produits ayant un abonnement par prélèvement, vous allez vouloir présenter à votre usager final les dates auxquelles il sera prélevé, le montant qu'il va devoir régler initialement, et le montant des échéances qu'il aura à régler par la suite.

La date de début de prélèvement

Un client peut-être prélevé à différents dates du mois (une seule fois, mais plusieurs possibilités). Le client final peut choisir le jour du mois auquel il souhaite être prélevé parmis les dates que propose le club (les dates auxquelles le club lance ses prélèvements).

Pour récupérer ces dates, vous pouvez utiliser l'endpoint GET /{client_token}/allowed_debit_days

Cet endpoint prend en paramètre un filtre startDate qui permets de récupérer les prochaines dates de prélèvement selon une date donnée "à parir de".

curl 'https://{{base_url}}/{{client_token}}/allowed_debit_days?startDate=2024-11-18' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer ...' \

Cet endpoint renvoie en retour la liste des jours de prélèvement :

[
    {
        "debitDay": 1,
        "date": "2024-11-18"
    },
    {
        "debitDay": 2,
        "date": "2024-11-19"
    },
    ...
]

Fournir la date de prélèvement à l'ajout au panier

Proposer l'une de ces dates à votre client, et conserver la en mémoire pour l'utiliser lors de l'ajout du produit au panier.

Lors du POST /{client_token}/articles renseignez la date de début souhaitée des prélèvements dans le repaymentSchedule

curl 'https://{{base_url}}/{{client_token}}/sales/{{saleId}}/articles' \
  -H 'accept: application/json, text/plain, */*' \
  --data-raw '{"parent":null,"offerId":"/{{client_token}}/offers/{{offerId}}","implementation":{"startDate":"2024-11-22"},"repaymentSchedule":{"specificDay":true,"debitDay":null,"startDate":"2024-11-23","debitWeekDay":6}}'

Les informations importantes ici étant :

{
    ...
    "offerId":"/{{client_token}}/offers/{{offerId}}",
    "implementation":{
        "startDate":"2024-11-22"
    },
    "repaymentSchedule":{
        "specificDay":true,
        "debitDay":null,
        "startDate":"2024-11-23",
        "debitWeekDay":6
    }
    ...
}

paramètre	description	exemple
offerId	L'identifiant de l'offre	/demo/offers/12345
implementation.starDate	Date de début de l'abonnement	2024-11-22
repaymentSchedule.specificDay	Spécifier un jour de prélèvement spécifique	true ou false
repaymentSchedule.startDate	Date du premier prélèvement	2024-11-23
repaymentSchedule.debitWeekDay	Jour de la semaine auquel l'usager souhaite être prelevé	6 (samedi)

Présenter les montants

Plusieurs montants sont à présenter au client

• Le montant à régler immédiatement
• Les frais d'inscription (souvent inclus)
• Le montant de la première échéance (pouvant différer, elle peut-être également inclue dans le montant à régler immédiatement)
• Le montant de chaque échéance suivante

CAUTION: Il est important de noter qu'un abonnement par prélèvement peut ne pas avoir de fin (reconduction tacite). Rendant difficile la possibilité de fournir un montant "total" de l'abonnement.

Où récupérer ces informations

Vous pouvez récupérer l'ensemble des informations dont vous aurez besoin dans le détail des offres du produit que l'usager souhaite acheter.

GET /{client_token}/offers?product=/{client_token}/products/12345

paramètre	description	exemple
registrationFeeTI	Le montant des frais d'inscription, taxes inclues	4900
registrationFeeName	Le nom donné aux frais d'inscription	Frais d'inscription
totalPriceTI	Le montant initial à régler, taxes incluses	8896
isFirstMonthPayed	Si la première échéance est inclue dans le montant à régler immédiatement	true ou false
rhythmBilling	Le rythme de facturation	week4 (Toutes les 4 semaines)
product.productBehaviors[].configuration.validityPeriod	La durée de validité de l'abonnement	P52W (52 semaines)
articleBehaviors.implementation.isProrated	Si le montant de la première échéance est proratisé selon la date de	début de l'abonnement
repaymentSchedule.occurrences	Les échéances pour une durée limiée	Voir plus bas
repaymentSchedule.recurrences	Les échéances pour une durée illimitée : Ce tableau est vide dans le cas d'un CDD	Voir plus bas

Les frais d'inscription

Les frais d'inscription registrationFeeTI sont inclus dans le montant initial de l'offre totalPriceTI. Leur séparation vous permet de les présenter/détailler.

Le montant à régler immédiatement

Ce montant est à récupéré dans la propriété totalPriceTI, il inclut d'office le montant de la première échéance (si elle doit être inclue), vous n'avez pas besoin de l'ajouter.

Le montant des échéances

Une présentation habituelle est de présenter un texte "Vous serez prélevé de X€ par (semaine|mois) tou(te)s les X (semaines|mois)".

Pour obtenir cette information vous devez récupérer les informations des occurences et recurrences comme décrit ci-dessous.

Fonctionnement des occurrences et recurrences

Les occurrences et recurrences fonctionnent sous le même schéma, elles vous servent à connaître les montants à facturer par période, pour un nombre de périodes données.

Grâce à elles, vous avez la possibilité d'établir un échéancier avec les dates des échéances et les montants qui seront prélevés.

CAUTION: Elles représentes des périodes de facturation, et non des périodes de prélèvement. Elles doivent être composées avec le rhythmBilling. cf. ci-dessous.

Si on prend la présentation d'un repaymentSchedule :

{
  "occurrences": [
    {
      "offset": "P4W", // La durée de répétition de cette occurrence
      "interval": "P1W", // L'intervalle de répétition de cette occurence
      "loop": 0, // Si 0 : On boucle offset / intervalle
      "taxRate": 2000,
      "priceTI": 749, // Le prix facturé taxes incluses par occurrences
      "priceTE": 624,
      "tax": 125,
      "priceCurrency": "EUR"
    },
    {
      "offset": "P0W", // Si 0 : Utilise loop
      "interval": "P1W", // L'intervalle de répétition de cette occurrence
      "loop": 48, // Le nombre de fois ou cette occurence est répétée
      "taxRate": 2000,
      "priceTI": 999,
      "priceTE": 833,
      "tax": 166,
      "priceCurrency": "EUR"
    }
  ],
  "recurrences": [
    {
      // Ni loop ni offset : Cette réccurrence se repète indefiniement
      "tax": 166,
      "interval": "P1W",
      "priceCurrency": "EUR",
      "taxRate": 2000,
      "priceTI": 1999,
      "priceTE": 833,
      "offset": "P0W"
    }
  ]
}

Cet échéancier se décrirait donc ainsi :

• Pendant 4 semaines (offset P4W et loop 0) on facture tous les 1 semaine (interval P1W) 7,49€
• Puis pendant 48 semaines (offset 0 et loop 48), l'abonnement coûte 9,99€ par semaine
• De manière infinie, dès la fin des récurrences, l'abonnement coûte 9,99€ par semaine

Pour une offre dans le rhythmBilling est week4, l'usager serait ici prélevé ainsi :

• 7,49€*4 = 29,96€ la première fois, au bout de 4 semaines
• 9,99€*4 = 39,96€ toutes les 4 semaines, pendant 48 semaines.
• 19,99€*4 = 79,96€ toutes les 4 semaines de manière indéfinie.

NOTE: Il est rare que le montant varie entre les occurences et les reccurences, il l'est ici pour l'exemple. Par contre, il arrive généralement que le montant de la première occurence diffère, typiquement si elle inclue des frais supplémentaires.

CAUTION: Attention, occurences et recurrences sont des tableaux qui peuvent contenir plusieurs objects comme décrits ci-dessous. Vous devez donc les additionner.

Les rythmes de facturation rhythmBilling

Les 3 rythmes de facturation les plus courants sont :

Rythme	description	Intevalle equivalent
week1	Toutes les semaines	P1W
week4	Toutes les 4 semaines	P4W
monthly	Tous les mois	P1M