• France
état des services
démonstrations
assistance
FAQContacter le support
Video tutorials
Rechercher
Catégories
Tags
Français
Français
Anglais
Accueil
Cas d'usage
Créer un paiement
Créer un paiement en plusieurs fois
Proposer un paiement complémentaire
Créer un paiement par alias (token)
Créer un lien de paiement
Créer un abonnement
Gérer vos abonnements
Gérer vos transactions (rembourser,...)
Analyser vos journaux
Docs API
Formulaire embarqué
API REST
Formulaire en redirection
Intégration mobile
Échange de fichiers
Exemples de code
Moyens de paiement
Modules de paiement
Guides
Back Office Marchand
Guides fonctionnels

Cas d'utilisation

Voici une liste non exhaustive des cas d'utilisation avec la création du formToken (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
Transmettre les données du sous-marchand
Proposer l'enregistrement du moyen de paiement
Utiliser un moyen de paiement enregistré
Utiliser un moyen de paiement enregistré sans afficher le formulaire embarqué
Transmettre la préférence marchand
Augmenter les chances de frictionless en 3DS2
Surcharger l'URL de notification instantanée
Transmettre des données personnalisées

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",
            "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.

Nom du champ Format Description
subMerchantDetails.address1 ans..255 Adresse du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.address2 ans..255 Complément de l'adresse du sous-marchand.Transmis par le facilitateur de paiement.
subMerchantDetails.city an..128 Ville du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.companyType ans..60 Type de société du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.country a2 Code pays de l'adresse du sous-marchand (norme ISO 3166 alpha-2). Transmis par le facilitateur de paiement.
subMerchantDetails.facilitatorId ans..128 Identifiant du facilitateur de paiement. Transmis par le facilitateur de paiement.
subMerchantDetails.legalNumber ans..24 Numéro légal du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.mcc n4 Code MCC du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.mid n..64 Numéro de contrat (MID) du sous-marchand.Transmis par le facilitateur de paiement.
subMerchantDetails.name ans..255 Raison sociale du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.phoneNumber an..32 Numéro de téléphone du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.softDescriptor ans..255 Libellé (soft descriptor) du sous-marchand qui apparaît sur le relevé d'opérations bancaires de l'acheteur.Transmis par le facilitateur de paiement.
subMerchantDetails.state ans..128 Région de l'adresse du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.url ans..128 URL du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.zip an..64 Code postal du sous-marchand. Transmis par le facilitateur de paiement.

Proposer l'enregistrement du moyen de paiement

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas de créer un alias à partir d'un IBAN.

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

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas de créer un alias à partir d'un IBAN.

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é

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas d'utiliser un alias créé à partir d'un IBAN.

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é

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas d'utiliser un alias créé à partir d'un IBAN.

Ce mode permet de créer une transaction sans affichage du formulaire de paiement et sans authentification (appel de serveur à serveur).

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

Sans authentification, le marchand n'est pas protégé contre les risques de fraude et plus spécifiquement en cas de contestation du porteur de carte.

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.
  • Voir : Paiement 0 clic

Transmettre la préférence 3-D Secure

Utilisez le champ strongAuthentication (lien vers le playground : strongAuthentication).

Ce champ indique la préférence du marchand au sujet de l'authentification de l'acheteur.

  • Sans interaction du porteur (frictionless).
  • Avec interaction du porteur (authentification forte ou challenge).
  • Pas de préférence du marchand.

Dans tous les cas, la banque émettrice décide seule du mode d'authentification de l'acheteur.

Cas d'utilisation Valeurs possibles
Avec interaction du porteur : Challenge
  • ENABLED : Cette valeur est dépréciée.
  • CHALLENGE_REQUESTED : Cette valeur permet de demander une authentification forte pour la transaction.
  • CHALLENGE_MANDATE : Cette valeur permet de demander une authentification forte pour la transaction pour des raisons règlementaires.
Sans interaction du porteur : Frictionless
  • DISABLED : Cette valeur permet de demander une exemption à l'authentification forte.

    Avec l'option Frictionless 3DS2 :

    • Transactions à faible montant
    • Safe'R by CB

    Si la demande de Frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.

    Sans l'option Frictionless 3DS2, le choix de la préférence est délégué à l'émetteur de la carte (No Preference).


  • DATA_SHARE_ONLY : Réservée au Brésil et à l'amérique Latine. Cette valeur permet de demander une transaction sans interaction du porteur (ni authentification) mais pour laquelle le marchand souhaite partager les données via le processus 3DS avec l'émetteur pour réduire le risque de refus lors de l'autorisation.
Pas de préférence du marchand
  • NO_PREFERENCE : 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: Le choix de la préférence est délégué à l'émetteur de la carte (No Preference).

Tableau des exemptions pour le Frictionless (valeur DISABLED)

Exemption Description
Transactions à faible montant Pour les paiements en euro, vous pouvez demander une exemption à l'authentification forte :
  • Si le montant est inférieur à 30 EUR, et dans la limite soit de 5 opérations successives ou d’un montant cumulé inférieur à 100 EUR.
  • Si le montant est supérieur à 30 EUR, la valeur transmise par le marchand est ignorée et le choix de la préférence est délégué à l'émetteur de la carte ( No Preference ).
Pour les paiements réalisés dans une devise différente de l'euro, une demande de frictionless est transmise à l'émetteur. Si la demande de frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.
Safe'R by CB

    Le programme Safe'R by CB a pour objectif de répondre aux attentes des marchands à très faible risque et à la volumétrie importante (120.000 transactions CB / an).

    Vous pouvez demander une exemption à l'authentification forte :

    • Si le montant est inférieur à 100 EUR, l'exemption est systématique pour les marchands éligibles.
    • Si le montant est compris entre 100 EUR et 250 EUR, une expérimentation est en cours. Le marchand doit remplir ces conditions :
      • Avoir un contrat CB.
      • Être éligible à la TRA acquéreur.
      • Transmettre les valeurs requises dans le flux 3-D Secure, selon les règles définies par la plateforme.
    Si la demande de frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.

    Pour bénéficier du programme Safe'R by CB, vous devez contacter votre conseiller clientèle Société Générale pour obtenir un accord explicite.

Augmenter les chances de frictionless en 3DS2

Transmettez ces données pour augmenter les chances de frictionless lors du paiement.

L'utilisation de ces champs est optionnelle. Dans tous les cas, c'est la banque émettrice qui décide si une authentification forte doit être réalisée.

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.
customer.shippingDetails.shippingSpeed Délai de livraison.

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>",
}
© 2025 Tous droits réservés à Sogecommerce
25.20-1.11