FAQ

Comment peut-on intégrer une application à Esup-Pay ?

Question détaillée :

Nous avons une application que nous souhaiterions intégrer à Esup-Pay : 

• nous souhaitons que les montants soient données par l'application, que le nom/prénom soient également présaisis.
• nous souhaitons que le paiement effectué, Esup-Pay restransmette cette information à notre application (api, callback, ...)
• etc.

Réponse : 

L'objectif d'Esup-Pay n'est pas de proposer une solution intégrée de paiement en ligne vis à vis des applications du SI ... en tout cas pas actuellement, pas en l'état.

Aussi, dans un cas d'usage comme décrit ci-dessus, il n'y a pas d'intérêt à utiliser esup-pay, autant intégrer directement la solution de paiement finale escomptée, comme peut l'être paybox.

Actuellement, Esup-Pay est une alternative générique pour la mise en place d'un paiement en ligne rapide et simple ... mais non intégrée avec les applications du SI, c'est à dire sans interactions avec elles ; pour être tout à fait juste, une exception existe pour sciencesconf.org cependant dans Esup-Pay ...

Esup-pay peut par contre éventuellement donner du code (une base, un exemple ... ou ne serait-ce que des idées) pour intégrer paybox à une application ...
https://github.com/EsupPortail/esup-pay/blob/master/src/main/java/org/esupportail/pay/services/PayBoxService.java

Groupe administrateurs EsupPay

J'ai installé l'application pour tester, je me retrouve après connexion avec ce message :

Accès restreint
Vous n'êtes pas autorisé à consulter cette page.

Une fois installée, et la base de données encore vierge de tout "événement" et "montant" de paiement, c'est à un administrateur EsupPay de se connecter.

Configuration des administrateurs via groupe ldap (posixGroup ou groupOfNames)

Dans EsupPay les administrateurs sont définis/identifiés par un groupe LDAP, groupe configuré dans le fichier esup-pay.properties.

Ce groupe peut être soit un groupe de type (objeclass) posixGroup ou de type groupOfNames (plus courant, et correspondant aux recommandations supann).

Pour un groupe groupOfNames :

• ldap.groupSearchFilter doit être normalement valué à 'member={0}'

• ldap.groupAdmin doit être valué par le nom du groupe (le cn) des administrateur

Pour un groupe posixGroup :

• ldap.groupSearchFilter doit être normalement valué à 'memberUid={1}'

• ldap.groupAdmin doit être valué par le nom du groupe (le cn) des administrateurs

Configuration des administrateurs via un simple filtre ldap

Depuis la version 1.1.0, EsupPay permet aussi de configurer les adminstrateurs via un filtre ldap : via la propriété ldap.groupAdminFilter.

Exemple :

ldap.groupAdminFilter=supannEntiteAffectation=DSI

Comptes Paybox

Peut-on utiliser plusieurs compte PayBox dans Esup-Pay ? L'agent comptable souhaite en effet utiliser un compte PayBox différent pour chaque service ou "type" d'évènements.

Pour pouvoir utiliser plusieurs comptes Paybox, il faut modifier le fichier XML Spring de configuration suivant :
src/main/resources/META-INF/spring/applicationContextPaybox.xml

Dans ce fichier, on peut ajouter autant d'entry que l'on a de comptes paybox à configurer.
Par défaut, esup-pay est livré avec 2 comptes paybox : un correspondant au compte paybox de test (compte_paybox_test) et un autre qui correspond aux paramètres paybox renseignés dans le fichier esup-pay.properties (compte_paybox_prod).
Ce fichier esup-pay.properties n'étant qu'une facilité permettant aux exploitants de configurer leur esup-pay sans rentrer dans ce fichier XML de configuration avancée.

Dans src/main/resources/META-INF/spring/applicationContextPaybox.xml, les noms des clefs de chaque "entry" seront proposés au service comptable lors de la création/modification d'un événement dans une liste déroulante ; il faudra qu'il en choisisse un.
Ces noms seront également utilisés comme identifiant dans la base de données pour retrouver les configurations paybox liées à un formulaire de paiement en ligne.

