Aller au contenu principal

Paiement

Le procéssus de paiement se décompose en deux étapes. Dans un premier temps la construction du dossier client dans via les différentes étapes du tunnel. Une fois le dossier assemblé, on passe à la partie paiement, ou l'on va construire la page de paiement déportée dans worldline à partir des infos du dossier client et de ses choix de modalités et facilité de paiement.

Tunnel​

Ce cookie a pour but d'enregistrer tous les choix de l'utilisateur:

  • nombre et identité des participants.
  • ajout d'options
  • sélection d'une assurance

Ce cookie à une durée de vie de 30 min et est gérer avec Jotai. Il représente les différents arguments que l'on va communiquer à XFT via le call Get QuotedAvailability. La modification du cookie va relancer une requête pour mettre a jour le dossier qu'on est en train de créer, nous retournant par exemple le nouveau prix, etc.

Le cookie se décompose comme ceci:

{
  "product": 1821, // iResa id de l'établissement
  "benefit": { "id": 6792 }, // iResaId de la typo
  "period": { "start": "2025-04-19", "end": "2025-04-26" }, // date de voyage
  "travellers": [
    {
      "id": "T0",
      "firstName": "John",
      "lastName": "Doe",
      "birthDate": "1990-01-01",
      "gender": "MALE",
      "type": "ADULT"
    },
    {
      "id": "T1",
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": null,
      "gender": "FEMALE",
      "type": "ADULT"
    }
  ],
  "options": [
    { "code": "I4_3_4_1_2_2_1_0___1_0_27710", "quantity": 2 }, // Id et quantité de l'option
    { "code": "I4_3_4_2_2_2_1_0___1_0_33702", "quantity": 1 },
    { "code": "I4_3_4_2_2_2_1_0___1_0_33703", "quantity": 1 }
  ],
  "insurance": "IASSU_AUTO_20408", // id de l'assurance choisie
  "refNumber": "2148161/2503/WEB/WOD" // Booking number, dispo uniquement une fois que le dossier sera créé.
}

Étapes du tunnel et cycle de vie du dossier​

Le tunnel se décomposer en trois étapes :

  1. composition du voyage
  2. identification du client et creation du dossier
  3. choix de paiement

Composition du voyage​

Ce premier écran permet de composer le voyage en choisissant le nombre de voyageurs, les options et assurance à ajouter. Dans toute cette étape, on communique avec le service XFT Get QuotedAvailability pour optenir le montant du voyage. A ce stade, le dossier n'est pas encore créer. Quitter cet écran entraine la perte des infos déjà renseignées.

Identification du client et creation du dossier​

Dans cette seconde étape, on va proposer au client de se logger ou de créer un compte, s'il n'est pas déjà connecté. Une fois l'utilisateur connecter, on lui propose un écran pour modifier ses infos de contact: adresse, téléphone, etc. À la validation de se formulaire, deux actions vont se déclancher successivement.

Dans un premier temps, on va inserer les informations de l'utilisateur comme premier voyageur dans le cookie. Puis on va transformer les choix de l'utilisateur en un dossier de réservation via le service XFT Create Availability.

Choix de paiement​

Sur cette dernière étape, le client a un dossier en cours, la chambre lui est réserver pour 45 min en attendant son paiement. Le client va pouvoir renseigner ses préférences de paiement: Bon d'achat / code promo, avoir. Mais aussi différentes modalités de paiement: payer plus tard, payer la totalité, payer un accompte, choix du mode de paiement.

On va faire appel au service XFT Update Booking pour enregistrer les choix du client dans son dossier.

Pour calculer les modalités de paiement pour la réservation, on fait appel au service XFT Calculate Payment. Ce servicec nous retourne diverse informations comme la date et montant d’acompte, pour solder le dossier ou les différentes dates d’échéance et leur montant correspondant s’il existe un échéancier.

Une règle middleware à été mise en place vis-à-vis du cookie. En effet, quand on se rend sur une url du tunnel (qui match le pattern suivant /^\/tunnel\/.*/), on va vérifier la présence du token. Il est en effet nécéssaire afin de communquer avec les service XFT mentionné ci-dessus. Si on se rend sur une page tunnel sans cookie, on est redirigé vers la homepage.

Si on quitte le tunnel sans avoir créer de dossier, donc sans être aller jusqu'au dernier écran du tunnel, le middleware va aller supprimer le cookie si il n'y a pas de booking number (clé refNumber)

Paiement​

Afin d'encaisser le paiement, on va diviser le procéssus en 3 étapes:

  • Transmettre à Worldline les informations du dossier et les choix du client pour créer la page de paiement
  • Page de paiement hébergée par Worldline (rien à gérer de notre côté)
  • Les traitements du retours de Worldline

Création de la HostedCheckout Page de Wordline​

