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

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 Marchand, 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 Marchand, 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 Marchand, 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 Marchand, vous devez transmettre au minimum le champ productAmount de chaque produit.

Transmettre les données du sous-marchand

Le facilitateur de paiement peut transmettre les données du sous-marchand concerné par la transaction.

Ces données seront :

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

Le tableau décrit les champs communs disponibles avec les informations sur le sous-marchand.

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.

Transmettre la préférence marchand

Avec 3DS2, il ne sera pas possible de désactiver le 3DS. Le marchand doit demander une exemption dans sa requête de paiement (on parle de "préférence du marchand").

Pour celà, utilisez le champ strongAuthentication.

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

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 Marchand, 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 (déconseillé)

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 Marchand, 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>",
}