Dans les faits donc, la configuration de nouveaux comptes paybox revient à copier/coller tout un bloc correspondant à l'entry compte_paybox_prod (par exemple) et y modifier "en dur" les paramètres paybox liés au compte (ainsi que le nom de la key donc).

Peut-on fixer un montant maximum sur un évènement EsupPay

A partir de la version 1.1.0, Esup-Pay permet de fixer un montant maximum par évènement (répercuté sur les montants, fixes ou libres), montant qui est donné par défaut à 1500€ :

• ce montant donné par défaut est également paramétrable, il est donné dans le fichier de configuration esup-pay.properties : esup-pay.defaultDbleMontantMax=1500
• 1500 € correspond au montant à partir duquel le droit français impose des contraintes supplémentaires sur le paiement CB (signature, ...).

Peut-on ajouter des paramètres Paybox avancés/supplémentaires pour modifier le comportement du paiement ?

Paybox supporte en effet des paramètres avancés pour modifier le comportement du paiement : http://www1.paybox.com/espace-integrateur-documentation/dictionnaire-des-donnees/paybox-system/

Ainsi

• sur un compte paybox où le 3D Secure est actif, le paramètre PBX_3DS=N permet de désactiver pour la transaction la fonctionnalité 3DS ; utile pou les petits montants et économiser le surcout de cette fonctionnalité 3D Secure.
• PBX_DIFF=05 permettant de différer la transaction bancaire de 5 j
• etc.

Depuis la version 1.1.0, Esup-Pay permet à l'administrateur d'Esup-Pay d'ajouter autant de paramètres paybox qu'il le souhaite pour un évènement Esup-Pay (paramètres supplémentaires paybox par défaut) et sur chaque montant Esup-Pay.

Ce paramètre, donné au travers de l'interface web toujours, est attendu sous la forme : PBX_DIFF=5&PBX_LANGUE=ITA&PBX_3DS=N

Quel moyen de paiement Paybox est affiché à l'utilisateur ?

Par défaut, et avec un compte de test paybox, l'utilisateur est redirigé sur Paybox avec tous les moyens de paiement offerts et disponibles par Paybox sur le compte de test.

Si vous souscrivez un compte Paybox en ne souscrivant/activant aucun autre moyen de paiement que le paiement par carte bancaire, paybox affichera directement la page proposant à l'utilisateur de rentrer ses coordonnées de carte bancaire.
Cf le manuel d'intégration paybox page 12: http://www1.paybox.com/wp-content/uploads/2017/08/ManuelIntegrationVerifone_PayboxSystem_V8.0_FR.pdf

Comme l'indique également ce même manuel page 18, si vous avez plusieurs moyens de paiement actifs sur votre compte paybox vous pouvez forcer l'usage d'un moyen de paiement unique et direct en ajoutant un paramètre Paybox avancé pour un montant donné.

Cf la question ci-dessus "Peut-on ajouter des paramètres Paybox avancés/supplémentaires pour modifier le comportement du paiement ?" vous pouvez ajouter par exemple comme "Paramètres Paybox optionnels supplémentaires" la valeur "PBX_TYPEPAIEMENT=CARTE&PBX_TYPECARTE=CB" pour forcer le moyen de paiement en carte bancaire : pour le(s) montant(s) poussé(s) avec ces paramètres, l'utilisateur sera ainsi redirigé directement sur la page proposant à l'utilisateur de rentrer ses coordonnées de carte bancaire. 

A quoi sert le 'Préfixe OTP' demandé lors de l'édition d'un évènement ?

Le 'préfixe OTP' est une chaine de caractère qui va s'ajouter à toutes les références de tous les paiements paybox effectués sur cet évènement.

C'est ce qui peut permettre à l'agence comptable de ventiler au mieux les paiements liés à différents évènements en n'utilisant qu'un seul et unique compte Paybox !

Lors de l'édition d'un montant, esup-pay propose des paramètres avancés, est-il indispensable de les utiliser ?

Les paramètres avancés sont optionnels, dans la majorité des cas d'usage ils ne servent pas. Ils permettent d'activer certaines options simplement : intégration à scienceconf, paramètres spécifiques paybox ...

Comment intégrer esup-pay dans sciencesconf ?