Tout le process de paiement est géré par via les services de Worldline, formulaire CB, enregistrer une carte, validation des informations, réaliser la transaction. Dans cette étape, il nous faut transformer les choix du client et les infos du dossier en une configuration que l'on transmet ensuite à Worldline via l'api Create hosted checkout. Cet appel nous retourne une url vers laquelle rediriger le client pour procéder au paiement.

La configuration peut se décomposer en deux blocs à fusionner

Create Hosted Checkout: configuration commune​

Voici le bloc de configuration commun à tout les modes de paiement

{
  "order": {
    "amountOfMoney": {
      "amount": 10000, // montant en centimes
      "currencyCode": "EUR" // devise
    },
    "references": {
      // référence du paiement custom, pour matcher la config v3
      "merchantReference": "2148094/2503/WEB/WOD_124512",
      // Contexte custom qui nous permettra de rattacher le paiement au dossier une fois le paiement réaliser. Format JSON stringifié
      "merchantParameters": "{\"refNumber\":\"2148094/2503/WEB/WOD\",\"timestamp\":\"124512\"}"
    }
  }
}

Create Hosted Checkout: moyen de paiement​

Chaque moyen de paiement va aller compléter le bloque de configuration ci-dessus. Ils ont tous des configurations différentes On retrouve leurs spécificité propre ici: Worldline moyens de paiements

Exemple: Cartes​

Pour les cartes, on utilise la configuration suivante

{
  "cardPaymentMethodSpecificInput": {
    "authorizationMode": "SALE" // stratégie de capture du paiement.
  },
  "hostedCheckoutSpecificInput": {
    "returnUrl": "https://odalys-vacances.com/tunnel/confirmation",
    "sessionTimeout": 45, // Timeout de paiement en minutes
    "allowedNumberOfPaymentAttempts": 3, // Nombre de tentative autorisé

    // les deux blocs ci dessous permette de traiter toutes les cartes de la même manière,
    // Et de laisser worldline déterminer lui-même le type de carte et les règles de validation
    // ex CVV visa 3 caractères vs amex 4 caractères.
    "cardPaymentMethodSpecificInput": {
      "groupCards": true
    },
    "paymentProductFilters": {
      "exclude": {},
      "restrictTo": {
        "groups": ["cards"],
        "products": []
      }
    }
  }
}
Exemple: ANCV​
{
  "hostedCheckoutSpecificInput": {
    "returnUrl": "https://odalys-vacances.com/tunnel/confirmation"
  },
  "redirectPaymentMethodSpecificInput": {
    "paymentProductId": 5403 // id du mode de paiement ANCV connect
  }
}

Hosted Checkout Page​

Nous n'avons rien a faire durant cette étape. Une fois le parcours terminer, Worldline va déclancher 2 opérations en simultanée.

Worldline va rediriger le client vers la page de retour configurer précédement (returnUrl) avec en query params la référence du paiement hostedCheckoutId. On peut utiliser l'api Get Hosted Checkout pour récupérer le détail du paiememt.

Dans le même temps, Worldline envoie un évènement Webhook

Webhook MSPayment​

Le but de ce service est de recevoir les notifications de paiement et d'inscrire dans le dossier client les paiements capturé. On retoruvera ici la documentation des Webhook

Worldline dispatch des évènements pour nous notifier de toutes les activités de paiement, on retrouvera ici la liste des status

Il n'y en a qu'un seul qui nous intéresse : payment.captured Ce status signifie que le paiement est bien enregistré, et sera dispatché aux banques client à la fin de la période en cours (heure de cut-off, en général à minuit)

Si on reçoit ce status, c'est que tout c'est bien passé et qu'il nous faut enregistre le paiement dans XFT. Voici les différentes étapes réaliser par le web-service à la réception d'un statut payment.captured

  1. On s'assure d'avoir un contexte qu'on à défini à l'étape de création de la configiration du hosted checkout
  2. Conversion des ids de méthode de paiement worldline/iResa via le call à Boom /api/paymentMethods/getIresaId/from-worldline/1
  3. Vérification que le paiement n'existe pas déjà dans le dossier client via le webservice Flag FSCanAddPayment
  4. On ajoute le paiement au dossier client via le service XFT Create Payment

À chacune de ses étapes, si un check n'est pas validé, on à la possiblité de rembourser le client via l'api Cancel payment A faire, attention à l'heure de cut-off.

Configuration des Webhooks.​

Afin de rattacher un webhook à Worldline, sur le portail worldline, se rendre à la page suitante Configuration -> Information technique -> Paramètres API Dans la section Configuration Webhooks, renseigner l'url du endpoint à notifier.

Il faut configurer le service avec deux tokens:

  • WebhooksKey: clé publique
  • WebhooksKeySecret : clé privée

Afin de garantir la sécurité des notifications, Worldline ajoute également deux headers :

  • X-GCS-KeyId avec comme valeur WebhooksKey
  • X-GCS-Signature, un hash du body utilisant la valeur de WebhooksKeySecret

Lib Node.js fourni par Worldline: onlinepayments-sdk-nodejs