Si vous êtes un nouveau marchand, veuillez envisager l’utilisation de notre nouvelle interface pour ce mode d’intégration.

Consultez ses fonctionnalités et possibilités dans notre guide dédié.

Ingenico ePayments DirectLink vous permet d’établir des liens entre vos applications et notre système, comme si notre système était tout simplement un serveur local. Cela fournit un accès programme à programme (serveur à serveur) entre le logiciel du marchand et nos fonctions de paiement et d’administration. Le programme du marchand interagit directement avec notre API à distance, sans intervention humaine.

Le graphique ci-dessus représente une transaction avec DirectLink

En utilisant DirectLink, il n’y a aucun contact entre notre système et le client de notre marchand. Le marchand transmet toutes les informations requises pour effectuer directement le paiement à partir de notre système dans une requête HTTPS POST. Notre système demande la transaction financière (de manière synchrone ou asynchrone) à l’acquéreur pertinent et retourne la réponse au marchand dans un format XML. Le programme du marchand lit la réponse et reprend le traitement.
Le marchand est donc responsable pour la collecte et le stockage des détails confidentiels de paiement de son client. Il doit garantir la confidentialité et la sécurité de ces détails via l’utilisation de communication web encryptée et d’un serveur de sécurité.

Le marchand peut effectuer des nouvelles commandes, des maintenances sur des commandes existantes et des interrogations sur le statut d’une commande en particulier en utilisant DirectLink.