Côté Esup-Pay, dans un 'évènement', vous devez créer un montant pour lequel vous allez cocher (dans paramètres avancés) la case 'sciencesconf' à 'oui'. Le montant lui même (en euros) ne pourra alors plus être saisi (case grisée) puisque c'est sciencsconf qui se charge de donner les montants à esup-pay.

Côté scienceconf, dans le paramétrage du paiement (en ligne), il faut donner l'url du montant esup-pay simplement (on laisse les paramètres paybox à vide).

N'hésitez pas à tester cette intégration en utilisant le serveur de démonstration de sciencesconf.org : https://www.sciencesconf.org/demo

A quoi sert le paramètre avancé 'Add Prefix' ?

Le paramètre avancé 'Add Prefix' proposé dans l'édition d'un montant permet d'ajouter au 'préfixe OTP' positionné sur l'évènement une valeur rentrée par l'utilisateur lui-même : cette valeur pouvant donc correspondre au champ1 ou au champ2.

Dans le cadre de la mise en place d'un formulaire générique de paiement de factures par exemple, on peut proposer :

• un montant libre
• dont l'intitulé du champ1 serait 'Nom ou Raison social'
• dont l'intitulé du champ2 serait 'Numéro de facture (9 caractères)'
• et avec comme 'Add Prefix' field2

Avec une telle configuration, on trouvera dans les références paybox, juste après le préfixe otp, le numéro de facture renseigné par l'utilisateur-payeur lors du paiement ; ce qui permettra de faciliter la gestion/validation/ventilation des paiements depuis les exports csv/excel paybox.

Esup-Pay propose t'il un mécanisme d'archivage des logs ?

Depuis la version 1.1.0, il est possible d'activer dans Esup-Pay l'archivage ou plutôt l'anonymisation des logs. 

Dans esup-pay.properties, pour anonymiser les logs au bout de 5 ans on configurera les paramètres ainsi :

archive.enabled=true
archive.oldDays.emailFieldsMapReference=15
archive.oldDays.transactionsLogs=1825

archive.enabled=true permet d'activer effectivement cette fonctionnalité : un cron interne à l'application lance toutes les heures une procédure d'archivage/anonymisation des log fonction de la date de création du log.
archive.oldDays.transactionsLogs=1825 correspond à anonymiser les logs vieux de 1825 jours (5 ans) et plus (à noter que le droit français demande à conserver les logs de paiement durant 5 ans).

archive.oldDays.emailFieldsMapReference=15 quant à lui permet simplement de purger la table email_fields_map_reference qui est une table temporaire utilisée lors du paiement et dont les informations doivent normalement être utilisées et requises sur un interval de temps court (entre moment où l'utilisateur quitte l'application esup-pay  pour aller sur le formulaire de paiement et le moment où paybox envoie l'information que le paiement s'est effectivement bien déroulé).

Le paiement sur Paybox a été effectué mais la transaction n'apparait pas dans la liste des Transactions sur l'interface.

Lorsque le paiement est effectué sur Paybox, Paybox tente d'appeler esup-pay sur son url de callback. C'est grâce à cet appel qu'esup-pay enregistre la transaction effectuée et envoie également éventuellement un mail à un gestionnaire.

Ainsi sur votre serveur web, dans ses logs d'accès, vous devez trouver des appels des serveurs paybox qui font des GET sur une url en /payboxcallback

Cette requête est prise en compte par esup-pay, mais dans un tout premier temps, une vérification (par spring-security) sur les IP est réalisée : en effet, l'idée est de n'autoriser que les serveurs paybox à appeler cette url de callback /payboxcallback
Ainsi le fichier security.properties liste l'ensemble des serveurs paybox.
Si un client appelle le /payboxcallback sans faire partie de ce listing d'IP, alors l'application renvoie un 403 (Forbidden) en réponse HTTP au lieu d'un 200 - on peut retrouver ces codes dans les fichiers logs d'accès à votre serveur web.

Si un serveur paybox de production appelle cette url et que esup-pay ne retourne pas un code HTTP 200, paybox enverra un mail de warning au mail de contact paybox de l'établissement.

Un problème courant lors de la mise en oeuvre de esup-pay est que l'application n'a pas connaissance de l'IP des clients véritablement et donc des serveurs paybox, mais de l'IP d'un éventuel proxy qui se situe entre esup-pay et les clients.

