1 Procédures générales et paramètres de sécurité
   1.1 Utilisateur API
   1.2 Formulaire de requête
   1.3 Sécurité
      1.3.1 Cryptage
      1.3.2 Adresse IP
      1.3.3 Signature SHA
   1.4 Parsing de la réponse
2 Effectuer une nouvelle commande
   2.1 URL de requête
   2.2 Paramètres de requête
   2.3 Page de test
   2.4 Exclure les moyens de paiement spécifiques
   2.5 Requête de commande utilisant 3-D Secure
   2.6 Subdivision en cartes de crédit/débit
   2.7 Traitement de transactions avec des identifiants enregistrés
3 Réponse de commande
   3.1 Double requête (doublon)
4 Maintenance directe: Maintenance sur des commandes existantes
   4.1 Requête de maintenance
      4.1.1 URL de requête
      4.1.2 Paramètres de requête
      4.1.3 Page de test
   4.2 Réponse de maintenance
   4.3 Double requête (doublon)
5 Requête Directe (Direct Query): demander le statut d’une commande
   5.1 Demande de requête
      5.1.1 URL de requête
      5.1.2 Paramètres de requête
      5.1.3 Page de test
   5.2 Réponse de requête
      5.2.1 Transactions traitées en e-Commerce
   5.3 Statuts possibles de réponse
   5.4 Requête Directe comme sécurité
6 Demande de politique de confidentialité à l’attention du responsable du traitement des données
   6.1 Demande de requête
      6.1.1 Demande d'URL
      6.1.2 Demande de Paramètres
      6.1.3 Page de test
   6.2 Réponse de requête
7 Exceptions parmi les moyens de paiement
   7.1 Direct Debits
      7.1.1 Direct Debits AT
      7.1.2 Direct Debits DE (ELV)
      7.1.3 Direct Debits NL
   7.2 Moyen de paiement où seule la maintenance est possible via DirectLink
8 3-D Secure v1.0
   8.1 Introduction
   8.2 Flux de Transaction 3-D via via DirectLink
      8.2.1 Paramètres de requête additionnels
      8.2.2 Champs de retour additionnels
      8.2.3 Commentaires
9 3-D Secure v2.1
   9.1 Introduction
   9.2 Flux de Transaction 3-D via DirectLink
      9.2.1 Paramètres de requête additionnels
      9.2.2 Champs de retour additionnels
      9.2.3 3-D Secure v2.1 MasterCard+
      9.2.4 Commentaires
   9.3 Exclusions et exceptions pour 3DSv2
      9.3.1 3DSv2 et exclusions
      9.3.2 Flux frictionless/avec identification pour la SCA et 3DS
      9.3.3 Indication du flux préféré
      9.3.4 Exceptions pour 3DS

1 Procédures générales et paramètres de sécurité

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

1.1 Utilisateur API

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

1.2 Formulaire de requête

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.

1.3 Sécurité

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.

1.3.1 Cryptage

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.

1.3.2 Adresse IP

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.

1.3.3 Signature SHA

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

1.4 Parsing de la réponse

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.

2 Effectuer une nouvelle commande

2.1 URL de requête

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

2.2 Paramètres de requête

2.3 Page de test

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

2.4 Exclure les moyens de paiement spécifiques

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.

2.5 Requête de commande utilisant 3-D Secure

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.

2.6 Subdivision en cartes de crédit/débit

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.

2.7 Traitement de transactions avec des identifiants enregistrés

Les transactions avec identifiants enregistrés (Credential-on-file ou COF en anglais) utilisent les informations relatives à la carte déjà enregistrées par les marchands pour traiter le paiement. Avant d’initier une transaction avec identifiants enregistrés (COF), le titulaire de carte devra d’abord autoriser le marchand à stocker les informations relatives à la carte. Les transactions avec identifiants enregistrés (COF) s’appliquent essentiellement aux paiements récurrents et indiquent si le paiement est initié par le titulaire de carte ou le marchand.

