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).
Pour transmettre le numéro de commande, utilisez le champ orderId :
{ "orderId": "CX-1254" }
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:
{ "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" } } }
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.
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" } } }
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" } } }
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
Pour celà, utilisez le champ cartItemInfo (tableau d’objets json) lors de l’appel au Web Service Charge/CreatePayment.
{ "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.
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é.
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" } }
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", }
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.
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" }
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".
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). |
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.
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 |
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" } }
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
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", }