Celà peut être le cas si vous mettez par exemple un Apache devant un Tomcat, le Apache jouant alors le rôle de Proxy. Si vous utilisez AJP pour le ProxyPass entre Apache et Tomcat, l'IP du client est cependant préservé et présenté à Tomcat et donc à l'application esup-pay (et non pas l'IP du proxy, cad de Apache).

Installation d'esup-pay derrière un proxy

 Cf la question ci-avant, dans sa configuration par défaut esup-pay se charge de vérifier que le client qui appelle l'url de callback d'esup-pay dédiée à paybox a bien une IP qui correspond au listing des IPs publiques de paybox (liste d'IPs fournie officiellement dans la document Paybox : http://www1.paybox.com/espace-integrateur-documentation/la-solution-paybox-system/urls-dappels-et-adresses-ip/ ).

Le mieux est donc de faire en sorte qu'esup-pay puisse avoir connaissance de l'IP du client.

Mais si par le biais d'un mécanisme type proxy vous ne pouvez pas procéder à une telle configuration, alors vous pouvez modifier simplement le fichier security.propeties pour y mettre l'IP de votre proxy ... ou encore pour mettre simplement : 

payboxIpRestriction=permitAll

Celà fait, vous pouvez faire cette vérification d'IPs en amont  d'esup-pay si vous le souhaitez, dans la configuration de votre proxy donc par exemple.

Sachez également que cette vérification par IP n'est pas la seule vérification faite par esup-pay : comme préconisé dans la documentation paybox, esup-pay vérifie également la signature de paybox fournie dans l'appel callback de paybox : ainsi rien que par la signature, esup-pay peut s'assurer que l'appel provient bien de paybox ; sécuriser aussi par le biais du contrôle IP (et donc par un 2 ème facteur, en plus de la vérification de la signature) renforce cette sécurité.

Quels sont les pré-requis à l'installation d'Esup-Pay ?

Esup-Pay est une "petite" application web java. Elle ne nécessite que très peu de ressources système. 

Sur une VM dédiée, 1GB de RAM, 1 CPU et 10GB de disque suffisent amplement.

Comme pour la plupart des applications ESUP, vous pouvez installer cette application java/servlet dans un tomcat, lui-même frontalisé par un apache qui vous permettra d'opérer :

• le ssl (https)
• la compression html, css, js ..
• le paramétrage éventuel du cache des fichiers statiques js,css ...
  
  

<LocationMatch /resources>
   Header set Cache-Control max-age=3600
</LocationMatch>

ExpiresActive On
ExpiresByType text/css "access plus 2 hours"
ExpiresByType text/javascript "access plus 2 hours"
ExpiresByType application/javascript "modification plus 2 hours"
ExpiresByType image/gif "access plus 2 hours"
ExpiresByType image/png "access plus 2 hours"
ExpiresByType image/jpg "access plus 2 hours"
ExpiresByType image/jpeg "access plus 2 hours"
ExpiresByType application/x-shockwave-flash "access plus 2 hours"
ExpiresByType image/x-icon  "access plus 2 hours"


CacheRoot /var/cache/httpd/paybox
CacheDirLevels 2
CacheDirLength 1
CacheEnable disk /resources

AddOutputFilterByType DEFLATE text/plain text/html text/css text/javascript application/x-javascript application/javascript application/json image/svg+xml

ProxyPass / ajp://localhost:8009/ retry=1

pg_dump -f /opt/backup/esuppay-$(date +%w).dump esuppay

Résoudre l'erreur "Problème d'identification commerçant"

L'erreur type "Problème d'identification commerçant Accès refusé" peut survenir au moment où l'utilisateur arrive sur l'interface paybox après avoir cliqué sur le bouton de paiement proposé par esup-pay pour effectuer véritablement le paiement.

Cette erreur signifie que les paramètres paybox envoyés au travers de ce formulaire généré par esup-pay ne permettent pas à paybox de vous identifier correctement : champ manquant, hash ne correspondant pas aux champs ...

Pour connaitre l'ensemble des champs envoyés à paybox (dont le hmac calculé), vous pouvez (en jouant vous même le formulaire de paiement proposé par esup-pay) regarder le source du formulaire html généré par esup-pay (bouton de paiement qui renvoie sur paybox) pour vérfier que l'ensemble des champs vous semblent corrects.

<form action="https://tpeweb.paybox.com/cgi/MYchoix_pagepaiement.cgi" method="POST">
  <input value="https://esup-pay.univ-ville.fr" name="PBX_ANNULE" type="hidden">
  <input value="AZ-Bonamy@@justin.test@univ-ville.fr@@17000-2020-08-25-11-54-58-55" name="PBX_CMD" type="hidden">
  <input value="978" name="PBX_DEVISE" type="hidden">
  <input value="https://esup-pay.univ-ville.fr" name="PBX_EFFECTUE" type="hidden">
  <input value="SHA512" name="PBX_HASH" type="hidden">
  <input value="123456789" name="PBX_IDENTIFIANT" type="hidden">
  <input value="justin.test@univ-ville.fr" name="PBX_PORTEUR" type="hidden">
  <input value="01" name="PBX_RANG" type="hidden">
  <input value="https://esup-pay.univ-ville.fr" name="PBX_REFUSE" type="hidden">
  <input value="https://esup-pay.univ-ville.fr/payboxcallback" name="PBX_REPONDRE_A" type="hidden">
  <input value="montant:M;reference:R;auto:A;erreur:E;idtrans:S;signature:K" name="PBX_RETOUR" type="hidden">
  <input value="1234567" name="PBX_SITE" type="hidden"><input value="2020-08-25T09:54Z" name="PBX_TIME" type="hidden">
  <input value="17000" name="PBX_TOTAL" type="hidden">
  <input value="971CEB498C5380BB23AF0382E0B9C7635A68FCFDA34C92DDF51B3B7115D7C313720C6F133BB8B70CC413865AC9FF7349DEA17370A2D8CEFD2080DA13D777ACF0" 
         name="PBX_HMAC" type="hidden"><input class="btn btn-success btn-lg" value="170.0 Euros" type="submit">
</form>

Cela peut venir d'une erreur de saisie des identifiants paybox dans vos fichiers de configuration notamment. Aussi, il faut bien vérifier l'ensemble de ces paramètres : identifiant, rang, clef hmac ...

Le support de Paybox/Verifone peut aider à déterminer quel paramètre pose problème.

Notez enfin que certains établissements ont eu cette erreur suite à une saisie du numéro de rang sur 3 chiffres au lieu de 2. A priori le numéro de rang (généralement 1) était donné sur 2 chiffres (01) jusqu'il y a peu, il l'est maintenant que 3 chiffres, soit 001.

Dans le doute, n'hésitez pas à tester les 2 formats. Côté des établissements qui font fonctionner esup-pay, on note que paybox/verifone fournit donc maintenant des numéros sur 3 chiffres (001) mais que l'on rentre en paramètre le format en 2 chiffres (01) et que cela fonctionne.

Est-il possible d'intégrer Payfip/Tipi et Esup-Pay ?

La direction générale des Finances publiques (DGFiP) a mis en place un service de paiement en ligne nommé PayFip.

PayFip propose de payer en ligne les factures par carte bancaire (en intégrant en fait payline, un concurrent de paybox)  mais aussi par prélèvement bancaire.

Les établissements de l'ESR qui disposent d'Esup-Pay ont ainsi pu se poser la question de l'intégration voir du remplacement d'Esup-Pay par PayFip ; voir notamment le fil de discussions suivant :
https://listes.esup-portail.org/sympa/arc/esup-utilisateurs/2019-03/msg00004.html

Cependant, et confère  
https://www.collectivites-locales.gouv.fr/files/files/finances_locales/moy_paiement/PayFiP/guides_payfip_2020/guide_de_mise_en_oeuvre_payfip_regie_web_service_v19_juin2020.pdf

"""
Pour adhérer au dispositif, la régie de la collectivité ou de l’établissement doit respecter un certain nombre de critères :
- Disposer d’une régie, (les établissements publics locaux et nationaux de l’Etat sont exclus de cette offre) ;
...
"""
Actuellement, Payfip n'est donc pas ouvert pour les établissements publics de l'ESR.