Guide d’implémentation
- Interface avec la plateforme de paiement -
Paramétrage avancé
Version 2.6
Rédaction, Vérification, Approbation
Rédaction Vérification Approbation
Nom Date/Visa Nom Date/Visa Nom Date/Visa
Lyra-Network 30/04/2012 Lyra-Network 30/04/2012 Lyra-Network 30/04/2012
Version Auteur Date Commentaires
2.6 Lyra-Network 30/04/2012 Mise à jour des codes langues pour la variable
vads_languages
Mise à jour de la liste de moyens de paiement.
Ajout de la fonction MULTI_EXT pour la variable
vads_payment_config
2.5 Lyra-Network 16/02/2012 Correction sur la longueur des champs « phone »
2.4 Lyra-Network 22/07/2011 Ajout d’information sur un ensemble de champs
2.3 Lyra-Network 25/06/2011 Ajout de nouveaux champs
2.2 Lyra-Network 28/09/2010 Précisions apportées
2.1 Lyra-Network 26/03/2010 Modification documentaire
2.0 Lyra-Network 22/02/2010 Version initiale.
Confidentialité
Toutes les informations contenues dans ce document sont considérées comme
confidentielles. L’utilisation de celles-ci en dehors du cadre de cette consultation ou la
divulgation à des personnes extérieures est soumise à l’approbation préalable de Lyra
Network.
Historique du document
SOMMAIRE
1 PRINCIPE GENERAL ............................................................................................................................... 1
1.1 INTRODUCTION ...................................................................................................................................... 1 1.2 TRANSACTION E-COMMERCE « STANDARD » (EC4) .............................................................................. 1 1.3 AUTRES CAS D’USAGE ........................................................................................................................... 3
1.3.1 Transaction E-COMMERCE avec acquisition des données cartes par le commerçant .................. 3 1.3.1.1 Authentification 3D-Secure déléguée à la plateforme (EC1) ...................................................................... 4 1.3.1.2 Authentification 3D-Secure réalisée par le commerçant (EC2) .................................................................. 4
1.3.2 Transaction VENTE A DISTANCE ................................................................................................. 5 1.3.2.1 Acquisition des données cartes par le commerçant (VAD1) ....................................................................... 5 1.3.2.2 Acquisition des données cartes déléguée à la plateforme de paiement (VAD2) ......................................... 5
1.4 SECURITE ............................................................................................................................................... 6
2 REDIRECTION VERS LA PLATEFORME DE PAIEMENT .............................................................. 7
2.1 FORMAT ET CODAGE DES PARAMETRES .................................................................................................. 7 2.2 LISTE DES PARAMETRES ........................................................................................................................... 8
2.2.1 Format d’échange ........................................................................................................................... 8 2.2.2 Description détaillée des paramètres ............................................................................................ 11
2.3 SIGNATURE .......................................................................................................................................... 24
3 RETOUR VERS LE MARCHAND ......................................................................................................... 25
3.1 RETOUR VERS LE SITE MARCHAND (REPONSE CONDITIONNEE) .............................................................. 25 3.1.1 Liste des paramètres de retour ...................................................................................................... 25 3.1.2 Signature ....................................................................................................................................... 30
3.2 REPONSE DE SERVEUR A SERVEUR (REPONSE SYSTEMATIQUE) ................................................................ 30
4 COMMENT ACTIVER LA BOUTIQUE EN PRODUCTION ? ......................................................... 32
4.1 RECUPERATION DU « CERTIFICAT » DE TEST ET DE L’IDENTIFIANT DU SITE (SITE_ID) .................................. 32 4.2 REALISATION DES PARAMETRAGES DE LA BOUTIQUE .............................................................................. 33 4.3 PHASE DE TEST & CARTES A UTILISER ..................................................................................................... 34 4.4 GENERATION DU CERTIFICAT DE PRODUCTION ..................................................................................... 36
4.4.1 Génération du certificat de production et modification du champ "ctx_mode" ............................ 37
5 ASSISTANCE TECHNIQUE ................................................................................................................... 37
6 ACRONYMES ET GLOSSAIRE ............................................................................................................ 38
6.1 ACRONYMES ....................................................................................................................................... 38 6.2 GLOSSAIRE .......................................................................................................................................... 38
7 ANNEXES .................................................................................................................................................. 41
7.1 EXEMPLES D’IMPLEMENTATION ............................................................................................................. 41 7.1.1 Contrôle de la signature (Java)..................................................................................................... 41 7.1.2 Acquisition des données carte déléguée à la plateforme (PHP) ................................................... 43 7.1.3 Acquisition des données carte par le commerçant (PHP) ............................................................. 44 7.1.4 Contrôle des données reçues de la plateforme (PHP) .................................................................. 45
7.2 EXEMPLES DE PAGES DE LA PLATEFORME DE PAIEMENT ......................................................................... 47 7.3 PERSONNALISATION DES PAGES DE PAIEMENT A L’AIDE DU PARAMETRE « VADS_THEME_CONFIG ». ..... 50
7.3.1 Principe de fonctionnement ........................................................................................................... 50 7.3.2 Exemple d’utilisation..................................................................................................................... 51
Descriptif de l’interface vers la page de paiement
©Lyra Network- 1/52
1 PRINCIPE GENERAL
1.1 Introduction
Ce document a pour objet de décrire les différents types d’appels vers la plateforme
de paiement que peut être amené à réaliser un commerçant dans son usage
quotidien, ainsi que leurs modalités d’implémentation.
1.2 Transaction e-commerce « standard » (EC4)
La cinématique d'échange est la suivante :
1) Une fois la commande de l'internaute finalisée, le site marchand redirige celui-
ci vers la plateforme de paiement. Cette redirection prendra la forme d'un
formulaire HTTP POST en HTTPS contenant des paramètres décrits dans le
chapitre 2.2.1.
2) La plateforme de paiement, après vérification des paramètres et de leur
signature, présentera soit une page de sélection du type de carte, soit
directement la saisie correspondante à la carte lorsqu'il n'y a pas
d'ambiguïté ou lorsque le moyen de paiement a été forcé dans le
formulaire.
3) La plateforme de paiement affichera une page de saisie de numéro de
carte, date d'expiration et cryptogramme visuel. En cas de validation, une
authentification 3D-Secure aura éventuellement lieu, puis une demande
d'autorisation sera effectuée auprès de la banque du client, en plus des
contrôles de fraude internes de la plateforme de paiement.
4) Une page de résumé sera présentée en cas de succès ou d'échec, avec un
bouton de retour vers le site marchand.
Vu de l’internaute, la cinématique de paiement est représentée sur le schéma ci-
dessous :
Dans une configuration e-commerce standard, un webmaster n’a besoin de développer que le
cas d’usage décrit ci-dessous et référencé EC4 dans la suite de ce document.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 2/52
2ème étape : CHOIX DU MOYEN DE PAIEMENT
1ère étape : VALIDATION DU PANIER
sur la boutique du commerçant
Internaute
Annulation
du paiement /
clic sur retour
boutique
3ème étape : SAISIE DES COORDONNEES BANCAIRES
4ème étape : AUTHENTIFICATION 3D-SECURE
& DEMANDE D’AUTORISATION
AFFICHAGE DE LA FACTURETTE DE PAIEMENTINFORMATION SUR L’ECHEC DU PAIEMENT
clic sur retour
boutique
clic sur retour
boutique
Descriptif de l’interface vers la page de paiement
©Lyra Network- 3/52
1.3 Autres cas d’usage
Le commerçant implémentera un ou plusieurs des cas d’usage décrits ci-après en
fonction de ses besoins. Le cas d’usage standard EC4 a été présenté dans le
paragraphe précédent :
Réf.cas d’usage
Canal de vente Acquisition des données cartes1
Authentification 3D-Secure
Cinématique détaillée
EC1 e-commerce Réalisée par le commerçant Déléguée à la plateforme §1.3.1.1
EC2 e-commerce Réalisée par le commerçant Réalisée par le commerçant §1.3.1.2
EC4
e-commerce Déléguée à la plateforme Déléguée à la plateforme §1.2
VAD1 Vente à distance Réalisée par le commerçant - §1.3.2.1
VAD2 Vente à distance Déléguée à la plateforme - §1.3.2.2
NB : Pour pouvoir mettre en place l’intégralité de ces cas d’usage, le commerçant
doit faire expressément la demande auprès de sa banque et souscrire à une offre
commerciale lui offrant ces fonctionnalités. Seul le cas d’usage EC4 présenté au
paragraphe 1.2 est proposé en standard aux commerçants.
1.3.1 Transaction E-COMMERCE avec acquisition des données cartes par le commerçant
Contrairement au cas standard défini dans le paragraphe 1.2, dans les cas décrits
ci-après, le commerçant procède lui-même à l’acquisition des données sensibles
(numéro de carte, cryptogramme visuel…) des cartes de ses clients sur son propre
site web e-commerce.
Cet usage requiert que le commerçant soit certifié PCI-DSS.
1 Précise si l’acquisition des données sensibles de la carte du client (n° de carte, cryptogramme visuel,
etc.) est réalisée directement sur le site du commerçant, c’est-à-dire si l’acquisition est internalisée chez
le commerçant, ou si elle est réalisée sur les pages de paiement de la plateforme Systempay (sur un
mode de délégation à la plateforme).
Avertissement :
L’acquisition de données cartes par le commerçant nécessite que sa plateforme d’acquisition
soit conforme et certifiée PCI-DSS.
Pour plus d’informations sur cette norme sécuritaire, veuillez consulter l’URL suivante :
https://www.pcisecuritystandards.org/
Descriptif de l’interface vers la page de paiement
©Lyra Network- 4/52
1.3.1.1 Authentification 3D-Secure déléguée à la plateforme (EC1)
La cinématique d'échange est la suivante :
1) Une fois la commande de l'internaute complète, le site marchand lui présente
une page lui permettant de sélectionner son type de carte, ainsi que de
saisir le numéro de carte correspondant, sa date d’expiration, et son
cryptogramme visuel, ainsi que toute autre donnée de la carte utile pour
le paiement.
2) A l’aide de ces informations collectées, le site marchand effectue une
redirection vers la plateforme de paiement sous la forme d'un formulaire
HTTP POST en HTTPS contenant des paramètres décrits dans le chapitre
2.2.1.
3) La plateforme de paiement, après vérification des paramètres et de leur
signature, procédera si nécessaire à l’authentification 3D-Secure de
l’internaute, à des contrôles locaux (contrôle anti-fraude), et enfin à une
demande d’autorisation auprès de la banque de l’internaute.
4) La réponse à toute cette série de contrôles est adressée par la plateforme de
paiement au serveur marchand. Le commerçant a à sa charge
l’affichage du résultat de la demande de paiement à l’internaute.
1.3.1.2 Authentification 3D-Secure réalisée par le commerçant (EC2)
La cinématique d'échange est la suivante :
1) Une fois la commande de l'internaute complète, le site marchand lui présente
une page lui permettant de sélectionner son type de carte, ainsi que de
saisir le numéro de carte correspondant, sa date d’expiration, et son
cryptogramme visuel.
2) Le commerçant procède à l’authentification 3D-Secure, par l’intermédiaire
de son propre MPI (Merchant Plug-In).
3) Dans le cas où l’authentification 3D-Secure n’a pas échoué, le site marchand
effectue une redirection vers la plateforme de paiement sous la forme
d'un formulaire HTTP POST en HTTPS contenant des paramètres décrits dans
le chapitre 2.2.1 (et précisant notamment les caractéristiques de la carte,
le résultat de l’authentification 3D-Secure, etc.).
4) La plateforme de paiement, après vérification des paramètres et de leur
signature, procédera si nécessaire à des contrôles locaux (contrôle anti-
Descriptif de l’interface vers la page de paiement
©Lyra Network- 5/52
fraude), et à une demande d’autorisation auprès de la banque de
l’internaute.
5) La réponse globale est adressée par la plateforme de paiement au serveur
marchand. Le commerçant a à sa charge l’affichage du résultat de la
demande de paiement à l’internaute.
1.3.2 Transaction VENTE A DISTANCE
On appelle transaction VAD (Vente à distance) un paiement initié depuis tout autre
moyen qu’un site web commerçant. Il peut s’agir d’une saisie manuelle, d’un
paiement initié via un Serveur Vocal Interactif, etc. Ces transactions ne font pas
l’objet de garantie de paiement.
1.3.2.1 Acquisition des données cartes par le commerçant (VAD1)
La cinématique d'échange est la suivante :
1) Une fois l’intégralité des données nécessaires au paiement collectées
(montant, devise, n° de carte, date d’expiration, etc.), le serveur
marchand effectue une redirection vers la plateforme de paiement sous
la forme d'un formulaire HTTP POST en HTTPS contenant des paramètres
décrits dans le chapitre 2.2.1.
2) La plateforme de paiement, après vérification des paramètres et de leur
signature, procédera si nécessaire à des contrôles locaux (contrôle anti-
fraude), et à une demande d’autorisation auprès de la banque du client.
3) La réponse est adressée par la plateforme de paiement au serveur marchand
qui se charge de la finalisation du paiement auprès du client.
1.3.2.2 Acquisition des données cartes déléguée à la plateforme de paiement (VAD2)
La cinématique d'échange est la suivante :
1) Le serveur marchand, sur action d’un opérateur du commerçant, effectue
une redirection vers la plateforme de paiement sous la forme d'un
formulaire HTTP POST en HTTPS contenant des paramètres décrits dans le
chapitre 2.2.1 (montant, devise, etc.)
2) La plateforme de paiement, après vérification des paramètres et de leur
signature, présentera soit une page de sélection du type de carte à
l’opérateur, soit directement la saisie correspondante à la carte lorsqu'il n'y
a pas d'ambiguïté.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 6/52
3) La plateforme de paiement affichera une page de saisie de numéro de
carte, date d'expiration et cryptogramme visuel à l’opérateur. En cas de
validation, une demande d'autorisation sera effectuée auprès de
l'acquéreur concerné, en plus des contrôles de fraude internes de la
plateforme de paiement.
4) Une page de résumé sera présentée à l’opérateur, en cas de succès ou
d'échec.
1.4 Sécurité
Dans la communication entre la plateforme de paiement et le site marchand,
un mécanisme de signature est à mettre en place. Les échanges étant effectués
par paramètres de formulaire, l'un de ces paramètres sera la signature.
La signature sera générée comme suit :
- Création d'une chaîne de caractère représentant la concaténation de
valeurs de certaines données du formulaire, séparées par le caractère " + ".
- Ajout à cette chaîne d'un " certificat " numérique (de test ou de
production selon le contexte).
- Hachage de la chaîne résultante avec l'algorithme SHA1.
La plateforme de paiement effectuera obligatoirement la vérification de la
signature. Il est de la responsabilité du commerçant de vérifier à son tour les
données transmises en retour, notamment pour mettre en œuvre un mécanisme
de validation de commande.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 7/52
2 REDIRECTION VERS LA PLATEFORME DE PAIEMENT
Cette redirection est effectuée via un formulaire HTTP POST. Le formulaire contient
des champs décrits ci-dessous, ainsi qu'une signature basée sur une partie de ces
champs. L’URL de la plateforme de paiement est la suivante :
https://paiement.systempay.fr/vads-payment/
2.1 Format et codage des paramètres
Aux chapitres suivants, les paramètres et leur format sont listés dans des tableaux,
dont voici la légende :
- Nom : indique le nom du paramètre, tel qu’ils seront utilisés dans les requêtes
HTTP.
- Format : indique le format des données, selon la codification suivante :
Notation Description
a Caractères alphabétiques (de ‘A’ à ‘Z’ et de ‘a’ à ‘z’)
n Caractères numériques
s Caractères spéciaux
an Caractères alphanumériques
ans Caractères alphanumériques et spéciaux
3 Longueur fixe de 3 caractères
…12 Longueur variable jusqu’à 12 caractères
- Exemple : représente un exemple de codage correct des données.
- Présence Obligatoire : indique si la présence du paramètre est obligatoire.
Attention, un paramètre obligatoire peut être vide.
Notation Signification
X Obligatoire
C Conditionnel : la condition rendant ce paramètre obligatoire est précisée par une note
F Facultatif
. Non avenu
- Code : en cas d’erreur dans l’interfaçage entre le site marchand et la
plateforme de paiement, cette dernière indiquera par un code numérique le
paramètre fautif dans le champ vads_extra_result (cf. §3.1.1).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 8/52
2.2 Liste des paramètres
2.2.1 Format d’échange
Rappel de la nomenclature utilisée :
Réf.cas d’usage
Canal de vente Acquisition des données cartes
Authentification 3D-Secure
EC1 e-commerce Réalisée par le commerçant Déléguée à la plateforme
EC2 e-commerce Réalisée par le commerçant Réalisée par le commerçant
EC4
e-commerce Déléguée à la plateforme Déléguée à la plateforme
VAD1 Vente à distance Réalisée par le commerçant -
VAD2 Vente à distance Déléguée à la plateforme -
Nom Format Code Présence Obligatoire
E-commerce Vente A Distance EC1 : e-commerce – acquisition commerçant – 3DS délégué
EC2 : e-commerce – acquisition commerçant – 3DS
commerçant
EC4 : e-commerce – acquisition déléguée – 3DS délégué VAD1 : Vente à distance – acquisition commerçant VAD2 : Vente à distance – acquisition déléguée
EC1 EC2 EC4
VAD1 VAD2
signature an40 X X X X X
vads_action_mode 47 X X X X X
vads_amount n..12 9 X X X X X
vads_available_languages F F F F F
vads_capture_delay n..3 6 F F F F F
vads_card_info ans..255
44 C(6) C(6) . C(6) .
vads_card_number ns..19 40 X X . X .
vads_card_options ans..255
45 C(6) C(6) . C(6) .
vads_contracts ans..25
5
62 C(3) C(3) C(3) C(3) C(3)
vads_contrib ans..25
5
31 F F F F F
vads_ctx_mode 11 X X X X X
vads_currency n3 10 X X X X X
vads_cust_address an..255 19 F F F F F
vads_cust_cell_phone an..32 77 F F F F F
vads_cust_city an..32 21 F F F F F
vads_cust_country a2 22 F F F F F
vads_cust_email an.127 15 C(1) C(1) C(1) C(1) C(1)
vads_cust_id an..63 16 F F F F F
vads_cust_name an..127 18 F F F F F
vads_cust_phone an..63 23 F F F F F
vads_cust_title an..63 17 F F F F F
vads_cust_zip an..63 20 F F F F F
vads_cvv n..4 43 C(5) C(5) . C(5) .
Descriptif de l’interface vers la page de paiement
©Lyra Network- 9/52
Nom Format Code Présence Obligatoire
E-commerce Vente A Distance EC1 : e-commerce – acquisition commerçant – 3DS délégué
EC2 : e-commerce – acquisition commerçant – 3DS
commerçant
EC4 : e-commerce – acquisition déléguée – 3DS délégué VAD1 : Vente à distance – acquisition commerçant VAD2 : Vente à distance – acquisition déléguée
EC1 EC2 EC4
VAD1 VAD2
vads_expiry_month n1..2 41 C(4) C(4) . C(4) .
vads_expiry_year n4 42 C(4) C(4) . C(4) . vads_language a2 12 F F F F F vads_order_id an..12 13 F F F F F vads_order_info an..255 14 F F F F F vads_order_info2 an..255 14 F F F F F vads_order_info3 an..255 14 F F F F F vads_page_action 46 X X X X X vads_payment_cards an..127 8 F vads_payment_config 7 X X X X X vads_payment_src a..5 60 . . . X X vads_redirect_error_message F F F F F vads_redirect_error_timeout 36 F F F F F vads_redirect_success_message
F F F F F
vads_redirect_success_timeout 34 F F F F F vads_return_get_params an 39 F F F F F vads_return_mode 48 C(2) C(2) C(2) C(2) C(2) vads_return_post_params an 38 F F F F F vads_ship_to_city 83 F F F F F vads_ship_to_country a2 86 F F F F F vads_ship_to_name 80 F F F F F vads_ship_to_phone_num 87 F F F F F vads_ship_to_state 84 F F F F F vads_ship_to_street 81 F F F F F vads_ship_to_street2 82 F F F F F vads_ship_to_zip an..63 85 F F F F F vads_shop_name F F F F F vads_shop_url F F F F F vads_site_id n8 2 X X X X X vads_theme_config 32 F F F F F vads_threeds_cavv ans28 52 . X . . . vads_threeds_cavvAlgorithm n1 55 . X . . . vads_threeds_eci n2 53 . X . . . vads_threeds_enrolled a1 51 . X . . . vads_threeds_mpi n1 50 F X F . . vads_threeds_status a1 56 . X . . . vads_threeds_xid ans28 54 . X . . . vads_trans_date n14 4 X X X X X
Descriptif de l’interface vers la page de paiement
©Lyra Network- 10/52
Nom Format Code Présence Obligatoire
E-commerce Vente A Distance EC1 : e-commerce – acquisition commerçant – 3DS délégué
EC2 : e-commerce – acquisition commerçant – 3DS
commerçant
EC4 : e-commerce – acquisition déléguée – 3DS délégué VAD1 : Vente à distance – acquisition commerçant VAD2 : Vente à distance – acquisition déléguée
EC1 EC2 EC4
VAD1 VAD2
vads_trans_id n6 3 X X X X X vads_url_cancel ans..127 27 F F F F F vads_url_check ans..127 33 F F F F F vads_url_error ans..127 29 F F F F F vads_url_referral ans..127 26 F F F F F vads_url_refused ans..127 25 F F F F F vads_url_return ans..127 28 C(7) C(7) F C(7) F vads_url_success ans..127 24 F F F F F vads_user_info ans..255 61 . . . F F vads_validation_mode n..1 5 F F F F F vads_version 1 X X X X X
C(1) Obligatoire si souscription à l’envoi d’e-mail de confirmation de paiement au client
C(2)
C(3)
Obligatoire si souhait du commerçant de recevoir la réponse à la demande sur l’URL internet
de retour boutique en formulaire GET ou POST (après clic internaute sur bouton retour
boutique).
Ce paramétrage n’impacte pas la transmission, ni les paramètres de transfert, de la réponse
de serveur à serveur (URL serveur commerçant).
Obligatoire si le numéro de contrat commerçant à utiliser n’est pas celui configuré par défaut
sur la plateforme de paiement
C(4) Obligatoire si acquisition des données de la carte par le commerçant et carte CB, Visa,
MasterCard, Maestro, e-Carte Bleue ; Conditionnelle pour les autres typologies de carte.
C(5)
C(6)
Obligatoire si acquisition des données de la carte par le commerçant et carte CB, Visa,
MasterCard, e-Carte Bleue ; Conditionnelle pour les autres typologies de carte.
Obligatoire si acquisition des données de la carte par le commerçant et carte privative. Ne
pas utiliser pour cartes CB, Visa, MasterCard, e-Carte Bleue, Maestro, AMEX.
C(7) Obligatoire si acquisition des données de la carte par le commerçant et paramètres
vads_url_success, vads_url_referral, vads_url_refused, vads_url_cancel et vads_url_error
non renseignés.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 11/52
2.2.2 Description détaillée des paramètres
signature
Paramètre obligatoire permettant à la plateforme de vérifier la validité de la
requête transmise (voir chapitre 2.3).
vads_action_mode
Paramètre obligatoire indiquant le mode de fonctionnement de la plateforme :
- SILENT : correspond au cas où l’acquisition des données carte est effectuée
par le commerçant.
- INTERACTIVE : correspond au cas où l’acquisition des données carte est
déléguée à la plateforme.
vads_amount
Paramètre obligatoire. Montant de la transaction exprimé dans son unité
indivisible (en cents pour l'Euro).
Exemple :
- Pour une transaction de 10 euros et 28 centimes, la valeur du paramètre
attendue est 1028.
- Pour une transaction de 100 yens ou de 100 francs pacifique ( XPF ) la valeur
attendue est 100 et non 10000.
Attention : Un montant à zéro ou incorrect (présence de décimales) génère un
message d’incident technique associé à un code retour (vads_extra_result)
valorisé à 09.
vads_available_languages
Paramètre facultatif. Permet de spécifier les langues disponibles sur la page de
paiement (voir vads_language). Ce paramétre permet de faire afficher les
drapeaux nationaux pour changer de langue sur la page de paiement.
Si ce paramètre n’est pas présent alors toutes les langues supportées par la
plateforme de paiement seront proposées.
vads_capture_delay
Paramètre facultatif indiquant le délai en nombre de jours avant remise en
banque. Si ce paramètre n’est pas transmis, alors la valeur par défaut sera
utilisée. Cette dernière est paramétrable dans le back office Payzen par toutes
les personnes dûment habilitées.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 12/52
vads_card_info
Paramètre facultatif, à renseigner en fonction du type de carte défini par le
paramètre vads_payment_ cards et uniquement dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes. Définit des informations
spécifiques de la carte selon le formalisme suivant :
Information1=valeurInformation1;Information2=valeurInformation2
Exemple, pour une carte nécessitant de définir la date de naissance du porteur :
CARD_HOLDER_BIRTH_DAY=19780913
vads_card_options
Paramètre facultatif, à renseigner en fonction du type de carte défini par le
paramètre vads_payment_ cards et uniquement dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes. Définit des options
spécifiques de la carte selon le formalisme suivant :
Option1=valeurOption1;Option2=valeurOption2
Exemple, pour une carte nécessitant de définir le code d’opération commerciale
à employer pour le paiement :
OPERATION=100
vads_card_number
Paramètre obligatoire et à ne renseigner que dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes. Il permet de définir le
numéro de carte à utiliser pour la transaction.
Dans le cas de l’utilisation de ce paramètre, il est nécessaire de valoriser le
paramètre vads_payment_cards à la valeur effective de la carte utilisée.
L’ensemble des autres paramètres relatif aux informations de carte
(vads_expiry_month, vads_expiry_year, vads_cvv, vads_card_info,
vads_card_options) doivent être valorisés ou non en fonction du type de carte.
vads_contracts
Paramètre facultatif permettant de spécifier pour chaque réseau d’acceptation,
le contrat commerçant à utiliser. Le formalisme du paramètre est le suivant :
RESEAU1=contratReseau1;RESEAU2=contratReseau2;RESEAU3=contratReseau3
Les différents réseaux possibles étant :
Réseau Valorisation ‘vads_contracts’
American Express AMEX
CB CB
Descriptif de l’interface vers la page de paiement
©Lyra Network- 13/52
Par exemple, si vous disposez d’un 2ème contrat VAD de numéro 12312312 dans
votre banque, et que vous souhaitez enregistrer pour une commande donnée un
paiement par carte bancaire (Visa, MasterCard ou CB) sur ce contrat, alors il
faudra valoriser vads_contracts de la manière suivante :
CB=12312312
Remarque : ce paramètre est facultatif et n’est utile que dans le cas où vous
avez plusieurs contrats VAD sur le même réseau et si vous souhaitez en changer
dynamiquement en fonction du paiement. Si ce paramètre n’est pas renseigné
ou absent, alors le paiement sera enregistré sur votre contrat commerçant VAD
par défaut.
vads_contrib
Information complémentaire facultative destinée à indiquer le nom de la
contribution utilisée lors du paiement (joomla, oscommerce...). Si vous utilisez une
implémentation propriétaire, ce champ peut accueillir votre numéro de version
interne, par exemple.
vads_ctx_mode
Paramètre obligatoire indiquant le mode de sollicitation de la plateforme
de paiement :
- TEST : utilisation du mode test, nécessite d’employer le certificat de test
pour la signature.
- PRODUCTION : utilisation du mode production, nécessite d’employer le
certificat de production pour la signature.
vads_currency
Paramètre obligatoire indiquant la monnaie à utiliser, selon la norme ISO
4217 (code numérique).
Pour l’Euro, la valeur est 978.
Devise Codification ISO 4217
Dollar Australien 36
Dollar australien 036
Dollar canadien 124
Yuan chinois 156
Couronne danoise 208
Yen japonais 392
Couronne Norvégienne 578
Couronne suédoise 752
Franc suisse 756
Livre sterling 826
Dollar américain 840
Franc Pacifique 953
Euro 978
Descriptif de l’interface vers la page de paiement
©Lyra Network- 14/52
vads_cust_address
Paramètre facultatif. Adresse postale du client
vads_cust_cell_phone
Paramètre facultatif. Numéro de téléphone mobile du client
vads_cust_city
Paramètre facultatif. Ville du client
vads_cust_country
Paramètre facultatif. Code pays du client à la norme ISO 3166.
Pour la France, le code est FR.
vads_cust_email
Paramètre facultatif. Adresse e-mail du client, nécessaire pour lui envoyer un mail
récapitulatif de la transaction.
vads_cust_id
Paramètre facultatif. Identifiant du client chez le marchand.
vads_cust_name
Paramètre facultatif. Nom du client
vads_cust_phone
Paramètre facultatif. Numéro de téléphone du client
vads_cust_title
Paramètre facultatif. Civilité du client
vads_cust_zip
Paramètre facultatif. Code postal du client
vads_cvv
Paramètre facultatif, à ne renseigner que dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes et sous réserve du type de
carte défini par le paramètre vads_payment_cards.
Définit le cryptogramme visuel du porteur de la carte.
vads_expiry_month
Paramètre facultatif, à ne renseigner que dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes et sous réserve du type de
carte défini par le paramètre vads_payment_cards.
Définit le mois d’expiration de la carte (valeur de 1 à 12).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 15/52
vads_expiry_year
Paramètre facultatif, à ne renseigner que dans le cas où le commerçant
procède lui-même à l’acquisition des données cartes et sous réserve du type de
carte défini par le paramètre vads_payment_cards.
Définit l’année d’expiration de la carte qui doit être représentée sur 4 chiffres.
vads_language
Paramètre facultatif. Langue dans laquelle doit être affichée la page de
paiement (norme ISO 639-1).
Les langues possibles sont les suivantes :
Langue Codification ISO 639-1 Allemand de
Anglais en
Chinois zh
Espagnol es
Français fr
Italien it
Japonais jp
Portugais pt
Néerlandais nl
Par défaut, le français est sélectionné.
vads_order_id
Paramètre facultatif. Numéro de commande qui pourra être rappelé dans l'e-
mail de confirmation de paiement adressé au client. Champ au format
alphanumérique. Seul le caractère spécial « - » est autorisé.
vads_order_info, vads_order_info2, vads_order_info3
Champs libres facultatifs pouvant par exemple servir à stocker un résumé de la
commande.
vads_page_action
Ce paramètre est obligatoire et doit être valorisé à PAYMENT.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 16/52
vads_payment_cards
Ce paramètre est obligatoire dans le cas d’une acquisition par le commerçant,
facultatif sinon.
Les différents réseaux possibles sont :
Réseau de la carte Valorisation ‘payment_cards’
Américan Express AMEX
AURORE (multi enseigne) AURORE-MULTI
BUYSTER BUYSTER
CB CB
COFINOGA COFINOGA
e-carte bleue E-CARTEBLEUE
Eurocard / MasterCard MASTERCARD
JCB JCB
Maestro MAESTRO
ONEY ONEY
ONEY mode SANDBOX ONEY_SANDBOX
PAYPAL PAYPAL
PAYPAL mode SANDBOX PAYPAL_SB
PAYSAFECARD PAYSAFECARD
Visa VISA
Dans le cas d’une acquisition des données bancaires par le commerçant, il doit
obligatoirement contenir le réseau de la carte.
Dans le cas où l’acquisition des données cartes est déléguée à la plateforme de
paiement, il contient la liste des types de cartes disponibles pour la boutique,
séparés par des " ;". Si la liste ne contient qu'un type de carte, la page de saisie
des données du paiement sera directement présentée. Sinon la page de
sélection du moyen de paiement sera présentée. Si ce paramètre est vide alors
l’ensemble des moyens de paiement défini dans l’outil de gestion de caisse sera
présenté en sélection. Par défaut la valeur VIDE est conseillée.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 17/52
vads_payment_config
Ce paramètre obligatoire indique le type du paiement :
- SINGLE indique un paiement unitaire.
- MULTI indique un paiement en plusieurs fois. Dans ce cas, le paramètre est
constitué de la chaîne « MULTI: », suivi par des paires clés/valeurs séparées par
des « ; ». Les paramètres sont les suivants :
o « first » indique le montant du premier paiement.
o « count » indique le nombre de paiements total.
o « period » indique l’intervalle en nombre de jours entre 2 paiements.
Exemple :
vads_currency=978
vads_amount=10000
vads_payment_config=MULTI:first=5000;count=3;period=30
Dans cette configuration :
- Le montant total de l’achat est de 100 euros,
- Un premier paiement de 50 euros sera effectué à aujourd’hui +
« vads_capture_delay » jours.
- Un deuxième paiement de 25 euros sera effectué à aujourd’hui + «
vads_capture_delay » + 30 jours.
- Un troisième et dernier paiement de 25 euros sera effectué à aujourd’hui +
« vads_capture_delay » + 60 jours.
Le total des 3 transactions fait bien sûr 100 euros au final.
Définir un échéancier :
- MULTI_EXT permet de définir un échéancier personnalisé. Vous pourrez ainsi
définir la date et le montant de chaque échéance. Dans ce cas, le
paramètre est constitué de la chaîne :
MULTI_EXT:date1=montant1;date2=montant2;date3=montant3 etc...
Attention, la somme totale des montants doit être égale à la valeur de
variable vads_amount.
Exemple :
vads_currency=978
vads_amount=10000
vads_payment_config= MULTI_EXT:20120601=5000;20120701=2500;20120808=2500
Dans cette configuration :
- le premier paiement aura lieu le 1er juin 2012 pour un montant de 50€.
- le second paiement aura lieu le 1er juillet 2012 pour un montant de 25€.
- le dernier paiement aura lieu le 8 août pour un montant de 25€.
On note dans ce cas que la somme des montants des 3 échéances de
paiement (5000+2500+2500) est égale à la valeur de vads_amount.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 18/52
La date de la dernière échéance ne peut être supérieure à 1 an par
rapport à la date de soumission du formulaire.
Exemple : Un formulaire posté à la plateforme de paiement le
23/04/2012 pourra présenter une dernière échéance au maximum au
23/04/2013
Si la date de la dernière échéance est supérieure à la date de validité
de la carte aucune échéance ne sera enregistrée et l’internaute
obtiendra le message d’erreur suivant :
vads_payment_src
Paramètre obligatoire pour un paiement de type Vente à Distance, facultatif
sinon. Il définit le canal du paiement :
- Paramètre non défini ou valeur vide, indique un paiement de type
eCommerce. Dans ce cas, la garantie de paiement est calculée
conformément aux options du commerce concerné.
- BO indique un paiement effectué depuis le « Back Office » (saisie manuelle).
- MOTO indique un paiement effectué par un opérateur suite à une
commande par téléphone ou eMail (Mail Or Telephone Order).
- CC indique un paiement effectué via un centre d’appel (Call Center).
- OTHER indique un paiement effectué par toute autre source que celles
précédemment définies.
Des informations complémentaires sur l’origine du paiement peuvent être
définies dans le paramètre vads_user_info.
NB : L’utilisation de ce paramétrage n’est permise que pour les
commerçants ayant souscrit une offre adéquate. Merci de contacter
votre chargé de clientèle bancaire pour plus d’informations.
vads_redirect_error_message
Paramètre facultatif permettant de spécifier le message en cas de paiement
refusé dans le cas d’une redirection automatique vers le site marchand.*
vads_redirect_error_timeout
Paramètre facultatif permettant de spécifier le délai avant redirection vers le site
marchand à la fin d’un paiement refusé*
Descriptif de l’interface vers la page de paiement
©Lyra Network- 19/52
vads_redirect_success_message
Paramètre facultatif permettant de spécifier le message à la fin d’un paiement
accepté dans le cas d’une redirection automatique vers le site marchand.*
vads_redirect_success_timeout
Paramètre facultatif permettant de spécifier le délai avant redirection vers le site
marchand à la fin d’un paiement accepté.*
* Se référer au Guide d'implémentation du retour automatique à la
boutique.
vads_return_get_params
Paramètre facultatif permettant de spécifier des paramètres supplémentaires qui
seront transmis à l’URL de retour sous la forme d’un formulaire HTTP GET (dans la
« query string »).
Exemple :
Vads_return_get_params=info1=France&info2=Allemagne&info3=Angleterre ( etc
..)
vads_return_mode
Paramètre permettant de conditionner le passage des paramètres aux URL de
retour vers le site marchand.
- Non défini, vide ou NONE : aucun paramètre ne sera passé à l’URL de retour.
- POST : les paramètres de retour seront transmis à l’URL de retour sous la forme
d’un formulaire HTTP POST.
- GET : les paramètres de retour seront transmis à l’URL de retour sous la forme
d’un formulaire HTTP GET (dans la « query string »).
Remarque :
Par défaut si ce paramètre est absent aucun paramètre ne sera renvoyé à la
boutique.
vads_return_post_params
Paramètre facultatif permettant de spécifier des paramètres supplémentaires qui
seront transmis à l’URL de retour sous la forme d’un formulaire HTTP POST.
Exemple :
Vads_return_post_params=info1=France&info2=Allemagne&info3=Angleterre (
etc ..)
vads_ship_to_city
Paramètre facultatif. Adresse de livraison : Ville du client
Descriptif de l’interface vers la page de paiement
©Lyra Network- 20/52
vads_ship_to_country
Paramètre facultatif. Adresse de livraison : Code pays du client à la norme ISO
3166.
Pour la France, le code est FR.
vads_ship_to_name
Paramètre facultatif. Adresse de livraison : Nom du client
vads_ship_to_phone_num
Paramètre facultatif. Adresse de livraison : Numéro de téléphone du client
vads_ship_to_state
Paramètre facultatif. Adresse de livraison : Etat du client
vads_ship_to_street
Paramètre facultatif. Adresse de livraison : Adresse du client
vads_ship_to_street2
Paramètre facultatif. Adresse de livraison : Deuxième ligne d’adresse du client
vads_ship_to_zip
Paramètre facultatif. Adresse de livraison : Code postal du client
vads_shop_name
Paramètre facultatif. Nom de boutique qui apparait dans les mails de
confirmation de paiement
vads_shop_url
Paramètre facultatif. URL de la boutique qui apparait sur la page de paiement et
les mails de confirmation de paiement.
vads_site_id
Paramètre obligatoire attribué lors de l'inscription à la plateforme de paiement.
Sa valeur est consultable sur l’interface de l’outil de gestion de caisse dans
l’onglet « Paramétrages » / « Boutique » par toutes les personnes habilitées.
vads_theme_config
Paramètre permettant de personnaliser certains paramètres de la page de
paiement standard de la plateforme, comme les logos, bandeaux ainsi que
certains messages. Se reporter à l’annexe pour plus d’informations.
vads_threeds_cavv
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Valeur de vérification du porteur de la carte, 28 caractères (encodés en base
64).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 21/52
vads_threeds_ cavvAlgorithm
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Algorithme utilisé pour la génération du code de vérification du porteur de la
carte :
o 0 =HMAC
o 1 =CVV
o 2 =CVV avec ATN
o 3 =MasterCard SPA
vads_threeds_eci
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Valeur de l’ECI (Electronic Commerce Indicator) sur 2 chiffres.
vads_threeds_enrolled
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Représente le statut d’enrôlement du porteur (Y, Authentication available, N =
Cardholder not participating, U = Unable to authenticate).
vads_threeds_mpi
Paramètre permettant de spécifier les modalités de l’authentification 3DS pour
les transactions e-commerce.
Valorisation
vads_threeds_mpi
Signification
Indéfini Authentification 3DS gérée par la plateforme de paiement
(selon configuration standard commerçant)
0 Authentification 3DS gérée par la plateforme de paiement
(selon configuration standard commerçant)
1
Authentification 3DS intégralement gérée par le commerçant.
Possible uniquement si paramètre vads_card_number
renseigné (saisie des données cartes chez le marchand).
Les données résultantes de l’authentification 3D-Secure
effectuée par le MPI du commerçant doivent alors être
transmises dans les champs du formulaire prévus à cet effet
(vads_threeds_enrolled, vads_threeds_cavv,
vads_threeds_eci, vads_threeds_xid, vads_threeds_
cavvAlgorithm, vads_threeds_status).
2 Authentification 3DS désactivée pour la transaction, quelle
que soit la configuration habituelle du commerçant
Descriptif de l’interface vers la page de paiement
©Lyra Network- 22/52
vads_threeds_status
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Statut de l’authentification :
o Y = Succès.
o N = Echec.
o U = Authentification ne pouvant être réalisée.
o A = Preuve de tentative d’authentification.
vads_threeds_xid
Paramètre requis lorsque l’authentification 3DS est à la charge du site marchand.
Identifiant de transaction déterminé par le marchant, 28 caractères (encodés en
base 64).
vads_trans_date
Ce paramètre est obligatoire. Correspond à la date locale du site marchand au
format AAAAMMJJHHMMSS.
vads_trans_id
Ce paramètre est obligatoire. Il est constitué de 6 caractères numériques et doit
être unique pour chaque transaction pour une boutique donnée sur la journée.
En effet l'identifiant unique de transaction au niveau de la plateforme de
paiement est constitué du vads_site_id, de vads_trans_date restreint à la valeur
de la journée (partie correspondant à AAAAMMJJ) et de vads_trans_id. Il est à la
charge du site marchand de garantir cette unicité sur la journée. Il doit être
impérativement compris entre 000000 et 899999. La tranche 900000 et 999999 est
interdite.
Remarque : une valeur de longueur inférieure à 6 provoque une erreur lors de
l’appel à l’URL de paiement. Merci de respecter cette longueur de 6 caractères.
vads_url_cancel
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé le client si celui-ci
appuie sur " annuler et retourner à la boutique " avant d'avoir procédé au
paiement.
vads_url_check
Paramètre facultatif. Permet de surcharger la valeur de l’url serveur saisie dans
l’outil de gestion de caisse.
vads_url_error
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé le client en cas
d'erreur de traitement interne.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 23/52
vads_url_referral
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé le client en cas de
refus d’autorisation avec le code 02 « contacter l’émetteur de la carte », après
appui du bouton " retourner à la boutique ".
vads_url_refused
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé le client en cas de
refus pour toute autre cause que le refus d’autorisation de motif 02 (contacter
l’émetteur de la carte), après appui du bouton " retourner à la boutique ".
vads_url_success
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé le client en cas de
succès du paiement, après appui du bouton " retourner à la boutique ".
vads_url_return
Paramètre facultatif. Dans le cas où l’acquisition des données bancaires est
déléguée à la plateforme de paiement, URL où sera redirigé par défaut le client
après un appui sur le bouton " retourner à la boutique ", si les URL
correspondantes aux cas de figure vus précédemment ne sont pas renseignées.
Si cette URL n’est pas présente dans la requête, alors c’est la configuration dans
l’outil de gestion de caisse qui sera prise en compte.
En effet il est possible de configurer des URL de retour, en mode TEST et en mode
PRODUCTION. Ces paramètres sont nommés « URL de retour de la boutique » et
« URL de retour de la boutique en mode test » respectivement, et sont accessibles
dans l’onglet « Configuration » lors du paramétrage d’une boutique.
Si toutefois aucune URL n’est présente, que ce soit dans la requête ou dans le
paramétrage de la boutique, alors le bouton « retourner à la boutique »
redirigera vers l’URL générique de la boutique (paramètre nommé « URL » dans la
configuration de la boutique).
vads_user_info
Paramètre facultatif spécifiant des informations complémentaires quant au
paiement. Dans le cas d’un paiement via une saisie manuelle, ce paramètre
contient l’identifiant de l’opérateur à l’origine de la transaction. Dans les autres
cas de paiement (eMail, téléphone…) tels que définis par le paramètre.
vads_payment_src, ce paramètre doit servir à identifier l’opérateur à l’origine de
la transaction.
vads_validation_mode
Descriptif de l’interface vers la page de paiement
©Lyra Network- 24/52
Paramètre précisant le mode de validation de la transaction (manuellement par
le commerçant, ou automatiquement par la plateforme).
Valorisation
‘vads_validation_mode’
Signification
Absent ou vide Configuration par défaut de la boutique retenue
(paramétrable dans l’outil de gestion de caisse)
0 Validation automatique
1 Validation manuelle
vads_version
Paramètre obligatoire et devant être valorisé à V2.
2.3 Signature
La signature sera constituée de l’intégralité des champs dont le nom commence par
la chaîne « vads_ ». Les champs doivent être triés par ordre alphabétique.
Les valeurs de ces champs doivent être concaténées entre elles avec le caractère
« + ».
Au résultat de cette concaténation, on concatènera la valeur du certificat employé
(certificat de test ou de production).
Exemple : si les paramètres de la requête sont les suivants :
- vads_version = V2
- vads_page_action = PAYMENT
- vads_action_mode = INTERACTIVE
- vads_payment_config = SINGLE
- vads_site_id = 12345678
- vads_ctx_mode = TEST
- vads_trans_id = 654321
- vads_trans_date = 20090501193530
- vads_amount = 1524
- vads_currency = 978
et Valeur du certificat en fonction du mode =1122334455667788
L’ordre alphabétique des paramètres est le suivant : vads_action_mode,
vads_amount, vads_ctx_mode, vads_currency, vads_page_action,
vads_payment_config, vads_site_id, vads_trans_date, vads_trans_id, vads_version.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 25/52
Il faudra rajouter à ces paramètres la valeur du certificat.
La chaîne à utiliser pour le hachage à l’aide de l’algorithme SHA-1 sera donc la
suivante :
INTERACTIVE+1524+TEST+978+PAYMENT+SINGLE+12345678+20090501193530+654321+
V2+1122334455667788
3 RETOUR VERS LE MARCHAND
3.1 Retour vers le site marchand (réponse conditionnée)
Le comportement de cette redirection dépend de la valeur du paramètre
vads_return_mode.
Si vads_return_mode est valorisé à vide ou NONE, aucun paramètre n’est passé en
retour vers le site marchand.
Sinon, si vads_return_mode est valorisé à POST ou GET, des paramètres de retour sont
passés respectivement sous la forme d’un formulaire HTTP POST, ou dans les
paramètres de la « query string ».
Le formulaire contient des champs décrits ci-dessous, ainsi qu'une signature basée
sur la totalité de ces champs. Le " certificat " employé est le même que celui de la
requête.
3.1.1 Liste des paramètres de retour
Nom Format Obligatoire Remarques
vads_action_mode oui idem requête
vads_amount oui idem requête
vads_auth_result n2 oui vide si erreur avant autorisation
vads_auth_mode oui MARK : prise d’empreinte FULL : autorisation du montant total (ou du montant initial dans le cas du paiement en N fois)
vads_auth_number n6 oui vide si autorisation échouée.
vads_capture_delay n..3 oui valeur par défaut ou valeur spécifiée dans requête
Dans le calcul de la signature, l’ordre alphabétique des paramètres doit être
respecté.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 26/52
Nom Format Obligatoire Remarques
vads_card_brand an..127 oui Réseau de la carte utilisé pour le paiement (si information disponible).
vads_card_number an..19 oui numéro masqué
vads_ctx_mode oui idem requête
vads_currency oui idem requête
vads_extra_result n2 oui numérique, peut être vide.
vads_payment_config oui idem requête
signature oui
vads_site_id oui idem requête
vads_trans_date oui idem requête
vads_trans_id oui idem requête
vads_validation_mode n1 oui valeur par défaut ou valeur spécifiée dans la requête
vads_warranty_result oui vide ou YES, NO, UNKNOWN
vads_payment_certificate an40 oui vide si paiement échoué
vads_result n2 oui numérique, toujours renseigné
vads_version oui Idem requête vads_order_id Idem requête
vads_order_info Idem requête
vads_order_info2 Idem requête
vads_order_info3 Idem requête
vads_cust_address Idem requête
vads_cust_country Idem requête
vads_cust_email Idem requête
vads_cust_id Idem requête
vads_cust_name Idem requête
vads_cust_phone Idem requête
vads_cust_title Idem requête
vads_cust_city Idem requête
vads_cust_zip Idem requête
vads_language valeur par défaut ou valeur spécifiée dans requête
vads_payment_src Idem requête
vads_user_info Idem requête
vads_theme_config Idem requête
vads_contract_used ans..250 Contrat commerçant utilisé
vads_expiry_month n..2 Idem requête
vads_expiry_year n4 Idem requête
vads_card_info ans..250 Idem requête
vads_card_options ans..250 Idem requête
vads_threeds_enrolled a1
vads_threeds_cavv ans28
vads_threeds_eci n2
vads_threeds_xid ans28
vads_threeds_cavvAlgorithm n1
vads_threeds_status a1
vads_threeds_sign_valid n1 vide ou 0/1
Descriptif de l’interface vers la page de paiement
©Lyra Network- 27/52
vads_action_mode, vads_amount, vads_currency, vads_payment_config,
vads_site_id, vads_trans_date, vads_trans_id, vads_version, vads_payment_src,
vads_user_info, vads_theme_config, vads_order_info, vads_order_info2,
vads_order_info3, vads_cust_address, vads_cust_country, vads_cust_email,
vads_cust_id, vads_cust_name, vads_cust_phone, vads_cust_title, vads_cust_city,
vads_cust_zip, vads_card_info, vads_card_options
Mêmes valeur que la requête.
vads_threeds_enrolled, vads_threeds_cavv, vads_threeds_eci, vads_threeds_xid,
vads_threeds_cavvAlgorithm, vads_threeds_status, vads_threeds_sign_valid
Mêmes valeurs que la requête si l’authentification 3D-Secure est réalisée par le
site marchand. Sinon, ces champs sont valorisés par le résultat de
l’authentification 3D-Secure faite via le MPI de la plateforme SystemPay.
vads_auth_result
Code retour de la demande d'autorisation retournée par la banque émettrice, si
disponible (vide sinon). auth_result Signification
00 transaction approuvée ou traitée avec succès
02 contacter l’émetteur de carte
03 accepteur invalide
04 conserver la carte
05 ne pas honorer
07 conserver la carte, conditions spéciales
08 approuver après identification
12 transaction invalide
13 montant invalide
14 numéro de porteur invalide
30 erreur de format
31 identifiant de l’organisme acquéreur inconnu
33 date de validité de la carte dépassée
34 suspicion de fraude
41 carte perdue
43 carte volée
51 provision insuffisante ou crédit dépassé
54 date de validité de la carte dépassée
56 carte absente du fichier
57 transaction non permise à ce porteur
58 transaction interdite au terminal
59 suspicion de fraude
60 l’accepteur de carte doit contacter l’acquéreur
61 montant de retrait hors limite
63 règles de sécurité non respectées
68 réponse non parvenue ou reçue trop tard
90 arrêt momentané du système
91 émetteur de cartes inaccessible
96 mauvais fonctionnement du système
94 transaction dupliquée
97 échéance de la temporisation de surveillance globale
98 serveur indisponible routage réseau demandé à nouveau
99 incident domaine initiateur
Descriptif de l’interface vers la page de paiement
©Lyra Network- 28/52
vads_auth_number
Numéro d'autorisation retourné par le serveur bancaire, si disponible (vide sinon).
vads_auth_mode
Indique comment a été réalisée la demande d’autorisation. Ce champ peut
prendre les valeurs suivantes :
- FULL : correspond à une autorisation du montant total de la transaction dans
le cas d’un paiement unitaire avec remise à moins de 6 jours, ou à une
autorisation du montant du premier paiement dans le cas du paiement en N
fois, dans le cas d’une remise de ce premier paiement à moins de 6 jours.
- MARK : correspond à une prise d’empreinte de la carte, dans le cas ou le
paiement est envoyé en banque à plus de 6 jours.
vads_capture_delay
Identique à la requête si il a été spécifié dans celle-ci, sinon retourne la valeur par
défaut configurée.
vads_card_brand
Type de carte utilisé pour le paiement, si disponible (vide sinon).
vads_card_number
Numéro de carte masqué, si disponible (vide sinon).
vads_change_rate
Indique le taux de change appliqué lors d’un paiement en devise étrangère.
vads_expiry_month
Identique à la requête si il a été spécifié dans celle-ci, sinon retourne le mois
d’expiration de la carte utilisée pour le paiement, si disponible (vide sinon).
vads_expiry_year
Identique à la requête si il a été spécifié dans celle-ci, sinon retourne l’année
d’expiration de la carte utilisée pour le paiement, si disponible (vide sinon).
vads_language
Retourne la valeur spécifiée dans le formulaire posté si le client n’a pas
changé la langue sur le page de paiement.
Retourne la langue sélectionnée par le client si celui-ci a changé de langue
sur la page de paiement en sélectionnant un autre drapeau. L’exploitation
de la valeur du champ vads_language peut vous permettre lors du retour
boutique de positionner la langue de votre site marchand en analysant la
valeur
signature
Descriptif de l’interface vers la page de paiement
©Lyra Network- 29/52
Paramètre permettant au site marchand de vérifier la validité de la requête
transmise par la plateforme de paiement (voir le chapitre suivant).
vads_validation_mode
Identique à la requête si il a été spécifié dans celle-ci, sinon retourne la valeur par
défaut configurée.
vads_warranty_result
Si l’autorisation a été réalisée avec succès, indique la garantie du paiement, liée
à 3D-Secure :
warranty_result Signification
YES Le paiement est garanti
NO Le paiement n’est pas garanti
UNKNOWN Suite à une erreur technique, le paiement ne peut pas être garanti
Non valorisé Garantie de paiement non applicable
vads_payment_certificate
Si l’autorisation a été réalisée avec succès, la plateforme de paiement délivre un
certificat de paiement. Pour toute question concernant un paiement réalisé sur la
plateforme, cette information devra être communiquée.
vads_result
Code retour général. Est l'une des valeurs suivantes :
- 00 : Paiement réalisé avec succès.
- 02 : Le commerçant doit contacter la banque du porteur.
- 05 : Paiement refusé.
- 17 : Annulation client.
- 30 : Erreur de format de la requête. A mettre en rapport avec la valorisation
du champ vads_extra_result.
- 96 : Erreur technique lors du paiement.
vads_extra_result
Code complémentaire de réponse. Sa signification dépend de la valeur
renseignée dans vads_result.
Lorsque vads_result vaut 30 (erreur de requête), alors vads_extra_result
contient le code numérique du champ qui comporte une erreur de
valorisation ou de format. Cette valeur peut être renseignée à 99 dans le
cas d’une erreur inconnue dans la requête.
Exemple : si vads_extra_result contient la valeur 09, cela signifie que le
montant spécifié dans vads_amount est incorrect (par exemple, si le
montant contient des décimales, car il n’aurait pas été converti
préalablement en centimes).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 30/52
Cette valeur 09 correspond à la valeur de la colonne « Code » dans le
tableau du chapitre 2.2.1. Se référer à ce tableau pour obtenir les autres
codes existants.
Lorsque vads_result vaut 05 (refusée) ou 00 (acceptée), alors vads_extra_result
contient le code numérique du résultat des contrôles risques (si l’option a été
souscrite).
extra_result Signification
Vide Pas de contrôle effectué
00 Tous les contrôles se sont déroulés avec succès
02 La carte a dépassé l’encours autorisé
03 La carte appartient à la liste grise du commerçant
04 Le pays d’émission de la carte appartient à la liste grise du commerçant ou le pays d’émission de la carte n’appartient pas à la liste blanche du commerçant.
05 L’adresse IP appartient à la liste grise du commerçant
07 La carte appartient à la liste grise BIN du commerçant
99 Problème technique rencontré par le serveur lors du traitement d’un des contrôles locaux
3.1.2 Signature
Pour les URL de retour passées en paramètre, la construction de la signature de
retour est similaire à celle effectuée lors de la requête. Se référer au chapitre 2.3
pour plus d’informations.
3.2 Réponse de serveur à serveur (réponse systématique)
Cette fonctionnalité permet de spécifier une URL sur l’outil de gestion de caisse que
la plateforme de paiement peut systématiquement appeler. Contrairement au cas
précédent, la requête HTTP ne passe pas par l'intermédiaire du navigateur du client,
mais est réalisée de serveur à serveur. Elle contient tous les paramètres de réponse
décrits au paragraphe 3.1, plus un paramètre supplémentaire nommé vads_hash.
Remarques importantes :
Cette URL est toujours appelée avec un formulaire HTTP POST, et ce quelque soit la
valeur du paramètre vads_return_mode.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 31/52
Pour paramétrer cette réponse, aller dans l’outil de gestion de caisse, menu
Paramétrage / boutique / Configuration, et renseigner la section « URL serveur » :
Attention :
L’utilisation de la réponse de serveur à serveur, via le paramétrage de l’URL
correspondante dans l’outil de gestion de caisse, est fortement conseillée.
Pour le commerçant, c’est le seul moyen de connaître de façon certaine le
dénouement de la transaction, et donc de gérer automatiquement ses stocks par
exemple.
ATTENTION : IL EST A LA CHARGE DU COMMERCANT DE SE PREMUNIR DE LA NON-RECEPTION ET DE LA RECEPTION MULTIPLE DE CETTE REPONSE.
En effet, tout incident de liaison entre la plateforme et le site marchand peut
avoir pour conséquence l’une ou l’autre de ces anomalies.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 32/52
4 COMMENT ACTIVER LA BOUTIQUE EN PRODUCTION ?
4.1 Récupération du « certificat » de test et de l’identifiant du site (site_ID)
Un « certificat » spécifique à la phase de test est nécessaire pour dialoguer avec le
serveur de test de la plateforme de paiement.
Il est mis à disposition de toutes les personnes habilitées à la consultation des
certificats dans l’outil de gestion de caisse à l’emplacement suivant : Paramétrage /
Boutique / Certificats.
L’identifiant de site (donnée ‘vads_site_id’), qui a été automatiquement attribué par
la plateforme de paiement à votre boutique lors de son inscription, est quant à lui
disponible dans l’outil de gestion de caisse à l’emplacement suivant : Paramétrage /
Boutique / Configuration générale, rubrique « identifiant de site ». Cette valeur est à
utiliser dans le calcul de la signature.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 33/52
4.2 Réalisation des paramétrages de la boutique
Elément à paramétrer
Où ? Comment ? A quoi cela
sert-il ?
Délai de présentation en banque
(valeur par défaut pour la boutique)
Outil de gestion de caisse Paramétrage / boutique / configuration
Cf. manuel utilisateur outil de gestion de caisse
Utilisé si le champ « vads_capture_delay » n’est pas renseigné dans la requête.
Mode de validation
(valeur par défaut pour la boutique)
Outil de gestion de caisse Paramétrage / boutique / configuration
Cf. manuel utilisateur outil de gestion de caisse
Utilisé si le champ « vads_validation_mode » n’est pas renseigné dans la requête.
URL serveur
à configurer en Production et en Test
Outil de gestion de caisse Paramétrage / boutique / configuration Cf. § 3.2
Cf. manuel utilisateur outil de gestion de caisse
Utilisé pour la réponse de serveur à serveur
URL de retour
A configurer en Production et en Test
Outil de gestion de caisse Paramétrage / boutique / configuration
Cf. manuel utilisateur outil de gestion de caisse
URL où est redirigée l’internaute dans le cas où la requête de paiement est mal formatée
Mode de réception des journaux -> Journal des opérations -> Journal des transactions -> Journal de rapprochement bancaire (réservé aux
commerçants ayant souscrit à cette option)
Outil de gestion de caisse Paramétrage / boutique / journaux
Modifier les critères comme souhaité, puis cliquer sur Sauvegarder. Cf. manuel utilisateur outil de gestion de caisse
Permet de définir la fréquence et les destinataires des journaux de reporting pré-formatés
Libellé de la boutique
Outil de gestion de caisse Paramétrage / boutique / configuration
Modifier le libellé de la boutique, puis cliquer sur Sauvegarder. Cf. manuel e-mail de confirmation de commande
Nom de la boutique tel qu’il apparaîtra sur les e-mail de confirmation de commande (commerçant et/ou client)
Descriptif de l’interface vers la page de paiement
©Lyra Network- 34/52
Elément à paramétrer
Où ? Comment ? A quoi cela sert-il ?
Logo et favicon de la boutique
Outil de gestion de caisse Paramétrage / boutique / personnalisation
Cf.. Manuel_utilisateur_personnalisation_logo_favicon
Après téléchargement, le logo apparaît sur les pages de paiement et dans le cas où la réception d’e-mail de commande (internaute et/ou commerçant) est activé, dans les entêtes de message.
E-mails de confirmation de commande (envoi commerçant )
Outil de gestion de caisse Paramétrage / boutique / configuration
Sélectionner la case à cocher, puis renseigner l’adresse e-mail. Cliquer enfin sur Sauvegarder. Cf. manuel e-mail de confirmation de commande
Permet au commerçant de recevoir un mail à chaque commande réalisée avec succès sur sa boutique.
E-mails de confirmation de commande (envoi client)
(réservé aux commerçants ayant souscrit à cette option)
-
Demander l’activation au chargé de clientèle. Cf. manuel e-mail de confirmation de commande
Permet aux clients de recevoir un mail à chaque commande réalisée sur la boutique.
Module d’aide à la décision
(réservé aux commerçants ayant souscrit à cette option)
Outil de gestion de caisse Paramétrage / boutique / contrôle risques
Demander l’activation au chargé de clientèle, puis effectuer le paramétrage tel que décrit dans le manuel module d’aide à la décision
Permet de paramétrer les différents contrôles du module anti-fraude.
4.3 Phase de test & Cartes à utiliser
Préalablement au passage en production de la boutique, il est nécessaire de réaliser
des tests pour s’assurer du bon dialogue entre le site marchand et la plateforme de
paiement.
Ces tests doivent impérativement être réalisés avant de demander le passage en
production.
Les demandes de paiement de test adressées via le formulaire HTTP POST doivent
contenir la donnée vads_ctx_mode valorisée à TEST. Elles doivent également utiliser
le certificat de test précédemment récupéré pour le calcul de la signature.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 35/52
En phase de test, le commerçant peut tester les configurations 3D-Secure ou non 3D-
Secure, quelle que soit sa configuration réelle
Différents cas de paiement peuvent être simulés en utilisant les numéros de carte de
test précisés ci-dessous ; Le choix de la date et du cryptogramme est libre (Ex : date
d’expiration décembre 2010 et CVV =123 ).
NB : Attention les paiements avec des numéros de cartes réelles en mode test
passeront en paiement refusé).
Numéro de carte Cas de test vérifié
Commerçant non enrôlé 3D-Secure 4970 1000 0000 0003 Paiement accepté (autorisation accordée)
Commerçant enrôlé 3D-Secure
4970 1000 0000 0000 Paiement accepté avec authentification internaute
4970 1000 0000 0001 Paiement accepté sans authentification internaute (Internaute non enrôlé 3D-Secure)
4970 1000 0000 0002 contacter l’émetteur de carte (Transaction à forcer). Authentification réalisée avec succès.
4970 1000 0000 0006
Problème technique lors du calcul de la garantie de paiement Le paiement est accepté, mais le calcul de la garantie de paiement est impossible (la garantie de paiement est restituée par la plateforme à UNKNOWN)
4970 1000 0000 0007 Problème technique lors de l’authentification porteur Le paiement est accepté, mais la transaction est non garantie (la garantie de paiement est restituée à NO)
4970 1000 0000 0097 Paiement refusé pour cause d’authentification 3D-Secure échouée (l’internaute n’est pas parvenu à s’authentifier)
4970 1000 0000 0099 Paiement refusé (autorisation refusée suite à erreur dans le cryptogramme visuel saisi)
4970 1000 0000 0098 Paiement refusé (autorisation refusée pour cause de plafond dépassé)
4970 1099 9999 9999 Paiement accepté (utilisation d’une carte étrangère)
Toutes les transactions réalisées en test sont consultables par les personnes habilitées
sur l’outil de gestion de caisse à l’adresse suivante :
https://paiement.systemepay.fr/vads-merchant/
Ces transactions sont disponibles en visualisation via le menu « Gestion
TEST/transactions de test » situé en haut à droite sur l’outil de gestion de caisse.
REMARQUE :
Dans la phase de test, après avoir renseigné dans l’outil de gestion de caisse l’URL
serveur en mode test, vérifiez que sans cliquer sur « retour à la boutique » (en
fermant votre navigateur par exemple) après paiement, le back office de votre site
est correctement renseigné sur l’état du paiement.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 36/52
4.4 Génération du certificat de production
Mode automatique
Suite à la réalisation des tests, vous pouvez générer le certificat de production
directement dans l’outil de gestion de caisse. (paramétrage/nom de la
boutique/onglet certificat) et cliquer sur le bouton générer le certificat.
Le bouton apparaît uniquement si vous avez testé la totalité des cartes de tests
(chacune seront alors taguées en vert) et si cette option a été activée sur votre
compte.
Un e-mail sera alors envoyé à l’interlocuteur administratif pour confirmer le passage
en production de la boutique.
Mode Manuel – Procès verbal de recette.
Si vous n’avez pas le bouton générer et que vous ne visualisez pas la liste des
numéros de carte de test comme ci-dessus, vous devez vous rapprocher de votre
service client pour passer en mode production.
0811 363 364 pour les clients banque populaire
0810 004 724 pour les clients Caisse d’épargne
(Numéro Azur – Coût d’un appel local depuis un poste fixe) les jours ouvrés du lundi
au vendredi de 09h00 à 18h00 (heure légale française).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 37/52
4.4.1 Génération du certificat de production et modification du champ "ctx_mode"
Il suffit de se rendre dans l’onglet « Certificats » ; accessible depuis le menu
« Paramétrage / Boutique » et de sélectionner la fonctionnalité « Générer le
certificat ».
Le certificat de production est accessible par toutes les personnes dûment habilitées
à cet effet. Pour des raisons de sécurité, ce certificat ne sera plus consultable dès
lors qu’une première transaction aura été réalisée sur la boutique.
A ce titre, nous vous demandons de prendre toutes les dispositions sécuritaires
appropriées quant à son utilisation et à sa conservation.
Passage en production :
La variable vads_ctx_mode doit quant-à-elle désormais être valorisée à
PRODUCTION dans votre formulaire.
La variable qui contient votre certificat doit être modifiée avec le certificat de
production.
5 ASSISTANCE TECHNIQUE
Pour tout problème d’accès à l’outil de gestion de caisse, il convient d’utiliser les
liens « compte bloqué » ou « mot de passe oublié » disponibles sur la page de
connexion de l’outil de gestion de caisse.
Pour toute question technique, vous pouvez nous contacter par téléphone au
0811 363 364 pour les clients banque populaire et au 0810 004 724 pour les clients
Caisse d’épargne (Numéro Azur – Coût d’un appel local depuis un poste fixe) les
jours ouvrés du lundi au vendredi de 09h00 à 18h00 (heure légale française).
Descriptif de l’interface vers la page de paiement
©Lyra Network- 38/52
6 Acronymes et glossaire
6.1 Acronymes
Acronyme Signification
3DS 3D-Secure
HTTP Hypertext Transfer Protocol
MPI Merchant Plug-in
PCI-DSS Payment Card Industry Data Security Standard
SHA Secure Hash Algorithm
URL Uniform Resource Locator
VAD Vente A Distance
6.2 Glossaire
Terme Signification
3D-Secure Protocole interbancaire permettant d’offrir un niveau de sécurité supplémentaire pour les transactions e-commerce réalisées on-line. Il consiste à demander à l’internaute, en plus de son numéro de carte bancaire et du cryptogramme visuel, une information indépendante de la carte et uniquement connue de lui. Cette authentification supplémentaire permet a priori de s’assurer que la personne qui est en train de réaliser la transaction est le véritable porteur de la carte bancaire.
Acquéreur Banque ou organisme ayant un contrat avec le commerçant pour la remise en banque de ses paiements.
Authentification Processus de vérification de l’identité du titulaire de la carte (basé sur le protocole 3D-Secure).
Autorisation Dans le cadre d’une transaction par carte de paiement, l’autorisation prend effet lorsqu’un commerçant reçoit la permission d’utiliser une carte de paiement pour une transaction particulière.
Boutique Enseigne commerciale d’un marchand
Canal de vente Modalité de commercialisation d’un bien ou service par un commerçant (exemple : e-commerce, Serveur vocal, téléphone, e-mail, etc.)
Client Titulaire d’une carte achetant un bien ou un service chez un commerçant
Commerçant Marchand vendant des biens ou services
Contrat commerçant Contrat entre le commerçant et un acquéreur, sur lequel les transactions de paiement sont remises en banque.
Contribution Module réalisant automatiquement l’interfaçage entre la plateforme de paiement et un logiciel de création de boutique en ligne open-source.
Contrôles locaux Contrôles internes effectués sur la plateforme de paiement, avant demande d’autorisation, pour lutter contre la fraude.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 39/52
Terme Signification
Cryptogramme visuel Le cryptogramme visuel de la carte correspond au code de 3 chiffres présent au verso des cartes CB, VISA ou MASTERCARD, à droite dans la zone de signature ; ou aux 4 chiffres présents au recto des cartes AMEX. Il permet d’apporter à la transaction un niveau de sécurité supplémentaire.
Demande d’autorisation Demande effectuée auprès de l’émetteur de la carte pour s’assurer de la validité de la carte du client
E-commerce Désigne la vente de biens et de services via internet
Emetteur Banque ou organisme ayant émis la carte du client
Empreinte Demande d’autorisation de montant inférieur à 2 euros effectuée auprès de l’émetteur pour s’assurer de la validité de la carte.
Enrôlement Inscription du commerçant ou de son client au service 3D-secure
Favicon Icône favori de la boutique apparaissant sur l’outil de gestion de caisse
Hachage Processus qui consiste à rendre des données illisibles en les convertissant en une empreinte numérique de longueur fixe via un algorithme de chiffrement (SHA-1)
http Protocole Internet ouvert pour le transfert ou la transmission d’informations sur le Web.
Identifiant de site Identifiant unique attribué par la plateforme de paiement à chaque boutique lors de son inscription
Internaute Acheteur sur la boutique du e-commerçant
Journal Reporting pré-formaté restitué au commerçant sous forme fichier
Marchand Cf. commerçant
Merchant Plug-in Module utilisé dans le traitement des authentifications 3D-secure. En standard, la plateforme de paiement inclut un merchant plug-in.
Outil de gestion de caisse Application internet mise à la disposition des commerçants pour paramétrer leur boutique et gérer leurs transactions
Paiement unitaire Paiement dont la totalité du montant est débité au porteur de carte en une seule fois
Paiement en plusieurs fois / paiement en n fois
Paiement débité en plusieurs échéances au porteur de carte (et crédités en plusieurs échéance au commerçant)
Porteur de carte Client du commerçant titulaire de la carte utilisée
PCI-DSS Norme sécuritaire développée dans le but de renforcer la sécurité des données des titulaires de cartes et de faciliter l'adoption de mesures de sécurité uniformes à l’échelle mondiale.
Plateforme de paiement Serveur de paiement sécurisé
Présentation en banque Transmission des paiements à l’acquéreur pour débiter le porteur et créditer le compte du commerçant.
Procès verbal de recette Document devant impérativement être renseigné et retourné pour permettre le passage en production de la boutique
Query string Partie de l’URL contenant les paramètres de retour exploitables par le commerçant. https//server/path/program?query_string
Remise en banque Cf Présentation en banque
SHA-1 Algorithme de chiffrement irréversible (Secure Hash Algorithm)
Signature Donnée permettant d’authentifier l’expéditeur d’un message
Site Cf. Boutique
Systempay Nom de la plateforme de paiement sécurisée
Type de carte Réseau d’émission de la carte
URL Adresse web
Validation Fait d’autoriser l’envoi en banque d’une transaction à la date de présentation demandée
Descriptif de l’interface vers la page de paiement
©Lyra Network- 40/52
Terme Signification
Validation automatique Présentation automatique des transactions en banque par la plateforme de paiement à la date de présentation demandée sans intervention complémentaire du commerçant.
Validation manuelle Le commerçant doit impérativement valider manuellement chaque paiement avec son outil de gestion de caisse ou via webservice pour qu’il soit remis en banque à la date de présentation demandée. Cette action ne peut être réalisée que jusqu’au jour de la date de présentation demandée.
Vente à distance Paiement initié depuis tout autre canal de vente que le e-commerce Il peut s’agir d’une saisie manuelle, d’un paiement initié via un Serveur Vocal Interactif, etc.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 41/52
7 ANNEXES
7.1 Exemples d’implémentation
7.1.1 Contrôle de la signature (Java)
L’algorithme SHA1 est disponible dans la plupart des langages utilisés dans le
développement d’applications Web. Voici un exemple de vérification de signature
en Java, dans un environnement JSP / Servlet, avec le framework Struts :
Tout d’abord, créons une classe utilitaire Sha, qui contiendra ce qui est nécessaire
au traitement de l’algorithme SHA1 :
import java.security.MessageDigest;
import java.security.SecureRandom;
public class Sha {
static public final String SEPARATOR = "+";
public static String encode(String src) {
try {
MessageDigest md;
md = MessageDigest.getInstance("SHA-1");
byte bytes[] = src.getBytes("iso-8859-1");
md.update(bytes, 0, bytes.length);
byte[] sha1hash = md.digest();
return convertToHex(sha1hash);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private static String convertToHex(byte[] sha1hash) {
StringBuilder builder = new StringBuilder();
for (int i = 0; i < sha1hash.length; i++) {
byte c = sha1hash[i];
addHex(builder, (c >> 4) & 0xf);
addHex(builder, c & 0xf);
}
return builder.toString();
}
private static void addHex(StringBuilder builder, int c) {
if (c < 10)
builder.append((char) (c + '0'));
else
builder.append((char) (c + 'a' - 10));
}
}
Descriptif de l’interface vers la page de paiement
©Lyra Network- 42/52
Ensuite, voici le traitement de vérification lui-même : @ActionMethod("return")
public ActionForward performCheck(ActionMapping actionMapping,
BasicForm form, HttpServletRequest request,
HttpServletResponse response) {
SortedSet<String> vadsFields = new TreeSet<String>();
Enumeration<String> paramNames = request.getParameterNames();
// Recupere et trie les noms des
// parametres vads_* par ordre alphabetique
while (paramNames.hasMoreElements()) {
String paramName = paramNames.nextElement();
if (paramName.startsWith("vads_")) {
vadsFields.add(paramName);
}
}
// Calcule la signature
String sep = Sha.SEPARATOR;
StringBuilder sb = new StringBuilder();
for (String vadsParamName : vadsFields) {
String vadsParamValue = request.getParameter(vadsParamName);
if (vadsParamValue != null) {
sb.append(vadsParamValue);
}
sb.append(sep);
}
sb.append(shaKey);
String c_sign = Sha.encode(sb.toString());
// Verifie la signature
if (c_sign.equals(request.getParameter("signature"))) {
return new ActionForward("/ok.jsp");
} else {
return new ActionForward("/fail.jsp");
}
}
Descriptif de l’interface vers la page de paiement
©Lyra Network- 43/52
7.1.2 Acquisition des données carte déléguée à la plateforme (PHP)
Cet exemple de code affiche un simple bouton « Payer », qui soumet un formulaire
tel que l’attend la plateforme.
L’acquisition des données carte est donc réalisée par la plateforme. <?php
$key = "votre certificat personnel, à récupérer dans le back-office";
// Initialisation des paramètres
$params = array(); // tableau des paramètres du formulaire
$params['vads_site_id'] = "votre identifiant boutique";
$montant_en_euro = 9.99;
$params['vads_amount'] = 100*$montant_en_euro; // en cents
$params['vads_currency'] = "978"; // norme ISO 4217
$params['vads_ctx_mode'] = "TEST";
$params['vads_page_action'] = "PAYMENT";
$params['vads_action_mode'] = "INTERACTIVE"; // saisie de carte réalisée par
la plateforme
$params['vads_payment_config']= "SINGLE";
$params['vads_version'] = "V2";
// Exemple de génération de trans_id basé sur l'horodatage
$ts = time();
$params['vads_trans_date'] = gmdate("YmdHis", $ts);
$params['vads_trans_id'] = gmdate("His", $ts);
// Génération de la signature
ksort($params); // tri des paramètres par ordre alphabétique
$contenu_signature = "";
foreach ($params as $nom => $valeur)
{
$contenu_signature .= $valeur."+";
}
$contenu_signature .= $key; // On ajoute le certificat à la fin
$params['signature'] = sha1($contenu_signature);
?>
<html>
<head>
<title>Redirection vers la plateforme de paiement</title>
</head>
<body>
<form method="POST" action="https://paiement.systempay.fr/vads-payment/">
<?php
foreach($params as $nom => $valeur)
{
echo '<input type="hidden" name="' . $nom . '" value="' . $valeur . '" />';
}
?>
<input type="submit" name="payer" value="Payer" />
</form>
</body>
</html>
Descriptif de l’interface vers la page de paiement
©Lyra Network- 44/52
7.1.3 Acquisition des données carte par le commerçant (PHP)
Cet exemple implémente un formulaire de saisie de carte minimaliste, avec la
génération du formulaire à destination de la plateforme.
Tout d’abord, voici le formulaire de saisie proprement dit :
<html>
<head>
<title>Saisissez les informations de votre carte</title>
</head>
<body>
<form action="3DS_form_paiement.php" method="POST">
<fieldset>
<legend>Formulaire de paiement par CB</legend>
<label for="vads_card_number">Numéro de carte</label><br/>
<input type="text" name="vads_card_number" size="19"/>
<br/>
<label>Date d'expiration</label><br/>
<input type="text" name="vads_expiry_month" size="2"/> / <input
type="text" name="vads_expiry_year" size="4"/>
<br/>
<label for="vads_cvv">Cryptogramme</label><br/>
<input type="text" name="vads_cvv" size="3"/>
<br/>
<input type="submit" value="Payer"/>
</fieldset>
</form>
</body>
</html>
Ce formulaire poste les informations de carte vers une page nommée
« 3DS_form_paiement.php » qui va être chargée de générer le formulaire à
destination de la plateforme.
En voici le code :
<?php
$key = "votre certificat personnel, à récupérer dans le back-office";
// Initialisation des paramètres
$params = array(); // tableau des paramètres du formulaire
$params['vads_site_id'] = "votre identifiant boutique";
$montant_en_euro = 9.99;
$params['vads_amount'] = 100*$montant_en_euro; // en cents
$params['vads_currency'] = "978"; // norme ISO 4217
$params['vads_ctx_mode'] = "TEST";
$params['vads_page_action']= "PAYMENT";
$params['vads_action_mode']= "SILENT"; // saisie de carte réalisée par le site
marchand
$params['vads_payment_config']= "SINGLE";
$params['vads_version'] = "V2";
// Exemple de génération de trans_id basé sur l'horodatage
$ts = time();
$params['vads_trans_date'] = gmdate("YmdHis", $ts);
$params['vads_trans_id'] = gmdate("His", $ts);
Descriptif de l’interface vers la page de paiement
©Lyra Network- 45/52
// Paramètres liés à la carte bancaire du client
$champs_carte =
array('vads_card_number','vads_expiry_month','vads_expiry_year','vads_cvv');
foreach ($champs_carte as $champ_carte)
{
$params[$champ_carte] = $_POST[$champ_carte];
}
$params['vads_payment_cards'] = "CB"; // préciser le type de carte qui a été
utilisée
// Génération de la signature
ksort($params); // tri des paramètres par ordre alphabétique
$contenu_signature = "";
foreach ($params as $nom => $valeur)
{
$contenu_signature .= $valeur."+";
}
$contenu_signature .= $key; // On ajoute le certificat à la fin
$params['signature'] = sha1($contenu_signature);
?>
<html>
<head>
<title>Redirection vers la plateforme de paiement</title>
</head>
<!-- On fait soumettre le formulaire immédiatement par javascript -->
<body onload="document.forms[0].submit();">
<form method="POST" action="https://paiement.systempay.fr/vads-payment/">
<?php
foreach($params as $nom => $valeur)
{
echo '<input type="hidden" name="' . $nom . '" value="' . $valeur . '" />';
}
?>
</form>
</body>
</html>
Ici, la redirection est effectuée immédiatement en javascript.
7.1.4 Contrôle des données reçues de la plateforme (PHP)
Cet exemple montre comment procéder pour vérifier ce qui est transmis par la
plateforme en retour, que ce soit par l’URL serveur, ou par redirection suite à un
« retour boutique » effectué à l’initiative du client :
<?php
$key = "votre certificat personnel, à récupérer dans le back-office";
$contenu_signature = "";
$params = $_POST;
ksort($params);
foreach ($params as $nom => $valeur)
{
if(substr($nom,0,5) == 'vads_')
{
// C'est un champ utilisé pour calculer la signature
$contenu_signature .= $valeur."+";
}
}
$contenu_signature .= $key; // On ajoute le certificat (dernier paramètre)
$signature_calculee = sha1($contenu_signature);
Descriptif de l’interface vers la page de paiement
©Lyra Network- 46/52
if(isset($_POST['signature']) && $signature_calculee == $_POST['signature'])
{
// Requête authentifiée
// Attention cependant à bien vérifier les paramètres passés
// Notamment le vads_site_id et le vads_ctx_mode
if($_POST['vads_result'] == "00")
{
// Paiement ok
}
else
{
// Paiement refusé ou referral
}
}
else
{
// Signature invalide – ne pas prendre en compte ce formulaire
}
?>
Descriptif de l’interface vers la page de paiement
©Lyra Network- 47/52
7.2 Exemples de pages de la plateforme de paiement
Ces pages sont spécifiques aux commerçants délégant l’acquisition des données
carte à la plateforme de paiement.
Les textes et visuels ci-dessous ne sont pas contractuels.
Sélection du type de carte :
Descriptif de l’interface vers la page de paiement
©Lyra Network- 48/52
Saisie des informations de la carte :
Descriptif de l’interface vers la page de paiement
©Lyra Network- 49/52
Compte-rendu d'une transaction réussie :
Message d'échec de transaction :
Descriptif de l’interface vers la page de paiement
©Lyra Network- 50/52
7.3 Personnalisation des pages de paiement à l’aide du paramètre
« vads_theme_config ».
7.3.1 Principe de fonctionnement
Dans le formulaire envoyé à l’URL de paiement, il est possible de spécifier un
paramètre nommé vads_theme_config afin de personnaliser l’affichage des pages
de paiement.
Ce paramètre contient une liste de mots-clés (codes) associés à des éléments des
pages de paiement (libellés, images), auxquels on associe une valeur. Le formalisme
du paramètre est le suivant :
Code1=Valeur1 ;Code2=Valeur2
Les éléments personnalisables sont les suivants : Code Description
SUCCESS_FOOTER_MSG_RETURN Libellé remplaçant « Retour à la boutique » lors d’un paiement réalisé avec succès.
CANCEL_FOOTER_MSG_RETURN Libellé remplaçant « Annuler et retourner à la boutique » pendant les phases de sélection puis de saisie de carte, et en cas d’échec du paiement.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 51/52
7.3.2 Exemple d’utilisation
En renseignant vads_theme_config avec la valeur suivante :
SUCCESS_FOOTER_MSG_RETURN=Retour au
site;CANCEL_FOOTER_MSG_RETURN=Annuler et retourner au site
La page de saisie de carte bancaire devient alors :
Le libellé « Annuler et retourner à la boutique » a été remplacé par la valeur
spécifiée via le code CANCEL_FOOTER_MSG_RETURN.
Descriptif de l’interface vers la page de paiement
©Lyra Network- 52/52
Dans le cas d’un paiement réussi, la page détaillant le paiement devient alors :
Le libellé « Retourner à la boutique » a été remplacé par la valeur spécifiée via le
code SUCCESS_FOOTER_MSG_RETURN.