Il existe deux types de transactions avec des identifiants enregistrés (COF) : les transactions initiées par le titulaire de carte (CIT) et les transactions initiées par le marchand (MIT). Une transaction initiée par le titulaire de carte (CIT) devra toujours avoir lieu avant de réaliser des transactions initiées par le marchand (MIT).

Une transaction initiée par le titulaire de carte (CIT) est une transaction dans laquelle le titulaire de carte est impliqué dans la transaction et authentifie personnellement la transaction au moyen d’une signature, de l’outil 3D-Secure ou en montrant une pièce d’identité.

Exemple de transaction initiée par le titulaire de carte (CIT):

Un titulaire de carte achète un billet de train et effectue un paiement. Il ou elle réalise le paiement avec sa carte de crédit et on lui demande d’authentifier et d’autoriser le paiement. On demande également au titulaire de carte s’il ou elle souhaite que les informations relatives à sa carte de crédit concernant ce paiement soient enregistrées. Si le titulaire de carte accepte, ces informations peuvent ensuite être réutilisées lors de transactions ultérieures initiées par le marchand.

Une transaction initiée par le marchand (MIT) sert de suivi à une transaction initiée par le titulaire de carte (CIT) et d’ordre permanent préautorisé pour les biens et services achetés par le titulaire de carte. Le titulaire de carte ne doit pas être impliqué dans la transaction.

Exemple de transaction initiée par le marchand (MIT):

Un marchand peut initier automatiquement une transaction pour réaliser le paiement d’un titulaire de carte dans le cadre d’un abonnement mensuel à un magazine.

Conformément aux réglementations mises en place par Visa et MasterCard pour les transactions avec identifiants enregistrés (COF), de nouveaux paramètres doivent être envoyés pour définir la transaction COF.

Vous serez concerné si:

  • Vous utilisez un pseudonyme (Alias)
  • Vous avez l’intention d’initier des transactions récurrentes (planifiées ou non) après avoir initié une transaction initiée par le titulaire de carte (CIT) pour la première fois

Mesures à prendre

Par défaut, les paramètres suivants sont utilisés lors d’une transaction DirectLink Server-to-Server:

Valeurs de paramètres COF_INITIATOR-COF_TRANSACTION-COF_SCHEDULE Description
CIT-FIRST-UNSCHED S’applique en cas d’utilisation d’un pseudonyme ou lors de sa création
CIT-FIRST-SCHED S’applique à un premier paiement planifié/abonnement
MIT-SUBSEQ-UNSCHED S’applique aux transactions récurrentes
MIT-SUBSEQ-SCHED S’applique aux paiements échelonnés

Les valeurs par défaut sont sélectionnées si vous n’ajoutez aucun paramètre. Cependant, si vous souhaitez les modifier, vous pouvez changer ces valeurs par défaut en envoyant les nouveaux paramètres. N’oubliez pas de recalculer la signature SHA également (cliquez ici pour plus d'informations concernant la signature SHA).

Paramètres
Valeurs Description
COF_INITIATOR CIT Une transaction initiée par un titulaire de carte
MIT Une transaction initiée par un marchand
COF_SCHEDULE SCHED Une transaction planifiée
UNSCHED Une transaction non planifiée
COF_TRANSACTION FIRST Première transaction d’une série de transactions
SUBSEQ Transactions suivantes d’une série de transactions
COF_RECURRING_EXPIRY Date AAAAMMJJ (ex. 20190914) Date de fin: dernière date de paiement d’une série de paiements récurrents
COF_RECURRING_FREQUENCY Chiffres entre 2 et 4 (31, 031 ou 0031) Nombre de jours séparant les paiements d’une série.

3 Réponse de commande

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.

3.1 Double requête (doublon)

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

4 Maintenance directe: Maintenance sur des commandes existantes

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.

4.1 Requête de maintenance

4.1.1 URL de requête

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

4.1.2 Paramètres de requête

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

4.1.3 Page de test

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

4.2 Réponse de maintenance

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.

4.3 Double requête (doublon)

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.

5 Requête Directe (Direct Query): demander le statut d’une 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).

