Cas d’utilisation

Voici une liste non exhaustive des cas d’utilisation qui se définissent lors de l’initialisation du paiement (lors de l’appel au web service Charge/createPayment).

Description
Transmettre le numéro de commande
Transmettre les données de l’acheteur
Transmettre les données de livraison
Transmettre le contenu du panier
Proposer l’enregistrement du moyen de paiement
Utiliser un moyen de paiement enregistré
Utiliser un moyen de paiement enregistré sans afficher le formulaire embarqué
Désactiver 3D Secure 1
Transmettre la préférence marchand
Augmenter les chances de frictionless en 3DS2
Créer des champs personnalisés
Surcharger l’URL de notification instantanée

Transmettre le numéro de commande

Pour transmettre le numéro de commande, utilisez le champ orderId :

{
  "orderId": "CX-1254"
}

Transmettre les données de l’acheteur

Le marchand peut transmettre l’adresse de facturation et les coordonnées de l’acheteur (adresse e-mail, civilité, numéro de téléphone etc.).

Ces données seront:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Acheteur),
  • retournées dans l’IPN, sans modification.

Pour cela, utilisez le champ customer:

Exemple

{
  "customer": {
    "reference": "C2383333540",
    "email": " sample@example.net",
    "billingDetails": {
      "category": "PRIVATE",
      "title": "M",
      "firstName": "Laurent",
      "lastName": "DURANT",
      "streetNumber": "109",
      "address": "rue de l'innovation",
      "zipCode": "31670",
      "city": "LABEGE",
      "country": "FR",
      "phoneNumber": "0123456789",
      "cellPhoneNumber": "0623456789"
    }
  }
}

Transmettre les données de livraison

Le marchand peut transmettre les données de livraison de l’acheteur (adresse, civilité, numéro de téléphone etc.).

Ces données seront:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Livraison),
  • retournées dans l’IPN, sans modification.

Exemple pour une livraison de type “Retrait en magasin”

L’adresse de livraison est celle du magasin.

L’adresse de facturation est différente de l’adresse de livraison.

Le nom du destinataire de la livraison est celui de l’adresse de facturation.

{
  "customer": {
    "shippingDetails": {
      "shippingMethod": "RECLAIM_IN_SHOP",
      "shippingSpeed": "STANDARD",
      "streetNumber": "230",
      "address": "avenue des Champs Elysées",
      "zipCode": "59170",
      "city": "CROIX",
      "country": "FR",
      "firstName": "Marie-Charlotte",
      "lastName": "GRIMALDI",
      "phoneNumber": "0328386789"
    }
  }
}

Exemple pour une livraison de type “point relais”

L’adresse de livraison est celle du point relais.

Le nom du point relais est transmis dans la deuxième ligne d’adresse de livraison.

L’adresse du point relais est transmise dans la première ligne d’adresse de livraison.

Le nom du destinataire est celui de l’adresse de facturation.

L’adresse de facturation est différente de l’adresse de livraison.

{
  "customer": {
    "shippingDetails": {
      "shippingMethod": "RELAY_POINT",
      "shippingSpeed": "STANDARD",
      "streetNumber": "100",
      "address": "avenue du parc Barbieux",
      "address2": "Pressing du Parc",
      "zipCode": "59170",
      "city": "CROIX",
      "country": "FR",
      "firstName": "Martine",
      "lastName": "DURAND",
      "phoneNumber": "0328386789",
      "deliveryCompanyName": "Chronospost"
    }
  }
}

Transmettre le contenu du panier

Lors de la création d’un paiement, le marchand peut transmettre le contenu du panier de l’acheteur.

Ces données seront visibles dans le Back Office Expert, dans le détail de la transaction (onglet Panier).

Pour celà, utilisez le champ cartItemInfo (tableau d’objets json) lors de l’appel au Web Service Charge/CreatePayment.

Exemple pour définir 2 articles dans le panier:

{
  "customer": {
    "shoppingCart": {
      "cartItemInfo": [
        {
          "productRef": "myRef1",
          "productAmount": "1200",
          "productLabel": "myLabel1",
          "productQty": "1"
        },
        {
          "productRef": "myRef2",
          "productAmount": "2400",
          "productLabel": "myLabel2",
          "productQty": "1"
        }
      ]
    }
  }
}

Remarques:

  • Le champ cartItemInfo est toujours retourné à vide dans la réponse.
  • Pour que l’onglet Panier s’affiche correctement dans le Back Office Expert, vous devez transmettre au minimum le champ productAmount de chaque produit.

Proposer l’enregistrement du moyen de paiement

Le marchand peut proposer à l’acheteur de faciliter ses achats en demandant l’enregistrement des données bancaires par la plateforme de paiement.