L’usage de requêtes automatisées en DirectLink par le marchand ne l’empêche pas de consulter manuellement l’historique des transactions dans son module de gestion, en utilisant son navigateur internet ou un téléchargement de rapport. Pour la configuration et le fonctionnement du site d’administration, veuillez vous référer au Utilisez votre compte Ingenico ePayments / Consultez vos transactions.

    Les procédures générales et contrôles de sécurité sont valides pour toutes les demandes DirectLink: nouvelles requêtes de commande, requêtes de maintenance et interrogations directes (direct queries).

    Le graphique ci-dessus représente les différentes étapes d’une transaction avec DirectLink

    Un utilisateur API (Application Program Interface) est nécessaire pour présenter des demandes DirectLink.

    En général, cet utilisateur est spécifiquement conçu pour qu’une application puisse présenter des demandes automatiques à la plateforme de paiement.

    Vous pouvez créer un utilisateur API dans votre compte Ingenico via « Configuration » > « Users » (Utilisateurs). Sélectionnez « New User » (Nouvel utilisateur) et remplissez les champs obligatoires.

    Pour que le nouvel utilisateur soit un utilisateur API, assurez-vous de cocher la case « Special user for API (no access to admin.) » (Utilisateur spécial API (aucun accès admin.)).

    Creation of an API user

    Bien que plusieurs profils d’utilisateur soient disponibles pour l’utilisateur API, nous vous recommandons vivement de configurer cet utilisateur sur le profil « Admin » (Administrateur).
    Si vous souhaitez limiter les droits de maintenance des transactions (remboursement, annulations, etc.), vous pourrez toujours modifier le profil utilisateur et le configurer sur « Encoder » (Encodeur), par exemple.

    En cas de doute, nous vous recommandons de choisir le profil « Admin », autrement, accédez à Profils d'utilsateur (Gestionnaire des utilisateurs).

    Le mot de passe d’un utilisateur API n’a pas besoin d’être modifié régulièrement. Ce qui est avantageux lorsque le mot de passe doit être codé en dur dans votre application. Nous vous recommandons néanmoins de changer de mot de passe de temps à autre.

    Pour en savoir plus sur les types d’utilisateur et sur la façon de modifier le mot de passe de l’utilisateur API, accédez à Types d'utilisateur (Gestionnaire des utilisateurs).

    Pour les requêtes de nouvelle commande, les requêtes de maintenance et les interrogations directes (direct queries), le marchand doit envoyer des requêtes avec certains paramètres vers des URLs spécifiques. Les paramètres de paiement/maintenance/interrogation doivent être envoyés dans une demande POST comme suit:

    PSPID=value1&USERID=value2&PSWD=value3&…

    Le sous-type (subtype) indiquant le type de média dans le champ header “Content-Type entity” dans la requête POST doit être encodé en "application/x-www-form-urlencoded".

    DirectLink fonctionne dans un mode “une requête-une réponse”, chaque paiement est traité individuellement. Notre système gère individuellement les requêtes de transaction via DirectLink et peut travailler simultanément (lorsque cette option est supportée techniquement), par exemple nous attendons la réponse de la banque avant de renvoyer une réponse XLM vers la requête.

    Lorsque nous recevons des requêtes sur nos serveurs, nous vérifions le niveau de cryptage ainsi que l’adresse IP à partir de laquelle la requête a été envoyée.

    DirectLink est construit sur un protocole de communication sécurisé et robuste. L’API DirectLink est un ensemble d’instructions soumises avec des requêtes HTTPS POST classiques. Nous permettons aux marchands de se connecter à nous dans un seul mode https sécurisé.
    Il n’est pas nécessaire d’utiliser un certificat client TLS.

    La signature SHA est basée sur le principe même que le serveur du marchand génère une chaîne unique de caractères pour chaque commande, hachée avec les algorythmes SHA-1, SHA-256 u SHA-512. Le résultat de ce hachage nous est envoyé dans la requête de commande du marchand. Notre système reconstruit la signature afin de vérifier l’intégrité des données de commande qui nous ont été envoyées dans la requête.

    Cette chaîne est construite en concaténant les valeurs des champs envoyés avec la commande (triés alphabétiquement, dans le format ‘paramètre=valeur’), avec chaque paramètre et valeur suivis d’une passphrase. La passphrase est définie dans l’Information Technique du marchand, dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink”. Pour la liste complete des paramètres à inclure dans le Digest SHA, veuillez cliquer ici. A noter que ces valeurs sont toutes sensibles à la casse lorsqu’elles sont assemblées pour former la chaîne avant le hachage!

    Important
    • Tous les paramètres que vous envoyez (et qui apparaissent dans la Liste des Paramètes à inclure dans le calcul du SHA-IN), seront inclus dans la suite (string) à hacher.
    • Tous les noms de paramètres devraient être en MAJUSCULES (Afin d’éviter toute confusion)
    • Les paramètres doivent être triés par ordre alphabétique
    • Les paramètres qui n’ont pas de valeur ne devraient PAS être inclus dans la suite (string) à hacher
    • Lorsque vous optez pour le transfert du compte de test en production en utilisant le lien dans votre compte, une passphrase SHA-IN aléatoire sera automatiquement configurée dans votre compte de production.
    • Par mesure de sécurité, nous vous invitons à utiliser des mots de passe SHA différents en TEST et PROD. Veuillez noter que si identiques dans les deux environnements, votre passphrase en TEST serait changée par notre système (vous en seriez bien entendu notifié).

    Lorsque vous hachez la suite (string) composé par l’algorythme SHA, un résumé hexadécimal sera renvoyé. La longueur de ce résumé SHA est de 40 caractères pour le SHA-1, 64 pour le SHA-256 et 128 pour le SHA-512. Ce résultat devrait être envoyé à notre système dans votre requête de commande, en utilisant le champ “SHASign”.

    Notre système recomposera lui-même la suite (string) SHA en se basant sur les paramètres reçus et comparera le résumé (digest) du marchand avec le résumé (digest) que nous avons généré. Si le résultat n’est pas identique, la commande sera refuse. Ce contrôle garantit l’exactitude et l’intégrité des données de commande.

    Vous pouvez tester votre signature SHA ici.

    Exemple de calcul d’un SHA-1-IN avec les seuls paramètres de base

    Paramètres (par ordre alphabétique)
    AMOUNT: 15.00 -> 1500
    CARDNO: 4111111111111111
    CURRENCY: EUR
    OPERATION: RES
    ORDERID: 1234
    PSPID: MyPSPID

    SHA Passphrase (Dans "Information Technique"):
    Mysecretsig1875!?

    String à hacher
    AMOUNT=1500Mysecretsig1875!?CARDNO=4111111111111111Mysecretsig1875!?CURRENCY=EURMysecretsig1875!?
    OPERATION=RESMysecretsig1875!?ORDERID=1234Mysecretsig1875!?PSPID=MyPSPIDMysecretsig1875!?

    Résumé de résultat (SHA-1)
    2B459D4D3AF0C678695AE77EE5BF0C83CA6F0AD8

    Si le signature SHA envoyé dans votre requête ne correspond pas au SHASIGN que nous avons récupéré en utilisant les details de la commande ainsi que la passphrase entrée dans le champ Signature SHA-IN dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink” dans la page d’Information Technique, vous recevrez le message d’erreur “unknown order/1/s/".

    Si le champ "SHASIGN" dans votre requête est vide, mais qu’une passphrase a été entrée dans le champ Signature SHA-IN dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink” dans la page d’Information Technique (indiquant ainsi que vous voulez utilise une signature SHA pour chaque transaction), vous recevrez le message d’erreur “unknown order/0/s/".

    Pour chaque requête, notre système vérifie l’adresse IP à partir de laquelle la requête a été envoyée afin de s’assurer que les requêtes ont bien été envoyées à partir du serveur du marchand. Dans le champ adresse IP de l’onglet "Contrôle de données et d’origine”, dans la section "Contrôles pour DirectLink" de la page Information technique de votre compte, vous devez entrer l’adresse IP ou le groupe d’adresse IP des serveurs qui envoient vos requêtes.

    Si l’adresse IP à partir de laquelle la requête a été envoyée n’a pas été déclarée dans le champ d’adresse IP de l’onglet “Contrôle de données et origine”, à vérifier dans la section DirectLink de la page d’information technique de votre compte, vous recevrez le message d’erreur “unknown order/1/i”. L’adresse IP à partir de laquelle la requête a été envoyée sera également montrée dans le message d’erreur.

    Nous retournerons une réponse XML à votre requête. Veuillez vous assurer que vos systèmes sont bien en mesure de faire du parsing en recevant la réponse XML de manière aussi tolérante que possible afin d’éviter tout problème dans le futur, par exemple éviter les noms d’attributs sensibles à la casse, ne pas convenir d’un ordre spécifique pour les attributs retournés dans les réponses, s’assurer que les nouveaux attributs dans la réponse ne causeront pas de problème, etc.

    • L’URL de la requête dans l’environnement de TEST est https://ogone.test.v-psp.com/ncol/test/orderdirect.asp.
    • L’URL de la requête dans l’environnement de PRODUCTION est https://secure.ogone.com/ncol/prod/orderdirect.asp.

    Remplacer "test" par "prod"

    N’oubliez pas de remplacer “test” par “prod” dans l’URL de la requête lorsque vous passez à votre compte de PRODUCTION. Si vous oubliez de changer l’URL de requête, lorsque vous commencerez à traiter des commandes réelles, vos transactions seront envoyées vers l’environnement de test et ne seront pas envoyées vers les acquéreurs/banques.

    Le tableau ci-dessous contient les paramètres de requête nécessaires à l’envoi d’une nouvelle commande:

    Format: AN= Alphanumérique / N=Numérique, le nombre maximum de caractères autorisés
    Champ Usage
    PSPID

    Votre nom d’affiliation dans notre système.

    Format: AN, 30

    Obligatoire

    ORDERID

    Votre numéro de commande unique (référence marchand).

    Format: AN, 40

    Obligatoire

    USERID

    Nom de votre utilisateur applicatif (API). Veuillez vous référer à la documentation User Manager pour plus d’informations sur comment créer un utilisateur API.

    Format: AN, 20 (min. 2)

    Obligatoire

    PSWD

    Mot de passe de l’utilisateur API (USERID).

    Format: AN

    Obligatoire

    AMOUNT

    Montant à payer MULTIPLIE PAR 100, puisque le format du montant ne doit pas contenir de décimales or tout type de séparateur.

    Format: N, 15

    Obligatoire

    CURRENCY

    Code devise de la commande en format ISO alpha, par exemple: EUR, USD, GBP, CHF, etc.

    Format: AN, 3

    Obligatoire

    CARDNO

    Numéro de Carte/Compte.

    Format: AN, 21

    Obligatoire

    ED

    Date d’expiration.

    Format: MM/AA ou MMAA

    Obligatoire

    COM

    Description de la Commande.

    Format: AN, 100

    Optionnel

    CN

    Nom du client.

    Format: AN, 35

    Obligatoire

    EMAIL

    Adresse e-mail du client. Si vous faites une demande de 3DSv2.1, assurez-vous que le format d’email soit valide. Dans le cas contraire, l’authentification client forte utilisera le protocole 3DSv1.0.

    Format: AN, 50

    Optionnel

    SHASIGN

    Signature (suite (string) hachée) pour authentifier les données (cfr. SHA-IN Signature).

    Format: AN, 128

    Optionnel

    CVC

    Code de Vérification de la Carte (CVC - Card Verification Code). En fonction du type de carte, le code de vérification sera un code de 3 ou 4 chiffres, situé à l’avant ou à l’arrière de la carte, un numéro d’émission, une date de début ou une date de naissance.

    Format: N, 5

    Obligatoire

    ECOM_PAYMENT_
    CARD_VERIFICATION

    Alternative au CVC: date de naissance / numéro d’émission / etc. (en function du pays/de la banque)

    Format: N, 5

    Obligatoire

    OWNERADDRESS

    Nom de rue et numéro du client.

    Format: AN, 50

    Optionnel

    OWNERZIP

    Code postal du client.

    Format: AN, 10

    Optionnel

    OWNERTOWN

    Nom de la ville du client.

    Format: AN, 40

    Optionnel

    OWNERCTY

    Pays du client, par exemple BE, NL, FR, etc.

    Format: AN, 2

    Optionnel

    OWNERTELNO

    Numéro de téléphone du client.

    Format: AN, 30

    Optionnel

    OPERATION

    Définit le type de transaction demandée.

    Vous pouvez configurer une opération par défaut (procédure de paiement) dans l’onglet "Paramètres de transaction globaux", section "Code d’opération par défaut" de la page d’Information technique. Lorsque vous envoyez une valeur d’opération dans la requête, celle-ci écrasera la valeur par défaut.

    Valeurs possibles:
    • RES : demande d’autorisation
    • SAL : demande de vente directe
    • RFD: remboursement, non lié à un paiement précédemment effectué, donc pas une opération de maintenance sur une transaction existante (vous ne pouvez pas utilise cette opération sans permission spécifique de votre acquéreur).

    Optionnel:

    • PAU: demande de pré-autorisation:
      En accord avec votre acquéreur vous pouvez utiliser ce code d’opération pour réserver temporairement des fonds sur la carte d’un client. Ceci est une pratique courante dans les industries liées au voyage et à la location.
      Le code PAU/pré-autorisation ne peut actuellement être utilisé que pour les transactions MasterCard et n’est supporté que par quelques acquéreurs. Ce code d’opération ne peut pas être défini comme valeur par défaut dans votre compte Ingenico ePayments.
      Si vous deviez utiliser le code PAU pour des transactions avec des acquéreurs ou des types de carte qui ne supportent pas la pré-autorisation, ces transactions ne seraient pas bloquées, mais traitées comme des autorisations classiques (RES).

    Format: AN, 3

    Obligatoire

    WITHROOT

    Ajoute un élément racine à votre réponse XML. Valeurs possibles: ‘Y’ ou vide.

    Format: Y ou <empty>

    Optionnel

    REMOTE_ADDR

    Adresse IP du client (Seulement pour le module de détection de fraude (FDM). Si une vérification de pays ne doit pas être effectuée sur l’adresse IP, envoyez “NONE”.

    Format: AN

    Optionnel

    RTIMEOUT

    Timeout de requête pour la transaction (en secondes, valeur entre 30 et 90)
    Important: La valeur que vous configurez ici doit être inférieure à la valeur du timeout dans votre propre système!

    Format: N, 2

    Optionnel

    ECI

    Indicateur Electronique de Commerce (Electronic Commerce Indicator).

    Vous pouvez configurer une valeur ECI par défaut dans l’onglet “Paramètres de transaction globaux”, section “valeur ECI par défaut” de la page d’Information Technique. Lorsque vous envoyez une valeur ECI dans la requête, celle-ci écrasera la valeur ECI par défaut.

    Valeurs (numériques) possibles:
    0 - Carte passée dans le terminal
    1 - Vente à distance classique (MOTO) (carte non présente)
    2 - Paiements périodiques provenant de VAD
    3 - Paiements étalés
    4 - Entrée manuelle, carte présente
    7 - E-commerce avec chiffrement SSL
    9 - Paiements périodiques issus du e-commerce

    Format: N, 2

    Optionnel


    Si vous traitez des paiements récurrents, vous devez ajouter les paramètres Credentials-on-file (COF) à votre demande.

    Consultez notre guide Alias Manager pour tout savoir sur le traitement des transactions COF.



    La liste des paramètres possible à envoyer peut être plus longue pour les marchands qui ont actives certaines options/fonctionnalités dans leurs comptes. Veuillez vous référer à la documentation relative à chaque option pour plus d’informations concernant les paramètres additionnels liés à cette option.

    Les paramètres de requêtes suivants sont obligatoires pour les nouvelles commandes:

    • PSPID et USERID
    • PSWD
    • ORDERID
    • AMOUNT (x 100)
    • CURRENCY
    • CARDNO
    • ED
    • CVC
    • OPERATION


    Respect du choix de marque de votre client pour les cartes co-badgées

    Dans certains cas, une carte de crédit d’un établissement international (c.-à-d. Visa / MasterCard) est également émise en tant que deuxième méthode de paiement locale. Ce type de carte de crédit est appelé des cartes co-badgées.

    Si vous proposez des méthodes de paiement locales en plus des établissements internationaux, vous devez laisser vos clients choisir parmi les marques pour lesquelles une carte co-badgée est émise

    Pour ce faire, assurez-vous que

    • Le paiement local est disponible dans votre Back Office sous Configuration > Méthodes de paiement. Si vous proposez Visa / MasterCard via un acquéreur français, nous avons déjà ajouté Carte Bancaire (CB) pour vous. Notre service clients se fera un plaisir de vous aider à ajouter des méthodes de paiement supplémentaires
    • Vos clients peuvent choisir parmi différentes marques dans votre boutique en ligne et que le formulaire de paiement est adapté en conséquence de votre côté. Utilisez les paramètres PM / BRAND pour indiquer le choix de votre client (Vous trouverez une liste de toutes les valeurs disponibles pour ces paramètres dans le Back Office).


    Une page de test pour une nouvelle commande peut être trouvée à l’adresse: https://ogone.test.v-psp.com/ncol/test/testodl.asp.

    Si vous désirez qu’un client ne soit pas en mesure de payer en utilisant un ou plusieurs moyens de paiement, vous pouvez utiliser un paramètre à cet effet.

    Ceci est particulièrement utile pour les sous-types de carte, spécialement lorsque vous désirez accepter un type de carte (ex.: MasterCard), mais pas les sous-types qui lui sont associés (ex.: Maestro).

    Le paramètre est le suivant:

    Champ Usage
    EXCLPMLIST Liste des moyens de paiement et/ou types de carte de crédit qui ne doivent PAS être utilisés, séparés par un “;” (point virgule).

    Si un client essaie de payer avec une carte liée à un moyen de paiement et/ou un (sous) type de carte que vous avez exclu en utilisant le paramètre EXCLPMLIST, le message d’erreur “Card number incorrect or incompatible” (Numéro de carte incorrect ou incompatible) sera retourné dans le champ NCERRORPLUS.

    Notre système supporte l’usage de 3-D Secure à travers DirectLink.

    Important

    • Si vous désirez utiliser 3-D Secure avec DirectLink, vous devez obligatoirement avoir l’option D3D activée dans votre compte.
    • Certaines banques acquéreurs exigent l’utilisation du 3-D Secure. Veuillez vérifier avec votre acquéreur si tel est le cas pour vous.

    La fonctionnalité consistant à subdiviser VISA et MasterCard en méthodes de paiement par débit et par crédit vous permet de les offrir à vos clients sous deux formes (p. ex. VISA Debit et VISA Credit), mais vous pouvez aussi décider de n'accepter qu'une seule de ces deux formes de paiement.

    Pour pouvoir utiliser cette fonctionnalité de subdivision en cartes de crédit et de débit via DirectLink, vous devez inclure le paramètre CREDITDEBIT dans les champs masqués que vous envoyez à la page de paiement (et les inclure également, par conséquent, dans le calcul SHA-IN !).

    Champ Format
    CREDITDEBIT "C": credit card (carte de crédit)
    "D": debit card (carte de débit)

    Erreur liée : Si l'acheteur sélectionne la méthode par carte de débit, mais entre ensuite un numéro de carte de crédit, un code d'erreur est renvoyé : « Marque/mode de paiement incorrect ».

    Si le paiement est traité avec succès avec le paramètre CREDITDEBIT, ce même paramètre est également renvoyé dans la réponse XML, et / ou peut être demandé avec une requête directe. Cependant, si les valeurs soumises sont C ou D, les valeurs de retour sont « CREDIT » ou « DEBIT ».

    Vous trouverez également ces valeurs de retour dans la vue d'ensemble de la transaction via « View transactions » et « Financial history », ainsi que dans les rapports que vous pouvez télécharger ensuite.

    Configuration au sein de votre compte

    La fonctionnalité de subdivision peut également être activée et configurée par méthode de paiement dans votre compte Ingenico ePayments. Accédez à Subdivision en cartes de crédit/débit pour plus d'informations.


    Consultez notre guide Alias Manager pour tout savoir sur le traitement des transactions COF.

    Notre serveur retourne une réponse XML à la requête:

    Exemple d’une réponse XML à une requête de commande

    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS=”5” ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA"/>

    Le tableau ci-dessous contient une liste des attributs de tag de type ncresponse:

    ChampUsage
    ACCEPTANCE Code de réception retourné par l’acquéreur.
    amount Montant de la commande (non multiplié par 100).
    BRAND Type de carte ou information pour d'autres moyens de paiement.
    currency Devise de la commande.
    ECI Indicateur Electronique de Commerce.
    NCERROR Code d’erreur.
    NCERRORPLUS Explication du code d’erreur.
    NCSTATUS Statut lié au code NCERROR
    orderID Votre référence de paiement.
    PAYID Référence de paiement dans notre système.
    PM Moyen de paiement.
    STATUS Statut de la transaction. (Statuts possibles)

    La liste des attributs peut être plus longue pour les marchands qui ont activés certaines options (par exemple, le module de détection de fraude) dans leurs comptes. Veuillez vous référer à la documentation relative à chaque option pour plus d’informations concernant les attributs de réponses additionnels liés à cette option.

    Si vous effectuez une requête pour un orderID existant et ayant déjà été utilisé (et traité correctement), notre réponse XML contiendra le PAYID correspondant à l’orderID existant, la valeur ACCEPTANCE donnée par l’acquéreur lors du traitement précédent, le STATUS (statut) “0” ainsi que le NCERROR “50001113”.

    Une requête de maintenance directe envoyée de votre application vous permet de:

    • effectuer automatiquement une saisie de données (paiement) d’une commande autorisée (plutôt que manuellement dans votre module de gestion (back-office))
    • annuler une autorisation liée à une commande
    • renouveler une autorisation liée à une commande
    • rembourser une commande payée.

    Les saisies de données, annulations d’autorisation et renouvellements d’autorisation sont réservés spécifiquement aux marchands qui ont configuré leur compte/requêtes pour effectuer des autorisations et des saisies de données en deux étapes.

    • l’URL de requête dans l’environnement de TEST est https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp.
    • l’URL de requête dans l’environnement de PRODUCTION est https://secure.ogone.com/ncol/prod/maintenancedirect.asp.

    Important

    N’oubliez pas de remplacer “test” par “prod” dans l’URL de la requête lorsque vous passez à votre compte de PRODUCTION. Si vous oubliez de changer l’URL de requête, lorsque vous commencerez à traiter des commandes réelles, vos transactions seront envoyées vers l’environnement de test et ne seront pas envoyées vers les acquéreurs/banques.

    Le tableau ci-dessous comprend les paramètres de requête obligatoires afin d’effectuer une opération de maintenance:

    Champ Usage
    AMOUNT
    Montant de la commande multiplié par 100. Celui-ci est seulement obligatoire lorsque le montant de la maintenance diffère du montant de l’autorisation initiale. Cependant, nous recommandons son utilisation dans tous les cas.
    Notre système vérifiera que le montant de la transaction de maintenance n’est pas supérieur au montant de l’autorisation/du paiement.
    OPERATION

    Valeurs possibles:

    • REN: renouvellement d’autorisation, si l’autorisation originale n’est plus valide.
    • DEL: annulation d’autorisation, en laissant la transaction ouverte pour d’autres opérations de maintenance potentielles.
    • DES: annulation d’autorisation, en clôturant la transaction après cette opération.
    • SAL: saisie de données partielle (paiement), en laissant la transaction ouverte pour d’autres saisies de données potentielles.
    • SAS: (dernière) saisie partielle ou totale de données (paiement), en clôturant la transaction (pour d’autres saisies de données) après la saisie de données.
    • RFD: remboursement partiel (d’une commande payée), en laissant la transaction ouverte pour d’autres remboursements potentiels
    • RFS: (dernier) remboursement partiel ou total (d’une commande payée), en clôturant la transaction après ce remboursement.

    A noter que les opérations DEL et DES (annulations d’une autorisation) ne sont pas supportées par tous les acquéreurs, nous enverrons malgré tout une simulation d’annulation d’autorisation dans le module de gestion (back-office).

    ORDERID Vous pouvez envoyer le PAYID ou l’ORDERID afin d’identifier la commande originale. Nous recommandons l’utilisation du PAYID.
    PAYID
    PSPID PSPID de votre compte Ingenico ePayments
    PSWD Le mot de passe du USERID
    SHASIGN Calcul de hachage SHA, pour authentifier les données (cfr. Signature SHA-IN)
    USERID Utilisateur API

    Un exemple (page de test) d’une demande de maintenance directe peut être trouvé à l’adresse: https://ogone.test.v-psp.com/ncol/test/testdm.asp

    Notre serveur retourne une réponse XML à la requête:

    Exemple d’une réponse XML à une requête de maintenance directe:
    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/>

    Le tableau ci-dessous comprend les attributs de tag ncresponse:

    ChampUsage
    ACCEPTANCE Code d’acceptance renvoyé par l’acquéreur
    AMOUNT Montant de la commande (non multiplié par 100)
    CURRENCY Devise de la commande
    NCERROR Code d’erreur
    NCERRORPLUS Explication du code d’erreur (NCERROR)
    NCSTATUS Statut lié au code NCERROR
    ORDERID Votre référence de commande
    PAYID Référence de paiement dans notre système
    PAYIDSUB L’ID de niveau dans l’historique des opérations de maintenance du PAYID
    STATUS Statut de la transaction (Statuts possibles)

    L’attribut de tag standard pour ncresponse sont identiques à ceux pour la réponse XML à une nouvelle commande, à l’exception de l’attribut additionnels PAYIDSUB.

    Si la maintenance est demandée deux fois pour la même commande, la seconde demande sera théoriquement refusée avec une erreur “50001127” (cette commande n’est pas autorisée), parce que la transaction initiale approuvée aura déjà modifié le statut de la commande.

    Une demande d’interrogation directe (direct query) à partir de votre application vous permet de demander le statut d’une commande automatiquement (plutôt que manuellement dans votre module de gestion (back-office)). Vous ne pouvez envoyer des interrogations qu’une à la fois, et ne recevrez qu’un nombre limité de données par rapport à cette commande.

    Si vous désirez plus d’informations sur la commande, vous pouvez vérifier la transaction dans le module de gestion (back-office) ou effectuer un téléchargement de fichier automatique ou manuel (cf. Consultez vos transactions et guide d’intégration avancé Batch).

    • L’URL de requête dans l’environnement de TEST est https://ogone.test.v-psp.com/ncol/test/querydirect.asp
    • L’URL de requête dans l’environnement de PRODUCTION est https://secure.ogone.com/ncol/prod/querydirect.asp

    Important

    N’oubliez pas de remplacer “test” par “prod” dans l’URL de requête lorsque vous passez votre compte en PRODUCTION.

    Le tableau ci-dessous comprend les paramètres de requête obligatoires pour effectuer une interrogation directe (direct query):

    Champ
    Usage
    ORDERID

    Vous pouvez envoyer le PAYID ou l’ORDERID afin d’identifier la commande originale. Nous recommandons l’utilisation du PAYID.

    PAYID
    PAYIDSUB
    Vous pouvez indiquer l’ID de niveau d’historique si vous utilise le PAYID pour identifier la commande originale (optionnel).
    PSPID
    PSPID de votre compte Ingenico ePayments
    PSWD
    Mot de passe de votre utilisateur API
    USERID
    Votre utilisateur API

    Un exemple (page de test) d’une requête d’interrogation directe (‘) peut être trouvé à l’adresse: https://ogone.test.v-psp.com/ncol/test/testdq.asp.

    Notre serveur renvoie une réponse XML à la requête:

    Exemple d’une réponse XML response à une interrogation directe (direct query):

    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55"/>

    Le tableau ci-dessous comprend une liste des attributs de tag “ncresponse”:

    Champ
    Usage
    ACCEPTANCE Code d’acceptance renvoyé par l’acquéreur
    amount Montant de la commande (non multiplié par 100)
    BRAND Type de carte ou information similaire pour d’autres moyens de paiement
    CARDNO Le numéro de carte de credit masqué
    currency Devise de la commande
    ECI Indicateur de Commerce Electronique (Electronic Commerce Indicator)
    IP Adresse IP du client, telle que détectée par notre système dans une intégration en mode 3 tiers, ou envoyée via une intégration en mode 2 tiers
    NCERROR Code d’erreur
    NCERRORPLUS Explication du code d’erreur
    NCSTATUS Statut lié au code NCERROR
    orderID Votre référence de commande
    PAYID Référence de paiement dans notre système
    PAYIDSUB L’ID de niveau dans l’historique des opérations de maintenance du PAYID
    PM Moyen de paiement
    STATUS Statut de la transaction

    Les paramètres du champ standards libellés ncresponse sont identiques à ceux pour la réponse XML à une nouvelle commande, à l’exception des attributs additionnels PAYIDSUB, CARDNO et IP.

    La liste des paramètres peut être plus longue pour les marchands qui ont activé certaines options (par exemple le module de détection de fraude) dans leurs comptes. Veuillez vous référer à la documentation spécifique à l’option pour obtenir plus d’informations sur les paramètres de réponse additionnels liés à ces options.

    Si les transactions pour lesquelles vous désirez vérifier le statut ont été traitées en mode Page de paiement hebergée, vous recevrez également les attributs additionnels suivants (dans la mesure où vous aviez envoyé dès le départ ces champs dans la transaction Page de paiement hebergée).

    Champ
    Usage
    complus*
    Une valeur que vous souhaitiez recevoir
    (paramplus content)*
    Les paramètres que vous désiriez recevoir et leurs valeurs

    * Cf. Paramètres du retour d'information variable (documentation Page de paiement hebergée)

    Exemple d’une réponse XML à une interrogation directe (direct query) pour une transaction Page de paiement hebergée

    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55" COMPLUS="123456789123456789123456789" SessionID="126548354" ShopperID="73541312"/>

    Le champ STATUS comprendra le statut de la transaction. (cf. Statuts possible).

    Seul le statut ci-dessous est spécifiquement lié à la recherche (query) elle-même:

    StatutNCERRORNCSTATUS Explication
    88 La recherche (query) sur querydirect.asp a échoué

    Les temps de réponse pour une requête de transaction DirectLink sont généralement de quelques secondes; certains acquéreurs peuvent, cependant, avoir des temps de réponse plus longs.

    Si vous n’avez pas reçu une réponse de notre système après 30 secondes, vous pouvez envoyer une requête à querydirect.asp, demandant le statut de votre transaction la plus récente à orderdirect.asp. Si vous recevez une réponse immédiate contenant le statut non final pour la transaction, il se pourrait qu’il y ait des problèmes chez l’acquéreur.

    Si vous n’avez pas reçu une réponse à cette interrogation directe (direct query) après 10 secondes, il se pourrait qu’il y ait des problèmes de notre côté. Vous pouvez répéter cette requête vers querydirect.asp toutes les 30 secondes jusqu’à ce que vous receviez une réponse dans les 10 secondes.

    A noter que :
    • Ce système de contrôle ne pourra pointer vers des problèmes de notre côté que s’il existe un contrôle de votre côté pour vérifier que les requêtes partent de vos serveurs correctement.
    • Un problème de notre côté ne sera pas nécessairement toujours causé par un downtime, mais pourrait également être le résultat de temps de réponse lents liés à des problèmes de base de données par exemple.
    • Veuillez utiliser ces contrôles de manière judicieuse afin d’éviter de bombarder nos serveurs avec des requêtes, sans quoi nous pourrions réduire votre accès à la page querydirect.asp.

    Important

    Afin de protéger notre système de surcharges non nécessaires, nous interdisons les contrôles préalables du système qui incluent l’envoi de fausses transactions ou d’interrogations (queries) systématiques, ainsi que les interrogations (queries) systématiques utilisées pour obtenir le retour d’information de transaction (transaction feedback) pour chaque transaction.

    En vertu des articles 12, 13 et 14 du RGPD, le responsable du traitement a l’obligation d’informer ses clients finaux du futur traitement de leurs données personnelles. Il indiquera le type de données personnelles utilisées pour une transaction spécifique (méthode de paiement sélectionnée, responsable du traitement des données, acquéreur, fraude, etc.). Le résultat doit être disponible et visible au moment de la collecte des données et le titulaire de la carte doit pouvoir le télécharger et l’imprimer. Conformément au RGPD, vous devez fournir ces informations à votre client avant qu’il ne valide sa transaction. Ces informations seront de préférence affichées sur la page de saisie des données de compte ou carte bancaire.
    La demande de politique de confidentialité ci-dessous vous permet de récupérer toutes les informations que vous devez indiquer à votre client sur nos services pour être en conformité avec le RGPD.

    • L’URL de demande dans l’environnement TEST est https://secure.ogone.com/ncol/test/privacy-policy.asp

    • L’URL de demande dans l’environnement PRODUCTION est https://secure.ogone.com/ncol/prod/privacy-policy.asp
    Remplacer « test » par « prod »
    Remplacez « test » par « prod » dans l’URL de demande pour passer au compte de production.

    Le tableau suivant contient les paramètres de demande obligatoires à envoyer à vos clients concernant l’utilisation de leurs informations à caractère personnel :

    Champ Format
    Description
    USERID Chaîne
    Votre utilisateur API
    PSWD Chaîne
    Votre mode de passe utilisateur API
    PSPID
    Chaîne
    PSPID de votre compte
    BRAND Chaîne (p. ex. Visa)

    Facultatif : marque du moyen de paiement
    Vous pouvez envoyer ce champ plusieurs fois pour obtenir immédiatement le résultat de plusieurs marques.
    • L’envoi d’aucune marque revient au même que l’envoi de toutes vos marques actives.

    • Les marques formatées vides/incorrectes sont ignorées.
    LANGUAGE ISO 639-1 : codes à deux lettres (p. ex. FR)

    Facultatif : la langue souhaitée du texte à récupérer.
    Si celle-ci n’est pas indiquée, le texte sera renvoyé dans la langue configurée par le commerçant.

    Vous pouvez tester des demandes de requête directes : https://secure.ogone.com/ncol/test/privacy-policy.asp

    Ci-dessous figure la liste des éléments XML et des exemples de réponses XML obtenues pour différents résultats.

    Nom Format Description
    Response Complexe Root node, always present
    Response.Status Chaîne, valeurs possibles : Success, SuccessWithWarnings, Error Toujours présent
    Response.Body Complexe Présent uniquement quand Response.Status = Success ou SuccessWithWarnings
    Response.Body.Html Chaîne / html Vide si Response.Status = SuccessWithWarnings & Response.Warnings.Warning.Code = NoContent
    Response.Errors Complexe Présent uniquement quand Response.Status = Error
    Response.Errors.Error Complexe Peut se produire plusieurs fois à l’intérieur d’un nœud <Errors>
    Response.Warnings Complexe Uniquement présent quand Response.Status = SuccessWithWarnings ou Error
    Response.Warnings.Warning Complexe Se produit plusieurs fois dans un nœud <Warnings>
    Response.Errors.Error.Code
    Response.Warnings.Warning.Code
    Chaîne, valeurs possibles :
    •À l’intérieur d’un nœud <Error> : non autorisé, InternalServerError
    •À l’intérieur d’un nœud <Warning> : NoContent

    Toujours présent à l’intérieur d’un nœud <Error> ou <Warning>
    Response.Errors.Error.Message
    Response.Warnings.Warning.Message
    Chaîne Facultatif

    Si vous obtenez Response.Status=Error, voir Response.Errors.Error pour corriger l’erreur.
    Ci-dessous figurent deux exemples de réussite :

    1. Exemple de réponse XML pour un succès avec avertissements. L’exemple est affiché si aucune information à caractère personnel ne doit être divulguée au client.

    <?xml version="1.0" encoding="utf-8"?><Response>
    <Status>SuccessWithWarnings</Status>
    <Warnings>
    <Warning>
    <Code>NoContent</Code>
    </Warning>
    </Warnings>
    <Body>
    <Html/>
    </Body>
    </Response>


    2. Exemple de réponse XML pour un succès avec contenu. L’exemple est affiché en deux sections.

    <?xml version="1.0" encoding="utf-8"?>
    <Response>
    <Status>Success</Status>
    <Body>
    <Html><![CDATA[<ul><li><h2>Title 1</h2><p>Content 1</p></li><li><h2>Title 2 (VISA, American Express)</h2><p>Content 2</p></li></ul>]]></Html>
    </Body>
    </Response>

    Pour certains moyens de paiement, les valeurs des paramètres diffèrent des valeurs standard pour les cartes de crédit.

    Le tableau ci-dessous contient les valeurs spécifiques des paramètres permettant la transmission de transactions Direct Debit AT via DirectLink.

    Format: AN= Alphanumérique / N=Numérique, le nombre maximum de caractères autorisés
    Champ
    Utilisation
    Format/Valeur
    CARDNO

    Numéro de compte bancaire

    AN, 21

    Format: XXXXXXXXXXXBLZYYYYY

    XXXXXXXXXXX: numéro de compte, numérique, 11 chiffres.
    YYYYY: Code bancaire (Bankleitzahl), 5 chiffres.
    CN Nom du titulaire de compte bancaire AN, 35
    ED Date d'expiration
    MM/AA or MMAA
    OPERATION

    Code d'opération

    A, 3

    Valeurs possibles:

    • RES: autorisation
    • SAL/SAS: argent débité du compte bancaire
    • RFD/RFS: argent remboursé (*)
    OWNERADDRESS Adresse du titulaire de compte bancaire AN, 50
    OWNERTOWN Ville du titulaire de compte bancaire AN, 40
    OWNERZIP Code postal du titulaire de compte bancaire AN, 10
    PM Moyen de paiement AN, 25

    “Direct Debits AT”

    (*Si l’option “Remboursement” est disponible et active, et les remboursements DTAUS sont disponibles)

    Le tableau suivant contient les valeurs spécifiques des paramètres permettant la transmission de transactions ELV en mode DirectLink. (à l’exception de Wirecard/Billpay)

    Format: AN= Alphanumérique / N=Numérique, le nombre maximum de caractères autorisés
    Champ
    Usage Format/Valeur
    Obligatoire
    CARDNO
    Numéro de compte bancaire

    IBAN: 22 caractères alphanumériques

    OR

    Numéro de compte bancaire + BLZ. Format: XXXXXXXXXBLZYYYYYYYY
    XXXXXXXXXX: numéro de compte, numérique, 1 to 10 chiffres.
    YYYYYYYY: Code bancaire (Bankleitzahl), 8 chiffres.
    Oui
    CN
    Nom du titulaire de compte bancaire
    AN, 35
    Non
    ED
    Date d'expiration
    MM/AA ou MMAA Oui
    MANDATEID
    Référence unique de mandat.

    Telego: AN, 35 / Charset: “A-Z a-z 0-9 space /-?:().,'+”)
    Si non fournie, la plateforme prendra l’ORDERID ou le PAYID

    Easycash: Format: AN, 27 / Charset: “A-Z a-z 0-9 space /-?:().,'+”)
    Note: Si non fournie, easycash générera une valeur.

    Non
    OPERATION
    Code d'opération

    A, 3

    Valeurs possibles:

    • RES: autorisation
    • SAL/SAS: argent débité du compte bancaire
    • RFD/RFS: argent remboursé (*)
    Non
    OWNERADDRESS
    Adresse du titulaire de compte bancaire
    AN, 50 Oui
    OWNERTOWN
    Ville du titulaire de compte bancaire
    AN, 40 Oui
    OWNERZIP
    Code postal du titulaire de compte bancaire
    AN, 10 Oui
    PM
    Moyen de paiement

    AN, 25

    "Direct Debits DE”

    Oui

    Note: Ces champs peuvent être retournés dans une réponse XML en mode DirectLink XML et doivent être inclus dans le calcul du SHA-IN (de manière optionnelle aussi le SHA-OUT)

    (*Si la function REMBOURSEMENT est disponible et active et les Remboursements DTAUS sont disponibles)

    Le tableau suivant contient les valeurs spécifiques des paramètres permettant la transmission de transactions Direct Debits NL via DirectLink.

    Format: AN= Alphanumérique / N=Numérique, le nombre maximum de caractères autorisés
    Champ
    Usage
    Format/Valeur
    CARDNO
    Numéro de compte bancaire
    Numéro de compte néerlandais classique: max. 10 caractères alphanumériques (si inférieur, pad à gauche avec des zéros).

    OU

    Numéro de compte IBAN: max. 35 caractères alphanumériques (SEPA)

    CN
    Nom du titulaire de compte bancaire
    AN, 35
    ED
    Date d'expiration
    MM/AA ou MMAA
    OPERATION

    Code d'opération

    A, 3

    Valeurs possibles:

    • SAL ou SAS: argent débité du compte bancaire
    • RFD ou RFS: argent remboursé (remboursement)
    OWNERTOWN
    Ville du titulaire de compte bancaire
    AN, 40
    PM Moyen de paiement

    AN, 25

    “Direct Debits NL”

    Seulement pertinent pour les transactions SEPA (*):
    BIC
    Code d’Identification de la Banque.
    AN, 11
    MANDATEID

    Référence unique de mandat.

    Note: Si non fournie, l’ORDERID sera pris à la place.

    AN, 35

    Pas d’espace; ne peut commencer ni finir par une barre oblique "/" ou contenir deux barres obliques (slashes) consécutives.

    SEQUENCETYPE

    Type de transaction Direct Debit

    Note: Si non fournie, la transaction sera considérée comme “seule et unique” (“one-off") (OOFF sera appliqué).

    Valeurs possible pour indiquer le type de transaction Direct Debit (AN, 4):
    • "FRST": Première collecte d’une série d’instructions pour Direct Debit
    • "RCUR": Instructions pour Direct Debit où l’autorisation du débiteur est utilisée pour des transactions classiques en Direct Debit initiées par le créditeur
    • "FNAL": Dernière collecte d’une série d’instructions pour Direct Debit (par après, le même MandateID ne peut plus être utilisé)
    • "OOFF": Instruction pour Direct Debit où l’autorisation du débiteur est utilisée pour initier une seule transaction Direct Debit
    SIGNDATE

    La date de mandat a été signée par l’acheteur.

    Note: Si non fournie, la date de transaction sera prise à la place.

    AAAAMMJJ

    (*SEPA: Single Euro Payments Area)

    Note: Ces champs peuvent être retournés dans une réponse XML en mode DirectLink XML et doivent être inclus dans le calcul du SHA-IN (de manière optionnelle aussi le SHA-OUT).

    Pour certains moyens de paiement (hors cartes de crédit), vous ne pouvez pas envoyer de nouvelles transactions via DirectLink, mais vous pouvez envoyer des opérations de maintenance via DirectLink. C’est par exemple le cas pour PostFinance Card, PostFinance e-finance, PayPal Express Checkout et TUNZ. Lorsque vous envoyez des opérations de maintenance, PM/BRAND/CARDNO/ED ne sont pas des données requises, aucune valeur spécifique ne doit donc être envoyée pour ces moyens de paiement.

    Pour des informations de nature générale sur 3-D Secure v2, consultez notre PSD2 guide.

    Découvrez ici comment mettre 3-D Secure en place dans le processus de paiement de façon sûre.

    Le flux de transaction comprend les étapes suivantes:

    1. Votre client se rend sur votre page de passage de la commande et finalise l’achat sur votre page de paiement.
    2. Vous nous envoyez les informations concernant la commande et le paiement via une demande DirectLink contenant une série de paramètres supplémentaires.
      • (2’)Optionnel : nous réalisons une vérification en matière de fraude.
    3. Vous recevez une réponse XML de la part de notre plateforme. Il y a deux scénarios possibles.
      • Si la transaction est effectuée sans interaction (frictionless flow), la réponse contient les paramètres standard  avec le retour d’informations final concernant la transaction. Cela marque la fin du flux.

      • Si la transaction est effectuée avec une vérification (challenge flow), la réponse contient le champ supplémentaire HTML ANSWER et un statut de paiement spécifique (STATUT=46). HTML_ANSWER contient un bloc de code crypté en BASE-64.

    4. Ajoutez le bloc de code décrypté au navigateur de votre titulaire de carte. Votre titulaire de carte est automatiquement redirigé vers sa banque émettrice pour une authentification
    5. Le titulaire de carte s’identifie. Notre système reçoit le résultat de la part de l’émetteur.
    6. Sur la base de ce résultat, il y a deux scénarios possibles.
      • Si l’identification a échoué, nous redirigeons le titulaire de carte vers le DECLINEURL, ce qui met fin au flux. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.
      • If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction
    7. Nous vous envoyons le résultat du paiement. En fonction du résultat de l’acquéreur, nous redirigeons le titulaire de carte vers le ACCEPTURL, DECLINEURL ou EXCEPTIONURL. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.
    8. Si la transaction est réussie, vous pouvez fournir les biens ou services

    DirectLink with 3-D Secure v2 transaction flowThis graph describes the DIRECTLINK (DPR/D3D) + Fraud transaction flow

    Que la responsabilité soit transférée ou non dépend de votre contrat avec votre acquéreur. En conséquence, nous vous suggérons de vérifier les conditions générales avec votre acquéreur.

    Pour traiter les transactions avec 3-D Secure, vous envoyez une série de paramètres obligatoires, recommandés et optionnels vers notre plateforme.

    Ces paramètres doivent être inclus dans le calcul SHA.

    Capturer et envoyer des paramètres

    Vous devez capturer les paramètres 3DS spécifiques obligatoires / recommandés / optionnels sur votre page de paiement.

    Vous trouverez ici un bloc de code Javascript que vous pouvez utiliser pour capturer les informations du navigateur.

    <script type="text/javascript" language="javascript">
    function createHiddenInput(form, name, value)
    {
    var input = document.createElement("input");
    input.setAttribute("type", "hidden");
    input.setAttribute("name", name);
    input.setAttribute("value", value);
    form.appendChild(input);
    }

    var myCCForms = document.getElementsByName("MyForm");
    if (myCCForms != null && myCCForms.length > 0)
    {
    var myCCForm = myCCForms[0];
    createHiddenInput(myCCForm, "browserColorDepth", screen.colorDepth);
    createHiddenInput(myCCForm, "browserJavaEnabled", navigator.javaEnabled());
    createHiddenInput(myCCForm, "browserLanguage", navigator.language);
    createHiddenInput(myCCForm, "browserScreenHeight", screen.height);
    createHiddenInput(myCCForm, "browserScreenWidth", screen.width);
    createHiddenInput(myCCForm, "browserTimeZone", new Date().getTimezoneOffset());
    }
    </script>

    Envoyez ces paramètres spécifiques 3-D Secure avec les autres paramètres obligatoires DirectLink. Notre plateforme traitera votre demande et vous fournira une réponse.

    Comprendre les transactions refusées

    PSD2 améliore la transparence du processus de paiement pour vous et vos clients. Ceci est particulièrement utile lorsqu’il s’agit de transactions de statut 2.

    Notre paramètre de retour d’information CH_AUTHENTICATION_INFO vous fournit des informations détaillées sur les émetteurs lorsqu’ils refusent des transactions de vos clients.

    Partagez ces informations avec vos clients afin de leur permettre de comprendre pourquoi leur banque a refusé leur transaction. Elles pourraient également vous permettre de récupérer la transaction par le biais de notre fonctionnalité Soft Decline.

    Pour recevoir CH_AUTHENTICATION_INFO dans la réponse XML et dans vos URL de redirection, sélectionnez ce paramètre respectivement dans le Back Office via Configuration > Technical information > Transaction feedback >  DirectLink > Dynamic parameters et Dynamic e-Commerce parameters . Cela permettra également de s’assurer que ces informations apparaissent dans l’aperçu des transactions via Operations > View transactions / Financial history.

    Utilisez CH_AUTHENTICATION_INFO pour l’un ou l’autre des scénarios possibles :

    • Si la transaction passe par le frictionless flow, notre réponse XML inclura ce paramètre. De ce fait, ajoutez les informations à la page de résultat de votre transaction.
    • Si la transaction passe par le challenge flow, vous recevez ce paramètre via le Page de paiement hebergée mode canaux de retour d’information. Comme vous ne recevrez pas les informations suffisamment tôt pour modifier, en conséquence, vos URL de redirection une fois la transaction finalisée, nous vous recommandons de marquer « I would like Ingenico to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process.» dans le Back Office via Configuration > Technical information > Transaction feedback > eCommerce > HTTP redirection in the browser. Notre plateforme redirigera ensuite vos clients vers notre page de résultats intermédiaires présentant les informations avant que vos clients ne se retrouvent au final sur vos URL de redirection.

    Notez que tous les émetteurs ne communiquent pas les raisons pour lesquelles ils refusent des transactions. Par conséquent, dans certains cas, CH_AUTHENTICATION_INFO est vide.

    Utilisez les numéros de carte suivants dans notre Environnement de test pour simuler la réponse d’un émetteur :
    Amex: 349586710563469
    MasterCard: 5111823134937549
    Visa: 4010759044222272

    Réponse de la plateforme de traitement

    Si la transaction est effectuée sans interaction (frictionless flow), la réponse contient les paramètres standard  avec le retour d’informations final concernant la transaction. Cela marque la fin du flux.

    Si la transaction est effectuée avec une vérification (challenge flow), la réponse contient des paramètres supplémentaires. Pour mettre en œuvre l’authentification de vos clients, vous devez traiter les données supplémentaires fournies comme décrit ci-après :

    Champ Description
    STATUT Nouvelle valeur : « 46 » (en attente d’identification)
    HTML_ANSWER

    Code html crypté en BASE64 à ajouter à la page html renvoyée au client.

    Cette balise est ajoutée en tant qu’enfant de la balise XML globale <ncresponse>. Le champ HTML_Answer contient du code HTML qui a été ajouté à la page html renvoyée au navigateur du client.

    Ce code chargera automatiquement la page d’identification de la banque émettrice dans une fenêtre contextuelle au sein de la page principale, en fonction de la valeur du paramètre WIN3DS.

    Afin d’éviter toute interférence entre les balises html incluses dans le contenu de la balise XML HTML_ANSWER avec le reste du XML renvoyé en tant que réponse à la demande DirectLink, le contenu de HTML_ANSWER est crypté en BASE64 par notre système avant d’envoyer la réponse. Par conséquent, il doit être décrypté en BASE64 avant d’être inclus dans la page html envoyée au titulaire de carte.

    Si l’identification a échoué, nous redirigeons le titulaire de carte vers le DECLINEURL, ce qui met fin au flux. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.

    Si l’identification est réussie, nous soumettons la transaction financière en question à l’acquéreur.

    En fonction du résultat de l’acquéreur, nous redirigeons le titulaire de carte vers le ACCEPTURL, DECLINEURL ou EXCEPTIONURL. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.

    9.3 Cartes de Test

    Vous pouvez utiliser la carte de test suivante pour simuler une carte enregistrée 3-D Secure dans notre environnement de test :

    Flux sans problème
    Type de carte Numéro de carte Date d'expiration
    VISA 4186455175836497 N’importe quelle date dans le futur
    Mastercard 5137009801943438 N’importe quelle date dans le futur
    American Express 375418081197346 N’importe quelle date dans le futur
    Carte Bancaire 4150557357382737 N’importe quelle date dans le futur
    Flux avec processus d'identification
    Type de carte Numéro de carte Date d'expiration
    VISA 4874970686672022 N’importe quelle date dans le futur
    Mastercard 5130257474533310 N’importe quelle date dans le futur
    American Express 379764422997381 N’importe quelle date dans le futur
    Carte Bancaire 4150550997933993 N’importe quelle date dans le futur

    Remarque: Plus de numéros de cartes de test peuvent être téléchargés ici.

    Si une transaction est bloquée par une identification incorrecte, le résultat de la transaction sera :

    STATUS = 2

    NCERROR = 40001134

    9.4 Exclusions de la règle 3DSv2

    Certaines transactions sont exclues de PSD2.Si une de vos transactions en fait partie, 3-D Secure ne sera pas mis en œuvre. Cela s’applique également aux transactions récurrentes que vous initiez. Pour marquer ces transactions initiées par des marchands (MIT) en tant que telles, vous devez envoyer des paramètres supplémentaires vers notre plateforme.

    Vous pouvez demander à éviter 3-D Secure


    Ne choisissez qu’une des deux options lorsque vous demandez des transactions puisqu’elles sont mutuellement exclusives.

    Flux sans interaction / avec vérification et indication du flux préféré

    Vous pouvez améliorer les probabilités d’éviter la SCA (ce qui entraîne un flux sans interaction) en envoyant le paramètre suivant.

    En fonction de votre évaluation du risque de fraude, vous pouvez envoyer des valeurs spécifiques (c.-à-d. pour une évaluation de faible risque : 02, pour un risque de fraude plus élevé : 03).

    Paramètre obligatoire (si vous souhaitez un flux spécifique)

    Paramètre Valeurs
    Mpi.threeDSRequestorChallengeIndicator

    Longueur : 2 caractères
    Type de données : chaîne
    Valeurs acceptées :

    • 01 = pas de préférence
    • 02 = pas de procédé d’identification demandé
    • 03 = procédé d’identification demandé : préférence marchand
    • 04 = procédé d’identification demandé : obligatoire
    • 05 = pas de procédé d’identification demandé [l’analyse de risque de la transaction est déjà réalisé]
    • 06 = pas de procédé d’identification demandé [partage de données uniquement]
    • 07 = pas de procédé d’identification demandé [SCA déjà réalisé]
      Performed]
    • 80-99 = réservé au SR

    Vous pouvez même augmenter la probabilité d’un flux sans interaction et obtenir un taux de conversion plus élevé en envoyant plus de paramètres optionnels.

    Exemptions de 3DS

    Pour contourner totalement 3-D Secure, envoyez les paramètres suivants :

    Paramètres Valeurs
    FLAG3D N = Ignorer le processus d’authentification 3DS
    3DS_EXEMPTION_INDICATOR Justifier le choix motivant le souhait d’ignorer 3DS. Les valeurs numériques peuvent s’appliquer en fonction de la transaction

    03 = ART* de l’émetteur
    04 = Exception pour faible montant
    05 = ART* du commerçant/de l’acheteur
    06 = Liste blanche
    07 = Entreprise
    08 = Expédition retardée
    09 = Authentification déléguée (portefeuille certifié)

    En revanche, il appartient toujours à l’émetteur de choisir de mettre en place un processus d’authentification. Dans le cas où l’émetteur insiste pour utiliser 3DS, la transaction sera refusée.

    Important

    Les transactions pour lesquelles 3-D Secure devrait être évité peuvent uniquement être traitées en tant qu’autorisations (qui se solderont par un statut 5 si elles sont réussies). Pour recevoir l’argent de ces transactions, vous devrez les capturer ultérieurement. Une transaction capturée avec succès atteindra le statut 9.

    Soft Decline

    Une séquence typique de transaction refusée par soft decline ressemble à ceci

    1. Lors de votre première demande, vous envoyez uniquement FLAG3D=N et aucun autre paramètre d’authentification. De cette façon, vous indiquez que vous souhaitez passer la procédure 3-D Secure. Il est possible que la transaction soit déjà acceptée à ce stade.
      Si elle est refusée par la banque de votre client parce qu’elle insiste pour réaliser la procédure 3-D Secure, nous l’indiquerons dans le paramètre de retour d’informations en envoyant NCERROR=40001139. La transaction sera placée en statut 2.
    2. Pour récupérer cette transaction refusée, soumettez à nouveau la transaction en envoyant les paramètres suivants à notre plateforme
      1. La demande standard  e-Commerce DirectLink parameters telle qu’envoyée dans votre première demande en tant que nouvelle commande eCommerce ou DirectLink.
      2. FLAG3D=Y pour indiquer que la procédure 3-D Secure doit être effectuée
      3. Les paramètres d’authentification 3DSv2 as described here
      4. Mpi.threeDSRequestorChallengeIndicator=04 pour indiquer que la banque de votre client insiste pour réaliser la procédure 3-D Secure à la suite du Soft Decline.

    Votre client devra réaliser avec succès la procédure d’authentification 3-D Secure au cours de la deuxième demande. Finalement, la transaction atteindra le statut 2 ou 9. Cela dépendra du fait que votre client ait réussi la procédure d’authentification et que le paiement soit accepté aussi bien par votre banque que celle de votre client

    Soft Decline  est actuellement disponible pour les méthodes de paiement Visa, MasterCard, American Express et Carte Bancaire.

    9.5 Passer de la version 2.1 à la version 2.2

    La nouvelle version de 3-D Secure (v2.2) qui va bientôt arriver vous donnera encore plus de possibilités d’optimiser votre intégration.

    Pour la version 2.1 actuelle de 3-D Secure, ce paramètre est optionnel. Il deviendra toutefois obligatoire lorsque la version 2.2 sera disponible. Sa mise en œuvre dès à présent garantira une transition sans accroc de la v2.1 à la v2.2.

    Paramètre Valeurs

    BROWSERJAVASCRIPTENABLED

    Cette valeur booléenne indique si vos clients ont activé JavaScript ou non dans leur navigateur lorsqu’ils ont fait un achat.

    En fonction de cette valeur, un des éléments suivants s’applique

    • TRUE : les paramètres suivants resteront obligatoires

      BROWSERJAVAENABLED
      BROWSERSCREENHEIGHT
      BROWSERSCREENWIDTH
      BROWSERTIMEZONE
      BROWSERACCEPTHEADER
      BROWSERUSERAGENT
      BROWSERLANGUAGE

    • FALSE: les paramètres suivants ne seront plus obligatoires :
      BROWSERCOLORDEPTH
      BROWSERJAVAENABLED
      BROWSERSCREENHEIGHT
      BROWSERSCREENWIDTH
      BROWSERTIMEZONE

      Ces paramètres restent obligatoires :

      BROWSERACCEPTHEADER
      BROWSERUSERAGENT
      BROWSERLANGUAGE

    Type de donnée : Boolean

    Valeurs acceptées :
    • TRUE
    • FALSE

    Si vous n’envoyez pas ce paramètre, nous prédéterminons cette valeur en fonction des autres paramètres disponibles.

    En plus de BROWSERJAVASCRIPTENABLED, la version 2.2 propose des paramètres améliorés / nouveaux destinés à rendre vos transactions encore plus sécurisées :

    3DSv1 est le premier protocole de sécurité à 3 dimensions mis en place par les systèmes de cartes. Il a été remplacé par la v2. Si vous avez mis en place la v2, cette section ne vous concerne pas.

    Nous vous recommandons instamment d’adapter votre mise en place aux exigences de la v2. Cependant, si vous n’êtes pas encore prêt, vous trouverez ici les instructions pour mettre en place la v1.

    Flux de transaction DirectLink 3-D Secure V1

    Le flux de transaction implique les étapes suivantes :

    1. Votre client se rend sur votre page de passage de la commande et finalise l’achat sur votre page de paiement.
    2. Vous nous envoyez les informations concernant la commande et le paiement via une demande DirectLink contenant une série de paramètres supplémentaires.
      • (2’) Optionnel : nous réalisons une vérification en matière de fraude
    3. Vous recevez une réponse XML de la part de notre plateforme
      • Si la carte de votre client n’est pas enregistrée pour 3-D Secure, la réponse contient les paramètres standard avec le retour d’informations final concernant la transaction.
      • Si la carte de votre client est enregistrée pour 3-D Secure, la réponse contient le champ supplémentaire HTML_ANSWER et un statut de paiement spécifique (STATUT=46). HTML_ANSWER contient un bloc de code crypté en BASE-64.
    4. Ajoutez le bloc de code décrypté au navigateur de votre titulaire de carte. Votre titulaire de carte est automatiquement redirigé vers sa banque émettrice pour une authentification
    5. Le titulaire de carte s’identifie. Notre système reçoit le résultat de la part de l’émetteur.
    6. Two scenarios are possible
      • Si l’identification a échoué, nous redirigeons le titulaire de carte vers le DECLINEURL, ce qui met fin au flux. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.
      • Si l’identification est réussie, nous soumettons la transaction financière en question à l’acquéreur pour qu’il traite la transaction.
    7. Nous vous envoyons le résultat du paiement. En fonction du résultat, nous redirigeons le titulaire de carte vers le ACCEPTURL, DECLINEURL ou EXCEPTIONURL. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée
    8. Si la transaction est réussie, vous pouvez fournir les biens ou services
    Que la responsabilité soit transférée ou non dépend de votre contrat avec votre acquéreur. En conséquence, nous vous suggérons de vérifier les conditions générales avec votre acquéreur.

    Envoyer une demande 3-D Secure v1

    Pour traiter les transactions avec 3-D Secure, vous envoyez une série de paramètres obligatoires et optionnels vers notre plateforme.

    Le tableau vous donne un aperçu des différents paramètres et de leur fin dans le cadre du processus d’authentification.

    Ces paramètres doivent être inclus dans le calcul SHA.

    Parameter category Paramètres Nom / Description
    Obligatoires

    FLAG3D

    Valeur Fixe: ‘Y’;

    Indique à notre système d’exécuter une identification 3-D Secure si nécessaire.

    HTTP_ACCEPT*

    This parameter has been replaced by browserAcceptHeader. Do not send it if you are already sending browserAcceptHeader.

    Le champ en header “Accept request” dans le navigateur du porteur de carte, utilisé pour spécifier certains médias qui sont acceptables pour la réponse. Cette valeur est utilisée par l’émetteur pour vérifier si le navigateur du porteur de carte est compatible avec le système d’identification de l’émetteur. Par exemple:
    Accept: */*

    HTTP_USER_AGENT*

    Ce paramètre a été remplacé par

    browserUserAgent. A ne pas envoyer si vous envoyez déjà browserUserAgent.

    Le champ en header “User-Agent request” dans le navigateur du porteur de carte, contenant des informations sur l’agent utilisateur de qui émane la requête. Cette valeur est utilisée par l’émetteur pour vérifier si le navigateur du porteur de carte est compatible avec le système d’identification de l’émetteur. Par exemple:
    User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)

    ACCEPTURL

    URL de la page web à montrer au client lorsque le paiement est autorisé (ou en attente d’autorisation).

    DECLINEURL

    URL vers lequel le client est redirigé si le nombre maximal de tentatives d’autorisation échouées a été atteint (10 par défaut, mais peut être modifié dans la page d’information technique, onglet "Paramètres de transaction Globaux ", section "Tentatives de paiement multiples").

    EXCEPTIONURL

    URL de la page web à montrer au client lorsque le résultat du paiement est incertain.

    LANGUAGE

    Langue par défaut utilisée si aucune valeur de langue n'est envoyée ou si la langue envoyée n'est pas valide : en_US (anglais)

    Optionels

    TP

    Pour modifier la mise en page de la page "order_A3DS", vous pouvez envoyer un nom / une URL de modèle avec ce paramètre. (aller à e-Commerce: Dynamic template).

    PARAMPLUS

    Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.

    COMPLUS

    Field to submit a value you wish to be returned in the post-sale request or output.

    WIN3DS

    Manière de montrer la page d’identification au client. Valeurs possibles :

    • MAINW : montre la page d’identification dans la fenêtre principale (valeur par défaut).
    • POPUP: montre la page d’identification dans une nouvelle fenêtre venant d’apparaître (pop up) et retourne vers la fenêtre principale à la fin.
    • POPIX: montre la page d’identification dans une nouvelle fenêtre venant d’apparaître (pop up) et reste dans cette même fenêtre.

    Après avoir envoyé ces paramètres, notre plateforme traitera votre demande et vous fournira une réponse.

    Réponse de la plateforme de traitement

    Si la carte de votre client n’est pas enregistrée pour 3-D Secure, la réponse contient les paramètres standard  avec le retour d’informations final concernant la transaction. Cela marque la fin du flux.

    Si la carte de votre client est enregistrée pour 3-D Secure, la réponse contient des paramètres supplémentaires. Pour mettre en œuvre l’authentification de vos clients, vous devez traiter les données supplémentaires fournies comme décrit ci-après :

    Paramètre Explication
    STATUS Nouvelle valeur: “46” (en attente d’identification)
    HTML_ANSWER

    Code html encodé en BASE64 à ajouter à la page html retournée au client.

    Ce tag est ajouté comme enfant au tag XML global . Le champ HTML_Answer contient du code HTML qui doit être ajouté à la page html retournée vers le navigateur du client.

    Ce code chargera automatiquement la page d’identification de la banque émettrice dans une nouvelle fenêtre apparaissant dans la fenêtre principale, en fonction de la valeur du paramètre WIN3DS.

    Afin d’éviter toute interférence entre les tags html inclus dans le contenu du tag HTML_ANSWER XML et le reste de l’XML retourné comme réponse à la requête <%DIRECTLINK%>, le contenu du champ HTML_ANSWER est encodé en BASE64 par notre système avant que nous retournions la réponse. Par conséquent, celui-ci doit être decodé (du BASE64) avant d’être inclus dans la page html envoyée vers le porteur de carte.

    Si l’identification a échoué, nous redirigeons le titulaire de carte vers le DECLINEURL, ce qui met fin au flux. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.

    Si l’identification est réussie, nous soumettons la transaction financière en question à l’acquéreur.

    En fonction du résultat de l’acquéreur, nous redirigeons le titulaire de carte vers le ACCEPTURL, DECLINEURL ou EXCEPTIONURL. Vous recevez le résultat via les canaux de retour d'informations Page de paiement hebergée.

    Cartes de Test

    Vous pouvez utiliser les cartes de test suivantes pour simuler une carte enregistrée 3-D Secure dans notre environnement de test :

    Type de carte Numéro de carte Date d'expiration Mot de passe
    VISA 4000000000000002 N’importe quelle date dans le futur 11111
    MasterCard 5300000000000006 N’importe quelle date dans le futur 11111
    American Express 371449635311004 N’importe quelle date dans le futur 11111

    Remarque: Plus de numéros de cartes de test peuvent être téléchargés ici.

    Si une transaction est bloquée par une identification incorrecte, le résultat de la transaction sera :

    STATUS = 2

    NCERROR = 40001134

    9.7 Obtenir un aperçu des transactions 3-D Secure

    Pour pouvoir faire un suivi de vos transactions et de leurs résultats 3-D Secure, nous vous proposons une façon d’accéder à vos rapports 3-D Secure depuis le Back Office.

    Regardez cette vidéo qui explique comment paramétrer votre rapport rapidement et en toute simplicité.

    Questions fréquemment posées

    Dans le menu de votre compte Ingenico ePayments, vous pouvez facilement rechercher vos transactions en cliquant sur « Opérations », puis sur « Afficher les transactions » ou « Historique financier », selon le type de résultat que vous recherchez.

    Cliquez sur Consulter vos transactions pour obtenir plus d’informations.

    Par défaut, vous pouvez envoyer des marchandises ou fournir un service lorsque la transaction a atteint le statut « 9 - Paiement demandé ». Même si le statut 5 est un statut positif, il s’agit d’une simple réserve d’argent temporaire sur la carte du client. Une transaction possédant le statut 5 doit être confirmée (manuellement ou automatiquement), pour passer au statut 9, qui est le dernier statut positif pour la plupart des méthodes de paiement.

    Cliquez sur Statuts des transactions pour obtenir plus d’informations.

    Vous pouvez facilement rembourser un paiement en cliquant sur le bouton « Rembourser » dans l’aperçu des commandes d’une transaction (dans « Afficher les transactions »). Si votre compte le permet, vous pouvez également effectuer des remboursements avec une demande DirectLink ou l’option de téléchargement de fichier Batch (en cas de transactions multiples).

    Sachez que l’option « Remboursement » doit être activée sur votre compte.

    Cliquez sur Gérer vos transactions pour obtenir plus d’informations.

     

    Si vous souhaitez vérifier les détails d’une commande/transaction ou gérer certaines transactions, vous devez utiliser l’option « Gestion des transactions ». « Historique financier » est l’option la plus pratique pour consulter périodiquement les fonds entrants et sortants.

    Pour plus d’informations, consultez Gestion des transactions vs Historique financier.

    Vous ne pouvez effectuer des remboursements que sur les transactions qui ont obtenu u statut 9 sur les dernières 24 heures. L’annulation ou la suppression d’un paiement est possible dans un délai de 24 heures après que le statut final de la transaction soit reçu (Statut 9 ou 5).

    Pour connaître l’heure limite de votre acquéreur, nous vous recommandons de contacter directement notre service clientèle.