5.1 Demande de requête

5.1.1 URL de requête

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

5.1.2 Paramètres de requête

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

5.1.3 Page de test

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.

5.2 Réponse de requête

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.

5.2.1 Transactions traitées en e-Commerce

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

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 e-Commerce)

Exemple d’une réponse XML à une interrogation directe (direct query) pour une transaction e-Commerce

<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"/>

5.3 Statuts possibles de réponse

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é

5.4 Requête Directe comme sécurité

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.

6 Demande de politique de confidentialité à l’attention du responsable du traitement des données

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.

6.1 Demande de requête

6.1.1 Demande d'URL

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

6.1.2 Demande de Paramètres

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.

6.1.3 Page de test

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

6.2 Réponse de requête

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>

7 Exceptions parmi les moyens de paiement

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

7.1 Direct Debits

7.1.1 Direct Debits AT

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)

7.1.2 Direct Debits DE (ELV)

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)

7.1.3 Direct Debits NL

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.

8 3-D Secure v1.0

8.1 Introduction

Le protocole 3-D Secure permet au porteur de carte d’être identifié lors du processus d’achat. Le porteur de carte doit absolument être connecté à l’internet pendant le processus d’identification. Le 3-D Secure ne fonctionne donc pas pour les centres d’appels (call centers) et les paiements récurrents.

Visa a implémenté le protocole 3-D Secure sous le nom “Verified By Visa”, MasterCard sous le nom “SecureCode” et JCB sous le nom “J-Secure”.
Le principe même d’intégration du DirectLink avec 3-D Secure est d’initier un paiement en mode DirectLink et de le finaliser en mode e-Commerce lorsqu’une authentification du porteur de carte est requise.

Le flux de transaction inclut les étapes suivantes:

  1. Vous nous envoyez une requête DirectLink pour la transaction, contenant un certain nombre de paramètres additionnels (cf. Extra request parameters).
  2. Notre système reçoît le numéro de carte dans votre requête et vérifie immédiatement en ligne si la carte est enregistrée dans le repertoire VISA/MasterCard/JCB (enregistré veut dire que l’identification est possible pour le numéro de carte, par exemple la carte est une carte 3-D Secure).
  3. Si le porteur de carte est enregistré, la réponse à la requête DirectLink contient un statut de paiement spécifique et du code html qui doit être retourné au client pour que ce dernier puisse entamer le processus d’identification(cf. Additional return fields). Le bloc de code html démarrera automatiquement le processus d’identification entre le porteur de carte (client) et sa banque émettrice.
  4. Le porteur de carte s’identifie sur la page de sa banque émettrice.
  5. Notre système reçoît la réponse d’identification de la part de l’émetteur.
  6. Si l’identification est réussie, notre système soumettra la transaction financière en elle-même à l’acquéreur.
  7. Vous recevez le résultat de l’identification globale et du processus d’autorisation en ligne via des canaux de feedback en mode e-Commerce.

Commentaires :

  • Si le porteur n’est pas enregistré (à l’étape 3), vous recevrez la réponse XML standard en DirectLink contenant le résultat du processus d’autorisation en ligne.
  • Afin de recevoir les statuts/codes d’erreur exacts des paiements (à l’étape 7), vous devez implementer le feedback post-sale en ligne (online) ou hors connexion (offline) comme décrit dans le guide d’intégration e-Commerce documentation.

8.2.1 Paramètres de requête additionnels

En dehors des paramètres standards DirectLink, vous devez également envoyer les informations suivantes:

Paramètre Explication
FLAG3D

Valeur Fixe: ‘Y’;

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

HTTP_ACCEPT 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 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)
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.
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.
PARAMPLUS Champs utilisés pour les paramètres divers ainsi que leurs valeurs et qui doivent être retournés dans la requête post-sale ou la redirection finale.
COMPLUS Champ utilisé pour soumettre un valeur qui doit être retournée dans la requête post-sale ou dans l’output.
LANGUAGE Langue du client, par exemple: “en_US”.
Optionnel
TP Afin de changer la disposition de la page "order_A3DS", vous pouvez envoyer un nom de template/url avec le paramètre.