Grâce à cette opération, la plateforme de paiement attribue un jeton unique au moyen de paiement et le retourne au site marchand via le champ paymentMethodToken.

Ainsi lors de futurs achats, l’acheteur n’aura plus à saisir son moyen de paiement.

Cette solution apporte un niveau supplémentaire de sécurité aux paiements puisque seul transite le token utilisable uniquement par la plateforme de paiement.

Pour proposer à l’acheteur d’enregistrer son moyen de paiement au moment du paiement, utilisez le champ formAction avec la valeur ASK_REGISTER_PAY

{
  "formAction": "ASK_REGISTER_PAY",
  "customer": {
    "email": " sample@example.net"
  }
}

Remarque

Le champ email devient obligatoire lors de l’enregistrement du moyen de paiement.

Lors de l’affichage du formulaire, une case à cocher apparaitra.

Par défaut, cette case est décochée.

Si l’acheteur accepte l’enregistrement de son moyen de paiement, il doit cocher la case.

Si le paiement est refusé, le moyen de paiement ne sera pas enregistré.

Forcer l’enregistrement du moyen de paiement

Si le marchand a avertit l’acheteur plus tôt dans le process d’achat, il peut “forcer” l’enregistrement du moyen de paiement sans afficher de case supplémentaire.

Pour celà, utilisez le champ formAction avec la valeur REGISTER_PAY:

{
  "formAction": "REGISTER_PAY",
  "customer": {
    "email": " sample@example.net"
  }
}

Utiliser un moyen de paiement enregistré

Le marchand peut transmettre le token à débiter lors de l’initialisation du paiement.

Lors de l’affichage du formulaire, les champs kr-pan et kr-expiry seront automatiquement renseignés. L’acheteur n’aura plus qu’à saisir son code de sécurité (CVV) pour finaliser son achat.

Pour celà, il suffit de transmettre le token à débiter dans le champ paymentMethodToken et de valoriser le champ formAction à PAYMENT.

Cette valeur étant la valeur par défaut, le champ formAction n’est plus nécessaire.