Pour des details complémentaires sur ces champs, veuillez vous referrer au retour d'information sur la transaction.

8.2.2 Champs de retour additionnels

Si le porteur de carte n’est pas enregistré, la réponse <%DIRECTLINK%> habituelle est retournée. Si le porteur de carte est enregistré, les champs (additionnels) suivants seront retourné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.

8.2.3 Commentaires

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
Identification incorrecte

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

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9 3-D Secure v2.1

9.1 Introduction

En 2013, la Commission européenne a publié une proposition de version révisée de la Directive sur les services de paiement, connue sous le nom de DSP2 (DSP2 en anglais), afin de simplifier le traitement des paiements et de créer les règles et réglementations pour les services de paiement dans l'UE. C'est pourquoi il a fallu créer une nouvelle version de 3-D Secure, la v2.1.

Le changement le plus important est qu'en tant que marchand, vous devez partager plus de données : les émetteurs sont avides de points de données pour améliorer la précision de leur décision, ce qui entraînera finalement un paiement sans problème, mais c'est vous qui collectez les données en première ligne. La méthode d'évaluation des risques de 3DS v2 est plus efficace, mais nécessite une changement de l'ensemble de l'écosystème, ce qui vous permettra de transmettre les données vers l'émetteur.

Avec l’introduction de la nouvelle directive, les principaux card schemes disposent de nouveaux logos pour la version 2 du 3DS. Comme vous avez développé votre propre page de paiement, nous vous conseillons de la mettre à jour avec ces nouveaux logos (Visa / Mastercard / JCB /… ).

9.2 Flux de Transaction 3-D via DirectLink

Le flux de transaction implique les étapes suivantes :

1.Vous nous envoyez une demande DirectLink pour la transaction, qui contient un certain nombre de paramètres supplémentaires. Ces paramètres peuvent être répartis en trois groupes :

a. Paramètres obligatoires devant être saisis dans la page de paiement où le titulaire de carte entre les détails de la carte.

ParamètreDescriptionFormatObligatoire
browserAcceptHeader

Contenu exact de l’en-tête d’acceptation HTTP tel qu’il a été envoyé au marchand par le navigateur du titulaire de carte. *

Type de données : Chaîne
Longueur : Variable, au maximum 2048 caractères
Valeur acceptée : Si la longueur totale de l’en-tête d’acceptation envoyé par le navigateur est supérieure à 2 048 caractères, le serveur 3DS tronque la partie excédentaire.
Oui
browserColorDepth Valeur représentant la profondeur de bits de la palette de couleurs pour l’affichage des images, en bits par pixel. Obtenue auprès du navigateur du titulaire de carte à l’aide des propriétés de profondeur des couleurs. Type de données : Chaîne
Valeurs acceptées :
1 = 1 bit
4 = 4 bits
8 = 8 bits
15 = 15 bits
16 = 16 bits
24 = 24 bits
32 = 32 bits
48 = 48 bits
Oui
browserJavaEnabled Opérateur booléen qui représente la capacité du navigateur du titulaire de carte à exécuter Java. La valeur est fournie par les propriétés du navigateur compatible avec Java. Type de données : Opérateur booléen
Valeurs acceptées :
true
false
Oui
browserLanguage Valeur représentant la langue du navigateur telle que définie dans le standard IETF BCP47. Fourni par les propriétés de langue du navigateur. Type de données : Chaîne
Longueur: Variable, 1 à 8 caractères
Oui
browserScreenHeight Hauteur totale de l’écran du titulaire de carte en pixels. La valeur est fournie par les propriétés de hauteur d’écran du navigateur. Type de données : int
Contre 0 et 9999
Oui
browserScreenWidth Largeur totale de l’écran du titulaire de carte en pixels. La valeur est fournie par les propriétés de largeur d’écran du navigateur. Type de données : int
Contre 0 et 9999
Oui
browserTimeZone Décalage horaire entre l’heure UTC (temps universel coordonné) et l’heure locale du navigateur du titulaire de carte, en minutes. Type de données : int
Contre -840 et 720
Oui
browserUserAgent Contenu exact de l’en-tête d’agent utilisateur HTTP. * Longueur : Variable, au maximum 2048 caractères Type de données: Chaîne
Remarque : Si la longueur totale de l’agent utilisateur envoyé par le navigateur est supérieure à 2 048 caractères, le serveur 3DS tronque la partie excédentaire.
Oui
CN Nom du titulaire de carte (client) Longueur : Variable, au max. 35
Les caractères spéciaux sont autorisés, mais les guillemets doivent être évités. La plupart des acquéreurs ne vérifient pas le nom du client puisque les noms peuvent être écrits de différentes façons
Oui

*Il est inutile d'envoyer HTTP_ACCEPT et HTTP_USER_AGENT avec browserAcceptHeader et browserUserAgent, nous utiliserons les paramètres du navigateur.

Remarque: N'oubliez pas de calculer les paramètres dans votre signature SHA.

Veuillez trouver ci-dessous un exemple de javascript, afin de collecter ces paramètres.

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

b. Paramètres supplémentaires requis (cf. Paramètres de requête additionnels)

c. Paramètres optionnels, mais recommandés (liste de paramètres) qui, s'ils sont envoyés, auront un impact positif sur les taux de conversion des transactions. Sur la base des informations contenues dans ces paramètres, un flux d'identification sans problème potentiel peut avoir lieu. Le titulaire de carte ne devra plus s'identifier et, par conséquent, la finalisation des transactions devrait être plus rapide. Par contre, si aucun de ces paramètres n'est fourni, il sera redirigé vers l'authentification normale.

Même si ces paramètres sont facultatifs, les principaux systèmes de cartes de paiement conseillent vivement de les inclure à votre demande pour favoriser la mise en place d’un flux fluide

ECOM_BILLTO_POSTAL_CITY
ECOM_BILLTO_POSTAL_COUNTRYCODE
ECOM_BILLTO_POSTAL_STREET_LINE1
ECOM_BILLTO_POSTAL_STREET_LINE2
ECOM_BILLTO_POSTAL_STREET_LINE3
ECOM_BILLTO_POSTAL_POSTALCODE
REMOTE_ADDR
CN
EMAIL

Notre système reçoît le numéro de carte dans votre requête et vérifie immédiatement en ligne si la carte est enregistrée dans le repertoire VISA/MasterCard/JCB (enregistré veut dire que l’identification est possible pour le numéro de carte, par exemple la carte est une carte 3-D Secure)

2. Sur la base de la réponse du répertoire du système, si le titulaire de carte est enregistré au 3-D Secure, deux flux potentiels sont prévus, en fonction de la fourniture ou non des paramètres supplémentaires mentionnés au point 1.c (Paramètres optionnels, mais recommandés: liste de paramètres) ci-dessus

2.1. Un flux sans problème : Le titulaire de carte est authentifié avec succès et ne doit pas effectuer de procédure supplémentaire. L'étape 3 est donc réalisée.

2.2. Un flux avec processus d'identification : Le titulaire de carte doit s'identifier de façon plus précise.

i. La réponse à la demande DirectLink contient un statut de paiement spécifique et un code html qui a été renvoyé au client pour commencer le processus d'identification (cf. champs supplémentaires renvoyés). Le bloc de code html commencera automatiquement le processus d'identification entre le titulaire de carte (client) et sa banque émettrice.

ii. Le porteur de carte s’identifie sur la page de sa banque émettrice.

iii. Notre système reçoît la réponse d’identification de la part de l’émetteur.

iv. Si l’identification est réussie, notre système soumettra la transaction financière en elle-même à l’acquéreur.

3. Vous recevez le résultat de l’identification globale et du processus d’autorisation en ligne via des canaux de feedback en mode e-Commerce.

9.2.1 Paramètres de requête additionnels

En dehors des paramètres standards DirectLink, vous devez également envoyer les informations suivantes:

Paramètre Explication
FLAG3D

Valeur Fixe: ‘Y’;

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

HTTP_ACCEPT 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 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)
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.
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.
PARAMPLUS Champs utilisés pour les paramètres divers ainsi que leurs valeurs et qui doivent être retournés dans la requête post-sale ou la redirection finale.
COMPLUS Champ utilisé pour soumettre un valeur qui doit être retournée dans la requête post-sale ou dans l’output.
LANGUAGE Langue du client, par exemple: “en_US”.
Optionnel
TP Afin de changer la disposition de la page "order_A3DS", vous pouvez envoyer un nom de template/url avec le paramètre.

*Il est inutile d'envoyer HTTP_ACCEPT et HTTP_USER_AGENT si browserAcceptHeader et browserUserAgent sont utilisés.

Pour des details complémentaires sur ces champs, veuillez vous referrer au retour d'information sur la transaction.

9.2.2 Champs de retour additionnels

Si le porteur de carte n’est pas enregistré, la réponse <%DIRECTLINK%> habituelle est retournée. Si le porteur de carte est enregistré, les champs (additionnels) suivants seront retourné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.

9.2.3 3-D Secure v2.1 MasterCard+

Pour maximiser les chances de flux sans problème, MasterCard a mis au point l’extension spécifique « MasterCard 2.1+ ». Cela signifie que vous pouvez envoyer trois paramètres supplémentaires en plus des paramètres recommandés.

ParamètreNomDescriptionFormat
Mpi.merchantFraudRate Taux de fraude chez les marchands Le taux de fraude chez les marchands dans l’EEE (l’ensemble des fraudes dans l’EEE divisé par l’ensemble des volumes de cartes dans l’EEE) calculé conformément aux normes techniques réglementaires (Regulatory Technical Standards, ou RTS) PSD2.

Assurez-vous de calculer le taux conformément à l’article 19 des RTS PSD2 étant donné que ni MasterCard ni nous ne validerons le résultat.

Longueur : max. 2 caractères
Format : entier 1 => 99
Valeurs acceptées :

  • 1 (représente un taux de fraude inférieur ou égal à 1 point de base [pb], c’est-à-dire 0,01 %)
  • 2 (représente un taux de fraude compris entre 1 pb + - et 6 pb)
  • 3 (représente un taux de fraude compris entre 6 pb + - et 13 pb)
  • 4 (représente un taux de fraude compris entre 13 pb + - et 25 pb)
  • 5 (représente un taux de fraude supérieur à 25 pb)

Mpi.secureCorporatePayment Paiement professionnel sécurisé Indique que des processus et procédures de paiement dédiés ont été utilisés et que l’exemption potentielle pour paiement professionnel sécurisé s’applique.
Envoyez ce champ uniquement avec Y si le champ d’exemption de l’acquéreur est vierge, puisque
l’exemption de l’acquéreur et le paiement sécurisé sont mutuellement exclusifs.
Cependant, le serveur de répertoire (SR) ne validera pas les conditions dans l’extension. Le SR transmettra les données telles qu’elles ont été envoyées.
Facultativement, vous pouvez indiquer si elles s’appliquent aux processus et protocoles dédiés conformément à l’article 17 des RTS PSD2, ce qui serait susceptible de permettre à l’émetteur à réclamer l’exemption pour paiement professionnel sécurisé.

Longueur : max. 1 caractère
Format accepté : booléen
Valeur acceptée :

  • Y
  • N
Mpi.threeDSRequestorChallengeIndicator Indicateur de procédé d’identification marchand Indique si vous demandez un procédé d’identification pour cette transaction. Par exemple :
Pour 01-PA, il est possible que vous ayez des inquiétudes concernant la transaction et demandiez un procédé d’identification.
Pour 02-NPA, un procédé d’identification pourrait s’avérer nécessaire lors de l’ajout d’une nouvelle carte à un portefeuille.

Pour les mandats locaux/régionaux ou les autres variables.

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