{
    "formAction" : "PAYMENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Utiliser un moyen de paiement enregistré sans afficher le formulaire embarqué

Lorsque l’acheteur souhaite faire un nouvel achat, le marchand peut, s’il le désire, proposer la liste des moyens de paiement enregistrés pour ce client. Pour cela, il affiche sur sa page le pan masqué et la date de validité qui lui ont été retournés lors de l’enregistrement du ou des moyens de paiement. L’acheteur sélectionne le moyen de paiement à utiliser et le marchand initialise le paiement avec le token associé.

Afin de ne pas faire apparaitre le formulaire embarqué, il suffit d’utiliser le paramètre formAction et de le valoriser à SILENT:

{
    "formAction" : "SILENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Remarque

  • Ce cas d’utilisation n’utilise pas le client JavaScript, mais uniquement un appel serveur à serveur. Il n’y a pas de redirection vers l’url de retour spécifiée dans kr-post-url-success.
  • La réponse ne contient pas de formToken mais directement un objet Transaction.
  • En fonction de la configuration de votre boutique concernant les paiements par alias, il est possible que la saisie du CVV ou l’authentification 3D Secure soit requise. Dans ce cas, le mode SILENT ne peut convenir.

Désactiver 3D Secure 1

Cette fonctionnalité nécessite la souscription de l’option 3D Secure sélectif.

Le marchand peut indiquer s’il souhaite activer ou désactiver le processus d’authentification forte (3D Secure ou Safekey par exemple) lors d’un appel au web service charge/createPayment.

Pour celà, utilisez le champ strongAuthentication.

Remarque

Désactiver 3D Secure aura pour conséquence la perte du transfert de responsabilité. En cas de litige ou constestation de l’acheteur, les éventuels frais pourront être imputés au marchand.

{
  "strongAuthentication": "DISABLED"
}

Transmettre la préférence marchand

Avec 3DS2, il ne sera plus possible de désactiver le 3DS. Cependant, le marchand pourra demander une exemption dans sa requête de paiement (on parle de “préférence du marchand”). Pour celà, utilisez le champ strongAuthentication.

Valeur Description 3DS1 Description 3DS2
ENABLED

Active (si possible) l'authentification forte.

Dépréciée. Cette valeur sera interprétée comme CHALLENGE_REQUESTED.

DISABLED

Désactive (si possible) l'authentification forte. Nécessite l'option "3DS1 Sélectif".

La désactivation ne sera pas prise en compte si le moyen de paiement requiert obligatoirement une authentification forte. C'est le cas pour les cartes MAESTRO.

Permet de demander une authentification sans interaction (frictionless). Nécessite l'option "Frictionless 3DS2".

  • Pour les paiements réalisés en euro, si le montant est inférieur à 30€, une demande de frictionless est transmise au DS. Si la demande de frictionless est acceptée par l'émetteur, le marchand perd la garantie de paiement.

  • Pour les paiements réalisés en euro, si le montant est supérieur à 30€, la valeur transmise par le marchand est ignorée et la gestion de l'authentification du porteur est déléguée à la plateforme.

  • Pour les paiements réalisés dans une devise différente de l'euro, une demande de frictionless est transmise au DS.

Si la boutique ne dispose pas de l'option "Frictionless 3DS2", la valeur transmise par le marchand est ignorée et la gestion de l'authentification du porteur est déléguée à la plateforme.

CHALLENGE_REQUESTED

Active (si possible) l'authentification forte.

Permet de demander une authentification forte pour la transaction.

CHALLENGE_MANDATE

Active (si possible) l'authentification forte.

Permet d'indiquer que pour des raisons règlementaires, une authentification forte est requise pour la transaction.

NO_PREFERENCE

Active (si possible) l'authentification forte.

Permet d'indiquer au DS que le marchand n'a pas de préférence. Si l'émetteur décide de réaliser une authentification sans interaction (frictionless), le paiement sera garanti.

AUTO

Valeur par défaut. Gestion de l’authentification 3DS déléguée à la plateforme de paiement (configuration du domaine, fournisseur, boutique).

Valeur par défaut. Gestion de l’authentification 3DS déléguée à la plateforme de paiement (configuration du domaine, fournisseur, boutique).

Augmenter les chances de frictionless en 3DS2

Lorsque tous les acteurs seront opérationnels, il sera possible de transmettre des données supplémentaires pour augmenter les chances de frictionless lors du paiement.

Liste des champs à transmettre

Paramètre Description
customer.email Adresse e-mail de l’acheteur
customer.billingDetails.identityCode Identifiant national. Permet d’identifier de façon unique chaque citoyen au sein d’un pays. CPF ou CNPJ au Brésil
customer.billingDetails.streetNumber Numéro de rue de l’adresse de facturation
customer.billingDetails.address Adresse postale
customer.billingDetails.address2 Deuxième ligne d’adresse
customer.billingDetails.zipCode Code postal
customer.billingDetails.city Ville
customer.billingDetails.state Etat / Région
customer.billingDetails.country Code pays suivant la norme ISO 3166 alpha-2
customer.billingDetails.phoneNumber Numéro de téléphone
customer.billingDetails.cellPhoneNumber Numéro de téléphone mobile
customer.shippingDetails.address Adresse postale
customer.shippingDetails.address2 Deuxième ligne d’adresse
customer.shippingDetails.zipCode Code postal
customer.shippingDetails.city Ville
customer.shippingDetails.state Etat / Région
customer.shippingDetails.country Code pays suivant la norme ISO 3166
customer.shippingDetails.shippingMethod Mode de livraison. De nouvelles valeurs spécifiques à 3DS2 seront bientôt disponibles
customer.shippingDetails.shippingSpeed Délai de livraison. De nouvelles valeurs spécifiques à 3DS2 seront bientôt disponibles

Transmettre des données personnalisées

Lors de la création d’un paiement, le marchand peut transmettre des informations spécifiques à la plateforme de paiement pour répondre à des besoins métier.

Par exemple, transmettre un numéro de dossier, un numéro de contrat etc…

Ces informations seront :

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Extras),
  • visibles dans l’e-mail de confirmation de paiement à destination du marchand,
  • retournées dans l’URL de notification, sans modification.

Pour celà, utilisez les champs metadata (au format json) lors de l’appel au Web Service Charge/CreatePayment:

Exemple pour transmettre une donnée nommée “contract” et sa valeur:

{
  "metadata": {
    "contract": "1245KL-78/ZE"
  }
}

Surcharger l’URL de notification instantanée

Vous pouvez surcharger l’URL de notification instantanée (également appelée IPN) dans le formulaire dans le cas où vous utilisez une seule boutique pour différents canaux de ventes, différentes typologies de paiement, différentes langues etc…

Cette fonctionnalité est incompatible avec l’exécution, depuis le Back Office Expert, de la requête envoyée à l’URL de notification instantanée.

L’URL appelée sera celle configurée dans la règle de notification (voir chapitre Paramétrer les notifications).

Utilisez le champ ipnTargetUrl lors de l’initialisation du paiement pour surcharger l’URL de la page à notifier.

Si la valeur du champ ipnTargetUrl est erronée, le formulaire ne sera pas rejeté.

{
    "ipnTargetUrl" : "https://my.site/my-ipn",
}