L’envoi de ces paramètres fournira beaucoup plus d’informations à toutes les parties impliquées. Cela entraînera non seulement plus de flux sans problème, mais aussi des taux d’acceptation plus élevés et moins de cas de fraude.
Veuillez noter que ces paramètres supplémentaires fonctionnent uniquement pour les transactions MasterCard. Les utiliser avec toute autre méthode de paiement n’aura aucun effet.

9.2.4 Commentaires

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

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

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

Identification incorrecte

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

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9.3 Exclusions et exceptions pour 3DSv2

9.3.1 3DSv2 et exclusions

Avec l’introduction de 3DSv2, l’authentification du titulaire de la carte sera obligatoire, tel que défini par la Directive sur les services de paiement 2 (2015/2366 - DSP 2) de l’UE Néanmoins, certaines transactions sont exclues de cette règle si l’un des cas suivants s’applique :

  • Commande mail / commande téléphonique (MOTO)
  • Le PSP du marchant (aussi appelé l’acquéreur) ou le PSP de l’acheteur (aussi appelé le fournisseur de méthode de paiement de l’acheteur) est hors de la zone EEE.
  • Les cartes de paiement anonymes avec une valeur maximale de 150 € (article 63)
  • MIT - Transactions Initiées par le Marchant

9.3.2 Flux frictionless/avec identification pour la SCA et 3DS

Ce nouveau règlement traite notamment du concept d’authentification forte du client (soit SCA pour « Strong Customer Authentication »). Ce processus suggère que l’émetteur (la banque du titulaire de la carte) demande au titulaire de la carte des informations supplémentaires. Dans ce cas, le processus d’authentification aboutira à un flux avec identification (exigeant que le titulaire de la carte s’authentifie de manière active) plutôt qu’un flux frictionless (n’exigeant aucune authentification de la part du titulaire de la carte).

En revanche, nous offrons à nos commerçants la possibilité d’indiquer le flux qu’ils préfèrent. À ces fins, des paramètres supplémentaires seront envoyés afin que l’émetteur puisse procéder à une évaluation des risques. En fonction de la décision de l’émetteur, un flux frictionless peut avoir lieu. Dans certains cas, le système 3DS peut même être ignoré si des exceptions particulières s’appliquent.

9.3.3 Indication du flux préféré

Pour indiquer sa préférence pour un flux frictionless au cours de la demande d’authentification, le commerçant peut envoyer le paramètre supplémentaire Mpi.threeDSRequestorChallengeIndicator. En fonction de l’évaluation du risque de fraude effectuée par le commerçant, des valeurs particulières peuvent être envoyées (soit 02 pour l’évaluation d’un risque faible et 03 pour l’évaluation d’un risque élevé).

Paramètre Valeurs Obligatoire/Facultatif
Mpi.threeDSRequestorChallengeIndicator 01 = aucune préférence
02 = aucun processus d’identification requis
03 = processus d’identification requis : en fonction de la préférence du marchand
04 = processus d’identification requis : Mandat
Obligatoire (si vous souhaitez un flux spécifique)

Le commerçant peut ensuite déterminer si le flux frictionless/taux de conversion est approprié en envoyant davantage de champs facultatifs.

9.3.4 Exceptions pour 3DS

Pour certaines transactions, le commerçant peut ignorer le système 3DS (aboutissant à un flux frictionless) et les autoriser directement. Ce processus est limité aux transactions qui sont exclues de la SCA (tel que décrit ci-dessus) ou qui peuvent faire l’objet d’exceptions particulières. Ces exceptions doivent stipuler dans un accord conclu entre le commerçant et son acheteur. Dans ce cas, le commerçant doit préciser qu’il souhaite ignorer le processus d’authentification en envoyant ces paramètres supplémentaires :


Paramètres Valeurs Obligatoire/Facultatif
FLAG3D
N = Ignorer le processus d’authentification 3DS
Obligatoire (dans le cas où 3DS est ignoré)
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é)
Obligatoire (dans le cas où 3DS est ignoré)

* Analyse de risques de la transaction

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.