Notice 4 Informations techniques Monelib

Transcription

1 Notice 4 Informations techniques Monelib 18 Octobre

2 Avertissement : Ce document s adresse aux personnes souhaitant faire une utilisation avancée du système de paiement Monelib. Sa compréhension nécessite d avoir des bases techniques avancées concernant principalement les technologies du web, et plus généralement de l internet. Les différents exemples de script «server side» pouvant être proposés sont fournis en PHP, version 5. Si un autre langage est utilisé sur la plateforme amenée à effectuer une utilisation avancée du système Monelib, il est à la charge du lecteur de convertir les scripts d exemples dans un autre langage. Enfin, le lecteur est réputé connaître le fonctionnement et la manière de configurer le système Monelib de façon classique, ce document ne revenant pas sur ces notions. 2

3 18 Octobre 2011 Ajout des informations concernant la monnaie virtuelle (micro paiement) 21 Juillet 2011 Ajout de l annexe A avec code PHP pour validation de code. 27 Avril 2011 Ajout des numéros de groupes pour France DOM Audio, Internet+ et MPME (passerelle) 7 Février 2011 Ajout de la fonctionnalité «cancelsubscription» au niveau de la passerelle, permettant l arrêt d un abonnement automatique MultiShot 19 Avril 2010 L url de notification, dans le cas d un achat EZSHot ou MultiShot ou lors d un renouvellement MultiShot est appelée avec le paramètre «monelib_trans» correspondant à l identifiant de la transaction 19 Novembre 2009 L url de notification est maintenant également appelée en cas de rejet d une transaction par carte. 12 Novembre 2009 Ajout de la fonctionnalité «publicstats» permettant de demander, via la passerelle, le CA d un jour donné, pour son propre compte ou pour un autre compte Monelib grâce au mot de passe public pouvant être défini dans l Espace Client. Ajout du paramètre «ext_frm_tpldiz» du script du bouton d achat MultiShot et EZShot. Ajout de la possibilité de valider pour un accès un nombre de codes différents que celui configuré sur des paliers également différents de ceux initialement configurés. 22 Octobre 2009 Ajout de la fonctionnalité «getpinlist» permettant d obtenir, via la passerelle, la liste des codes d accès ayants été utilisés sur les points de ventes. 19 Octobre 2009 Ajout de la fonctionnalité permettant de demander, via la passerelle, les informations concernant un palier précis. 15 Avril 2009 Ajout du paramètre «ext_frm_verbose» lors de la vérification d un code d accès avec le paramètre «ext_frm_online» à la valeur 1 25 Mars 2009 Ajout de la possibilité d indiquer un nom de «plan de reversement affilié» dans le champ «affiliateamount» du formulaire de micropaiement 23 Mars 2009 Ajout des champs «title» et «site_title» dans les formulaires micro paiement et achat EZShot 3

4 et MultiShot 26 Décembre 2008 Ajout de la balise «price» dans la réponse à la commande «accessinfo» de la passerelle. 23 Décembre 2008 Ajout des balises «pos», «name», «numpincode» dans la réponse à la commande «accessinfo» de la passerelle. 4

5 Sommaire 1 Scripts Appel de l Url de notification Ajout de paramètres supplémentaires au script d achat et d accès Sécurisation des pages à accès restreint et validation des codes par requête http Accès à la passerelle Annexe A Validation et grillage de code par script PHP

6 6

7 1 Scripts a Script d accès pour le micro paiement Le script d accès fourni par Monelib consiste principalement en un formulaire HTML qui est transmis à la plateforme Monelib lors de sa validation. Les champs contenus par défaut dans ce formulaire sont les suivants : ext_frm_pos : identifiant du point de vente ext_frm_zos : identifiant de la zone de vente ext_frm_coden : code d accès saisi, avec n compris entre 0 (inclus) et 5 (exclu) ext_frm_login : identifiant (optionnel) saisi par l utilisateur L envoi du formulaire s effectue en méthode «POST» vers le script «/accessscript/check.php» de la plateforme Monelib. L installation du formulaire sur la page HTML du marchand s effectue en insérant une ligne du type <script type="text/javascript" src=" 45" ></script> fournie sur le site Monelib. Le script ainsi inséré a un format de 485 sur 300 pixels. b Script d achat carte bancaire (EZShot et MultiShot) Ces scripts consistent en des formulaires HTML qui sont transmis à la plateforme Monelib lors de leur validation. Le champ contenu par défaut dans ces formulaires est le suivant : ext_frm_pos : identifiant du point de vente L envoi du formulaire s effectue en méthode «POST» vers le script «/accessscript/ezpurchase.php» de la plateforme Monelib. L installation des ces formulaires sur la page HTML du marchand s effectue en copiant collant le script fourni sur le site Monelib. c Script d accès carte bancaire (EZShot et MultiShot) 7

8 Ces scripts consistent en des formulaires HTML qui sont transmis à la plateforme Monelib lors de leur validation. Les champs contenus par défaut dans ces formulaires sont les suivants : ext_frm_pos : identifiant du point de vente ext_frm_zos : identifiant de la zone de vente ext_frm_code0 : code d accès saisi L envoi du formulaire s effectue en méthode «POST» vers le script «/accessscript/check.php» de la plateforme Monelib. L installation des ces formulaires sur la page HTML du marchand s effectue en copiant collant le script fourni sur le site Monelib. d Zone d achat pour la monnaie virtuelle La zone d achat de monnaie virtuelle est matérialisée par une «iframe» de taille 485 sur 300 pixels. Celle ci s installe sur la page HTML du marchand en insérant un code du type <iframe width="485" height="300" style="border:1px solid black" src=" 35&ext_frm_userid=REMPLACER_LA_VALEUR_ICI"> </iframe> fourni sur le site Monelib 8

9 2 Validation des scripts d accès et traitement a Micro paiement Lors de la soumission de ce formulaire, la plateforme Monelib effectue le contrôle des codes saisis. Trois cas sont alors possibles : Les codes sont valides : l utilisateur est redirigé vers la page déclarée par le marchand si le paiement est réputé effectué. Au moins un des codes saisis est invalide : l utilisateur est redirigé vers la page déclarée par le marchand si le paiement est réputé non effectué. En l absence de déclaration d une telle page par le marchand, l utilisateur est redirigé vers une page par défaut prévu à cet effet sur le site Monelib. Une erreur est survenue : si lors de la vérification du paiement une erreur survient, l utilisateur est redirigé vers la page déclarée par le marchand pour un tel événement. En l absence de déclaration d une telle page par le marchand, l utilisateur est redirigé vers une page par défaut prévu à cet effet sur le site Monelib. Les erreurs pouvant survenir peuvent être soit un dysfonctionnement de la plateforme Monelib ou une mauvaise installation du script d accès (paramètres manquants, incorrects etc.) Lors de l enregistrement de son point de vente sur le site Monelib, le marchand à la possibilité de demander le renvoi des paramètres sur les pages de retour. Cette option, dans les cas de paiement refusé ou d erreur, ne fonctionne que si le marchand à déclaré ses propres pages de refus de paiement ou d erreur. Le renvoi des paramètres s effectue en méthode «GET». Les paramètres retournés sont les suivants : monelib_pincoden : code d accès saisi, avec n compris entre 0 (inclus) et 4 (inclus) monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. b Monnaie virtuelle Lors de la saisie d un code dans la zone d achat de monnaie virtuelle, la plateforme Monelib en effectue le contrôle. Les résultats de ce contrôle sont les mêmes que pour le script de micro paiement. 9

10 Parallèlement, l url de notification configurée est appelée avec le résultat du paiement et le montant de monnaie virtuelle que le marchand doit créditer à son client. c Carte bancaire EZShot et MultiShot Le comportement est équivalent à celui décrit ci dessus, sachant que, concernant le code saisi, seul le paramètre monelib_pincode0 sera existant (car un seul code est saisi). 10

11 3 Appel de l Url de notification Si le marchand a défini une url de notification, la plateforme Monelib l appellera à chaque accès, réussi ou non, et à chaque achat de codes EZShot ou MultiShot. L appel de l url de notification se réalise dans les minutes, voire les secondes suivant l accès. Si l appel échoue, il est répété 4 fois avec un intervalle de 60 secondes. A noter que pour la monnaie virtuelle, cette url de notification étant obligatoire, son appel est réalisé à chaque saisie de code, valide ou non. Les paramètres renvoyés (en méthode «POST») sont les suivants : a Utilisation d un code micro paiement monelib_pincoden : code d accès saisi, avec n compris entre 0 (inclus) et 4 (inclus) monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. monelib_result : peut avoir la valeur «OK» ou «KO» selon que l accès est autorisé ou refusé. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_meaning : aura la valeur «MICROPUSE» b Utilisation d un code micro paiement dans la zone d achat de monnaie virtuelle Les paramètres sont identiques à ceux ci dessus (micro paiement) avec, en plus : monelib_virtualamount : le montant de monnaie virtuelle à créditer au compte du client. monelib_data0 : la même valeur que celle indiquée dans le paramètre ext_frm_userid de l url de la zone d achat. c Utilisation d un code MultiShot monelib_pincode0 : code d accès saisi. monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. 11

12 monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. monelib_result : peut avoir la valeur «OK» ou «KO» selon que l accès est autorisé ou refusé. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_meaning : aura la valeur «USEMULTISHOT» d Utilisation d un code EZShot monelib_pincode0 : code d accès saisi. monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. monelib_result : peut avoir la valeur «OK» ou «KO» selon que l accès est autorisé ou refusé. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_meaning : aura la valeur «USEEZSHOT» e Achat d un code EZShot monelib_pincode0 : code d accès généré. monelib_pos : identifiant du point de vente monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_ _customer : adresse du client monelib_meaning : aura la valeur «NEWEZSHOT» monelib_test : aura la valeur 1 si la carte de test a été utilisée (sinon, paramètre absent) monelib_trans : identifiant de la transaction (si une carte de test a été utilisée, aura la valeur «test») f Achat d un code MultiShot monelib_pincode0 : code d accès généré. monelib_pos : identifiant du point de vente monelib_expires : timestamp UNIX indiquant la date de fin de l abonnement. monelib_affiliateidn : identifiant d un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. 12

13 monelib_affiliateamountn : montant reversé à un affilié, avec n compris entre 0 (inclus) et 9 (inclus). Ce paramètre est détaillé plus loin. monelib_datan : données libres du marchand, avec n compris entre 0 (inclus) et 99 (inclus). Ce paramètre est détaillé plus loin. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_ _customer : adresse du client monelib_meaning : aura la valeur «NEWMULTISHOT» monelib_test : aura la valeur 1 si la carte de test a été utilisée (sinon, paramètre absent) monelib_trans : identifiant de la transaction (si une carte de test a été utilisée, aura la valeur «test») g Renouvellement d un code MultiShot monelib_pincode0 : code d accès saisi. monelib_expires : timestamp UNIX indiquant la date de fin de l abonnement. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_ _customer : adresse du client monelib_meaning : aura la valeur «RENEWMULTISHOT» monelib_test : aura la valeur 1 si la carte de test a été utilisée (sinon, paramètre absent) monelib_trans : identifiant de la transaction (si une carte de test a été utilisée, aura la valeur «test») Les informations concernant les données libres et l affiliation ne sont pas communiquées (même si les affiliés sont gérés lors des renouvellements). h Rejet d un code MultiShot ou EZShot Cet évènement se produit si, après l achat, il s avère que la transaction était frauduleuse (carte volée etc.). Attention! Pour que l url de notification soit appelée en cas de rejet, il faut que le point de vente concerné soit toujours existant dans votre configuration Monelib. De plus, c est l url de notification configurée au moment du rejet qui est prise en compte (et non pas l url de notification configurée au moment de l achat, laquelle peut être différente en cas de modification de votre configuration entre temps). monelib_pincode0 : code d accès. monelib_timestamp : un timestamp UNIX représentant l heure de l évènement. monelib_trans : identifiant interne de la transaction monelib_meaning : aura la valeur «REJECT» 13

14 4 Ajout de paramètres supplémentaires au script d achat et d accès Le marchand à la possibilité d ajouter différents paramètres au script d accès et scripts d achat. Selon le type de script, les noms des paramètres peut être légèrement différents. a Ajout de paramètres dans le script de micro paiement L ajout de paramètres se fait par l insertion dans la page sur laquelle est installé le script d accès de balises HTML de type «hidden» : le paramètre «name» de la balise contiendra le nom du paramètre et le paramètre «value» de la balise la valeur du paramètre. Exemple : <input type= hidden name= monelib_data0 value= Commande numéro 5 /> b Ajout de paramètres dans la zone d achat de monnaie virtuelle L ajout de paramètres se fait en ajoutant des paramètres à l url de la zone d achat. Par défaut, l url de la zone d achat est du type : t_frm_userid=remplacer_la_valeur_ici Il suffit d ajouter les paramètres nécessaires à la suite de l url. Par exemple, pour changer la couleur de fond de la zone d achat (couleur noire) : t_frm_userid=remplacer_la_valeur_ici&ext_frm_bgcolor= Aussi, il est nécessaire de modifier la valeur du paramètre ext_frm_userid par un identifiant, au choix du marchand, lui permettant de reconnaitre son client à créditer de monnaie virtuelle. En effet, cette valeur est reprise lors de l appel de l url de notification, cette dernière servant justement à créditer l utilisateur. c Ajout de paramètres dans les scripts d achat et d accès carte bancaire La méthode est similaire à celle du micro paiement. Toutefois, les champs «hidden» devront être ajoutés dans le formulaire HTML fourni (et non pas n importe où sur la page HTML). d Paramètres concernant l affiliation 14

15 Il est à noter que concernant les scripts EZShot et MultiShot, les paramètres concernant l affiliation doivent être placés dans les scripts d achat, et non pas dans les scripts d accès. L ajout d affiliés directement dans les scripts s effectue en précisant, pour chacun d eux, son identifiant de compte Monelib et le montant à lui reverser. Ce montant est déduit du gain du marchand. Il est possible d ajouter jusqu à 10 affiliés et de préciser un libellé d affiliation qui apparaîtra dans les statistiques «affilé» et «affilieur» et le nom du site sur lequel à lieu l affiliation, cela pour en faciliter la lecture. Pour préciser le numéro de compte d un affilié, on utilisera le paramètre «monelib_affiliateidn», n compris entre 0 (inclus) et 9 (inclus) dont la valeur sera les 17 chiffres du numéro de compte de l affilié. Pour préciser le montant reversé à un affilié «n», on utilisera le paramètre «monelib_affiliateamountn», n compris entre 0 (inclus) et 9(inclus) lequel représentera la valeur absolue du reversement affilié à effectuer, le pourcentage du reversement du marchand à reverser à l affilié ou un identifiant de «plan de reversement affilié». Pour préciser le nom du site de cette affiliation, on utilisera le paramètre «monelib_site_title» qui contiendra le nom du site (par exemple «LeSuperSite.com»). Le champ «monelib_site_title» n est pas obligatoire : s il n est pas précisé, alors le libellé sera automatiquement le nom de la zone de vente. Pour préciser un libellé pour cette affiliation, on utilisera le paramètre «monelib_title» qui contiendra un libellé libre (par exemple : «Affiliation au site abcd.com à 50%») Le champ «monelib_title» n est pas obligatoire : s il n est pas précisé, alors le libellé sera automatiquement le nom du point de vente. Exemple pour le micro paiement: L affilié 0 à comme numéro de compte le : <input type= hidden name= monelib_affiliateid0 value= /> L affilié 0 reçoit 0,25 euros sur le reversement du marchand : <input type= hidden name= monelib_affiliateamount0 value= 0.25 /> Si on avait voulu préciser un pourcentage, par exemple 10,5%, la syntaxe ci dessus aurait été : <input type= hidden name= monelib_affiliateamount0 value= 10.5% /> 15

16 Si on avait voulu préciser l identifiant d un «plan de reversement affilié», la syntaxe ci dessus aurait été (si le plan de reversement a comme identifiant «PLAN3456») : <input type= hidden name= monelib_affiliateamount0 value= PLAN3456 /> Pour préciser un un nom de site, par exemple «SuperSite.com» : <input type= hidden name= monelib_site_title value= SuperSite.com /> Pour préciser un libellé, par exemple «Affiliation à 10.5%» : <input type= hidden name= monelib_title value= Affiliation à 10.5% /> Note concernant les scripts EZShot et MultiShot Pour préciser les données d affiliation dans le script d achat EZShot et MultiShot (ou dans un script micro paiement que vous avez vous même réalisé), le nom des paramètres seront différents, à savoir : «ext_frm_affiliateidn», «ext_frm_affiliateamountn», «ext_frm_site_title» et «ext_frm_title». D autre part, il n est pas possible d indiquer un identifiant de «plan de reversement affilié» pour les EZShot et MultiShot. Exemple : <input type= hidden name= ext_frm_affiliateamount0 value= 0.25 /> Note concernant les scripts d achat de monnaie virtuelle Pour préciser les données d affiliation dans le script d appel de la zone d achat de Monnaie Virtuelle, le nom des paramètres seront différents, à savoir : «ext_frm_affiliateidn», «ext_frm_affiliateamountn», «ext_frm_site_title» et «ext_frm_title». Exemple : t_frm_userid=remplacer_la_valeur_ici&ext_frm_affiliateamount0=0.25&ext_frm_ affiliateid= e Données libres L ajout de données libres de la part du marchand est possible via le paramètre «monelib_datan», n compris entre 0 (inclus) et 99 (inclus). Exemple : Ajout de deux données libres dans un script de micro paiement : 16

17 <input type= hidden name= monelib_data0 value= première donnée /> <input type= hidden name= monelib_data1 value= seconde donnée /> Dans le cas du MultiShot et EZShot, des données libres peuvent être placés à la fois dans les scripts d achat et les scripts d accès : dans le premier cas, ces paramètres vous seront retournés lors de l achat du code EZShot ou MultiShot uniquement, dans le second cas, les données sont retournées lors de l utilisation des codes. De plus, le nom des paramètres seront de la forme «ext_frm_datan» (de même si vous utilisez un script d accès micro paiement que vous avez fait vous même). Exemple : <input type= hidden name= ext_frm_data0 value= première donnée /> Dans le cas du script de Monnaie Virtuelle, les données libres sont placées directement dans l url d appel de la zone d achat de monnaie virtuelle, via les paramètres «ext_frm_datan», compris entre 1 (inclus) et 99 (inclus) (l indice 0 étant réservé) Exemple : t_frm_userid=remplacer_la_valeur_ici&ext_frm_data1=donnée1 Pour que ces données vous soient effectivement retournées comme paramètres de la page payante (ou de la page code invalide selon le cas), vous devez activer la fonctionnalité en cochant les cases prévues à cet effet en bas du formulaire de configuration des points de ventes. f Inhibition de l ajout de paramètres dans le script de micro paiement 17

18 Pour des raisons de sécurité, il peut être utile d empêcher la prise en compte par la plateforme Monelib de tout paramètre supplémentaire dans les scripts de micro paiement (cela n est pas possible pour les scriptsmonnaie virtuelle, EZShot et MultiShot). Cela est rendu possible en ajoutant le paramètre «monelib_noparam» : Exemple : <input type= hidden name= monelib_noparam value= 1 /> Dans un tel cas, aucun autre paramètre supplémentaire ne sera pris en compte. g Préfixage des paramètres dans le script de micro paiement Dans certains cas, notamment la présence de plusieurs scripts d accès micro paiement sur une même page, il est nécessaire de préfixer le nom de chaque paramètre supplémentaire pour indiquer à la plateforme avec quel script est associé chaque paramètre (cela n est pas possible pour les scripts Monnaie Virtuelle, EZShot et MultiShot). Le nom du préfixe est au choix du marchand et doit être passé en paramètre dans le script d installation. Exemple : Le préfixe choisi est «nestor» : <script type="text/javascript" src=" 45&ext_frm_prefix=nestor" ></script> Pour ce script d accès, tous les noms des paramètres supplémentaires devront être préfixés par «nestor», par exemple : <input type= hidden name= nestor_monelib_data0 value= première donnée /> <input type= hidden name= nestor_monelib_data1 value= seconde donnée /> h Utilisation d alias pour les paramètres supplémentaires d affiliation La valeur des paramètres concernant l affiliation peuvent être des «alias» définis dans l espace client Monelib du marchand, rubrique «Avancé>Alias script», cela afin de garantir une confidentialité concernant leur valeur. Pour indiquer qu une valeur correspond à un alias, celle ci doit débuter par le caractère «@» ; 18 Ainsi, si le marchand a défini un alias nommé «alias01» ayant la valeur « », le paramètre

19 <input type= hidden name= monelib_affiliateid0 value= /> pourra également s écrire <input type= hidden name= monelib_affiliateid0 /> i Langue de l interface d achat de MultiShot et de EZShot Par défaut, l interface d achat des MultiShot et EZShot est en Français et Anglais. Vous pouvez choisir de ne l afficher qu en Anglais. Pour cela, dans le script du bouton d achat, ajoutez le paramètre : <input type= hidden name= ext_frm_tpldiz value= std_en /> L interface ne s affichera alors qu en Anglais. j Apparence de la zone d achat de monnaie virtuelle Il est possible de modifier la couleur de fond et la couleur de texte de la zone d achat de monnaie virtuelle. Pour cela, les paramètres suivant peuvent être ajoutés à l url d appel de la zone d achat : ext_frm_bgcolor : Code hexadécimal de la couleur de fond (Ex : ff2525) ext_frm_fontcolor : Code hexadécimal de la couleur de fond (Ex : 00ff56) k Indication du cadre d ouverture des pages de retour pour les paiements Monnaie Virtuelle. Vous pouvez indiquer dans quel cadre seront ouvertes les pages de retour pour les paiements Monnaie virtuelle. Par défaut, les pages de retour s affichent sur la page complète (target = _top). Le paramètre ext_frm_target permet de changer ce comportement : ext_frm_target : Nom de la cible (par exemple : _self, _blank, etc.) 19

20 5 Sécurisation des pages à accès restreint et validation des codes par requête http Les pages dont l accès est subordonné au paiement par codes d accès Monelib (micro paiement, EZShot ou MultiShot) doivent être sécurisées. Deux méthodes sont possibles : standard et avancée. a Sécurisation standard Cette sécurisation, généralement suffisante, se fait simplement par l insertion entre les balises <head> et </head> de chaque page HTML du script : <noscript> <meta http-equiv="refresh" content="0;url= </noscript> <script type="text/javascript" src=" " ></script> Ces lignes sont fournies sur le site Monelib sur la page d installation de chaque script d accès. Il est important que le marchand informe sa clientèle que la JavaScript doit être activé sur leur navigateur. Ces lignes empêchent l appel de la page sur lequel elles sont installées si le client n a pas payé son accès précédemment. Lorsqu une même page appartient à plusieurs points de ventes, le script ci dessus doit être modifié de telle sorte que le paramètre «ext_frm_idpos» énumère les identifiants des différents points de ventes. Par exemple, si une page fait partie des points de vente 28, 54 et 78, le script devra être : <noscript> <meta http-equiv="refresh" content="0;url= </noscript> <script type="text/javascript" src=" ></script> Il est recommandé, avec l utilisation de cette méthode, que le marchand place les pages nécessitant un paiement dans un dossier de son site avec un nom difficilement devinable. 20

21 b Sécurisation avancée et validation des codes d accès par requête http Cette méthode nécessite que le marchand ait la faculté d utiliser un langage de script coté serveur. Il est également nécessaire que le marchand active le retour des paramètres dans l url de la page protégée, afin que le script côté serveur ait connaissance des codes saisis par le client. Le principe est que chaque page nécessitant un paiement par Monelib va interroger la plateforme afin de savoir si les codes saisis sont valides. Dans la négative, le script du marchand devra afficher ou erreur ou rediriger le visiteur vers une page adéquate. Cette interrogation s effectue par requête http. L url est : Différentes valeurs doivent être passées en paramètres de cette url : ext_frm_coden : code d accès utilisé par le client, n allant de 0 à 4 (inclus), selon le paramétrage du point de vente. ext_frm_online : ce paramètre doit avoir la valeur «1» ext_frm_verbose : si ce paramètre vaut «1» et que le point de vente correspond à micropaiement, le résultat de la requête sera plus complet en cas d acceptation du ou des codes. ext_frm_pos : identifiant du point de vente concerné ext_frm_zos : identifiant de la zone de vente à laquelle appartient le point de vente La plateforme peut renvoyer alors : ERR : une erreur de traitement est survenue KO : le ou les codes d accès ne sont pas acceptés pour ce point de vente Si le paramètre ext_frm_verbose n est pas à 1 ou si l un des codes est le code de test du point de vente : OK : le ou les codes d accès sont acceptés pour ce point de vente Sinon plusieurs lignes qui, pour chaque code vérifié indique le ou les identifiants du palier utilisé : 21 OK Code0 Identifiant(s) palier du code0 Code1 Identifiant(s) palier du code1

22 Coden Identifiant(s) palier du coden Si certains codes sont des codes dits «gratuits» ou bien si le palier utilisé pour générer le code a été supprimé dans votre Espace Client, l identifiant palier retourné sera «N/A». Plusieurs identifiants peuvent être retourné si vous avez ajouté à votre liste de paliers plusieurs paliers identiques. Exemple : Le point de vente dont l identifiant est «5565» et appartenant à la zone de vente dont l identifiant est «999» nécessite 2 codes d accès. Le client a saisi sur le script d accès les code ABCDEFGH et La vérification se fera en appelant : &ext_frm_zos=999&ext_frm_code0=ABCDEFGH&ext_frm_code1= Note importante : Pour les code micro paiement et EZShot, l appel de cet url pour vérification des codes ne «grille» pas une utilisation des codes : si vous avez défini qu un code d accès pour votre point de vente est valable 2 fois, l appel de cette url ne comptabilisera pas un accès de plus. En effet, la comptabilisation de l accès est effectué lorsque le client saisi son ou ses codes sur le script de paiement. Si toutefois vous souhaitez que l appel de l url pour vérification comptabilise le nombre d accès, ajoutez le paramètre «ext_frm_validateuse» à la valeur «1». Exemple : &ext_frm_zos=999&ext_frm_code0=ABCDEFGH&ext_frm_code1= &ext_frm_ validateuse=1 Cela est nécessaire si, par exemple, le codes d accès ne sont pas saisi par le client dans le script d accès Monelib, mais directement dans votre application. Un exemple en PHP de validation de code par script PHP est disponible dans à l Annexe A de ce document. 22 c Validation d un nombre variable de codes sur un palier donné

23 Il est possible, via la requête http de validation de code expliquée juste avant, de valider un ou plusieurs codes d accès sur un palier pouvant être différent de ceux configurés pour un point de vente donné. Par exemple, si votre point de vente demande 1 seul code et que les paliers acceptés sont un palier France Audio et un palier Suisse SMS, vous pouvez toutefois effectuer une requête qui répondra OK uniquement si 2 codes sont saisis et appartenant à un autre palier au choix. La requête sera similaire à la requête standard de vérification de code avec, en plus les paramètres : Exemple : ext_frm_numpin : nombre de codes nécessaires ext_frm_accessid : l'identifiant du palier auquel doit appartenir le ou les codes. Plusieurs identifiants peuvent être indiqués en les séparant par un &ext_frm_zos=999&ext_frm_code0=ABCDEFGH&ext_frm_code1= &ext_frm_ validateuse=1&ext_frm_numpin=2&ext_frm_accessid=5698 Les identifiants de paliers sont visibles dans la rubrique «Configuration > Paliers micro paiement» : pour chaque palier disponible, cliquez sur le bouton «Configurer». L identifiant du palier est alors indiquée. Cliquer sur «Configurer» affiche le détail du palier, dont son identifiant : 6 Accès à la passerelle La passerelle Monelib permet à votre application, via un échange de flux XML, d interroger la plateforme Monelib. 23

24 L url de la passerelle est : Il est également possible de communiquer de manière sécurisée à l adresse : Le flux en entrée doit être fourni dans le paramètre «ext_xml», en méthode «Post» ou «Get». Lors de vos requêtes, il est nécessaire d indiquer votre nom d utilisateur et votre «mot de passe passerelle». Le nom d utilisateur est celui que vous utilisé habituellement pour vous connecter à votre espace utilisateur. Le «mot de passe passerelle» est, par défaut, le même mot de passe que le mot de passe de connexion qui vous a été attribué lors de la création de votre compte Monelib. Cependant, il est vivement recommandé de le modifier dans la rubrique «Avancé > Mot de passe passerelle». Au fur et à mesure du développement de Monelib, différentes fonctions seront ajoutées à la passerelle. a Obtention des paliers micro paiement configurés pour un point de vente Cette fonctionnalité vous permet, pour un point de vente «micro paiement» donné, de connaitre les différents paliers configurés. Cette fonctionnalité peut être nécessaire si vous désirez gérer vous même l affichage des différents éléments du script d accès. Flux de la demande : <?xml version="1.0" encoding="utf-8"?> <gateway> <getaccessinfo> <pfm>5</pfm> <login>login</login> <password>mot_de_passe</password> <pos>idpos</pos> <group>groupe</group> </getaccessinfo> </gateway> pfm Toujours à la valeur 5 login Nom d utilisateur password Mot de passe passerelle pos Identifiant du point de vente group Identifiant du groupe de palier (optionnel) Si aucun identifiant de groupe de palier n est précisé, l ensemble des paliers configurés sera retourné. 24

25 Dans le cas contraire, seul le palier du groupe indiqué sera retourné (si configuré). Liste des groupes de paliers 1 Belgique audio 2 Suisse audio 3 Luxembourg audio 4 France audio 5 Canada audio 6 Pays Bas SMS 7 Norvège SMS 8 Portugal SMS 9 Suède SMS 10 Espagne SMS 11 Danemark SMS 12 Royaume Uni SMS 13 Irlande SMS 14 Belgique SMS 15 Allemagne SMS 16 Suisse SMS 17 France SMS 18 Etats Unis SMS 19 Carte bancaire 20 Carte Neosurf 21 France DOM audio 22 Internet+ 23 MPME Flux de la réponse (en cas de succès ) : <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <accessinfo> <pos> <name>nom_pos</name> <numpincode>nombre_codes</numpincode> </pos> <result> <idgroup>groupe</idgroup> <shortname>nom</shortname> <mediatype>code</mediatype> <call>numéro_url</call> <idservice>code_service</idservice> <price>tarification</price> </result> <result>. </result> <accessinfo> </gateway> 25 name numpincode Nom du point de ventes Nombre de codes nécessaires

26 idgroup Identifiant du groupe du palier shortname Nom court du palier (ex : FR/V [A] ) mediatype Type de média : AUDIO,SMS,CC call Si le type de média est «AUDIO», l information correspond à un numéro de téléphone. Si le type de média est «SMS», l information correspond au numéro d appel SMS avec son mot clé, séparés par un «/» (ex : 8555/CODE) Si le type de média est «CC», l information correspond à l url de l interface d achat avec ses paramètres. idservice Identifiant service pour paliers étendus (ou «0» s il s agit d un palier standard) price Si le type de média est «AUDIO» ou «SMS», indique la tarification utilisateur Flux de la réponse (en cas d erreur) <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>code</errornum> <errorlabel>label</errorlabel> </declined> </gateway> errornum errorlabel Code d erreur Information texte sur l erreur Les erreurs possibles sont : 100 Flux XML non trouvé 101 Format XML incorrect 102 Login invalide 103 Point de vente incorrect 104 Point de vente de type incorrect 105 Impossible d accéder aux infos paliers 106 Point de vente manquant 999 Requête incorrecte Exemple de réponse en cas de succès : 26 <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <accessinfo> <pos> <name>point de vente</name> <numpincode>3</numpincode> </pos> <result> <idgroup>19</idgroup> <shortname>cc</shortname>

27 <mediatype>cc</mediatype> <call> _frm_idservice=325&ext_frm_num=1</call> </result> <result> <idgroup>1</idgroup> <shortname>be/v [AX]</shortname> <mediatype>audio</mediatype> <call> </call> <idservice>956214</idservice> <price>2,00 EUR/appel</price> </result> <result> <idgroup>7</idgroup> <shortname>no/s [A]</shortname> <mediatype>sms</mediatype> <call>2000/key</call> <idservice>0</idservice> <price>3,00 NOK/SMS</price> </result> <accessinfo> </gateway> Exemple de réponse en cas d erreur : <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>100</errornum> <errorlabel>invalid login</errorlabel> </declined> </gateway> b Obtention des informations pour un palier donné Cette fonctionnalité vous permet, pour un palier donné, d obtenir les différentes informations sur celui ci. Cette fonctionnalité peut être nécessaire si vous désirez gérer vous même l affichage des différents éléments du script d accès. Flux de la demande : <?xml version="1.0" encoding="utf-8"?> <gateway> <getaccessinfobyid> <pfm>5</pfm> <login>login</login> <password>mot_de_passe</password> <idaccess>idaccess</idaccess> </getaccessinfobyid> </gateway> pfm Toujours à la valeur 5 login Nom d utilisateur password Mot de passe passerelle idaccess Identifiant du palier. Cet identifiant se trouve dans la liste de vos 27

28 paliers, en cliquant sur le bouton «Configurer» de chacun d eux. Flux de la réponse (en cas de succès ) : <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <accessinfobyid> <idgroup>groupe</idgroup> <shortname>nom</shortname> <mediatype>code</mediatype> <call>numéro_url</call> <idservice>code_service</idservice> <price>tarification</price> <accessinfobyid> </gateway> name Nom du point de ventes numpincode Nombre de codes nécessaires idgroup Identifiant du groupe du palier shortname Nom court du palier (ex : FR/V [A] ) mediatype Type de média : AUDIO,SMS,CC call Si le type de média est «AUDIO», l information correspond à un numéro de téléphone. Si le type de média est «SMS», l information correspond au numéro d appel SMS avec son mot clé, séparés par un «/» (ex : 8555/CODE) Si le type de média est «CC», l information correspond à l url de l interface d achat avec ses paramètres. idservice Identifiant service pour paliers étendus (ou «0» s il s agit d un palier standard) price Si le type de média est «AUDIO» ou «SMS», indique la tarification utilisateur Flux de la réponse (en cas d erreur) <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>code</errornum> <errorlabel>label</errorlabel> </declined> </gateway> errornum errorlabel Code d erreur Information texte sur l erreur Les erreurs possibles sont : 100 Flux XML non trouvé 101 Format XML incorrect 102 Login invalide 28

29 103 Identifiant palier incorrect 104 Impossible d accéder aux infos paliers 999 Requête incorrecte c Obtention des codes d accès générés sur une journée Cette fonctionnalité vous permet, pour une date donnée, d obtenir la liste des codes d accès ayant été générés pour vos points de ventes. Flux de la demande : <?xml version="1.0" encoding="utf-8"?> <gateway> <getpinlist> <pfm>5</pfm> <login>login</login> <password>mot_de_passe</password> <day>jour</day> <month>mois</month> <year>annee</year> <csvdelimiter>delimiteur</csvdelimiter> </getpinlist> </gateway> pfm Toujours à la valeur 5 login Nom d utilisateur password Mot de passe passerelle day Jour (1 à 31) month Mois (1 à 12) year Année (par exemple «2009») csvdelimiter Optionnel. Delimiteur pour fichier CSV (par exemple «;») Si cette information est fournie, la réponse renvoyée ne sera pas en XML 29 Flux de la réponse (en cas de succès et si «csvdelimiter» n est pas indiqué ) : <gateway> <version>1.0</version> <pinlist> <pin> <pin>7w6fdsbj</pin> <tcreated> </tcreated> <rev>0.000</rev> <mediatype>ezshot</mediatype> <type>--</type> <group>--</group> </pin> <pin> <pin>gcje3ea5</pin> <tcreated> </tcreated> <rev>0.000</rev> <mediatype>free</mediatype> <type>--</type> <group>--</group> </pin> <pin> <pin>fg89ytds</pin>

30 </pin> </pinlist> </gateway> <tcreated> </tcreated> <rev>1.200</rev> <mediatype>audio</mediatype > <type>fr/v [BX]</type> <group>4</group> pin Code d accès tcreated Timestamp UNIX indiquant la date de création du code rev Reversement hors taxes type Nom court du palier (ex : FR/V [A], BE/S [B] ) mediatype Type de média : AUDIO, SMS, CC, FREE, EZSHOT, MULTISHOT group Identifiant du groupe de palier (voir page 21 pour la liste des groupes) : 1 = Belgique Audiotel, 2 = Suisse audiotel, etc Flux de la réponse (en cas d erreur, même si csvdelimiter est founrni) <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>code</errornum> <errorlabel>label</errorlabel> </declined> </gateway> errornum errorlabel Code d erreur Information texte sur l erreur Les erreurs possibles sont : 100 Flux XML non trouvé 101 Format XML incorrect 102 Login invalide 103 Année incorrecte 104 Mois incorrect 105 Jour incorrect 106 Date incorrecte 107 Pas de zone de ventes existante 108 Erreur interne 999 Requête incorrecte Le type (nom court du palier) correspond au nom du palier que vous pouvez trouver dans la rubrique «Reversements» de Monelib. Les deux premières lettres correspondent au pays (FR, BE, CH, DE etc.) ou CC pour la carte bancaire ou NS pour la carte Neosurf. 30

31 Si le paramètre csvdelimiter est fourni, la réponse ne sera pas en XML mais sur plusieurs lignes dont les informations seront séparées par le délimiteur fourni. Par exemple, si le délimiteur est «,» : 7W6FDSBJ, ,0.000,EZSHOT,--,-- GCJE3EA5, ,0.000,FREE,--,-- FG89YTDS, , 1.200,AUDIO,FR/V [BX],4 Limitations : Les codes qui ne sont plus valides disparaissent de la liste au bout de 3 mois. Seuls les codes attribués à des points de vente existants lors de la demande seront retournés. d Obtention du chiffre d affaire sur une journée Cette fonctionnalité vous permet, pour une date donnée, d obtenir le chiffre d affaire réalisé sur une journée. Vous pouvez demander votre propre chiffre d affaire ou celui de n importe quel autre compte Monelib, à condition que son titulaire vous ai communiqué son mot de passe public. On entend par chiffre d affaire la somme des gains dus aux ventes réalisées (moins les gains reversés à d éventuels affiliés), au parrainage, aux affiliations. Le «nombre d opération» retourné correspond à la somme du nombre de ventes, du nombre des gains d affiliations et du nombre des gains dus au parrainage. Ces statistiques pour un jour J ne sont accessibles qu à partir du jour J+1. Flux de la demande : <?xml version="1.0" encoding="utf-8"?> <gateway> <publicstats> <userlogin>login</userlogin> <userpassword>mot de passé public</userpassword> <day>jour</day> <month>mois</month> <year>année</year> </publicstats> </gateway> userlogin Nom d utilisateur userpassword Mot de passe public de l utilisateur day Jour (1 à 31) month Mois (1 à 12) year Année (par exemple «2009») 31 Flux de la réponse (en cas de succès) :

32 <gateway> <version>1.0</version> <publicstats> <amount>45.212</amount> <opnum>32</opnum> </publicstats> </gateway> amount opnum Chiffre d affaire sur ce jour Nombre d opérations ayant entraîné ce chiffre d affaire Flux de la réponse (en cas d erreur) <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>code</errornum> <errorlabel>label</errorlabel> </declined> </gateway> errornum errorlabel Code d erreur Information texte sur l erreur Les erreurs possibles sont : 100 Flux XML non trouvé 101 Format XML incorrect 102 Login invalide 103 Jour incorrect 104 Mois incorrect 105 Année incorrecte 106 Date incorrecte 107 Erreur interne 999 Requête incorrecte e Annulation du renouvellement d un abonnement Cette fonctionnalité permet de stopper un abonnement (MultiShot) de l un de vos abonnés. Le code d accès de votre abonné reste valide jusqu'à sa date de renouvellement, mais ne sera ensuite pas renouvelé. 32 Flux de la demande : <?xml version="1.0" encoding="utf-8"?> <gateway> <cancelsubscription> <pfm>5</pfm> <login>login</login> <password>mot_de_passe</password> <pin>code_abonne</pin>

33 </cancelsubscription> </gateway> pfm Toujours à la valeur 5 login Nom d utilisateur password Mot de passe passerelle pin Code de l abonné (8 caractères) Flux de la réponse (en cas de succès) : <gateway> <version>1.0</version> <cancelsubscription> <cancelled>yes</cancelled> </cancelsubscription> </gateway> cancelled Valeur = YES Flux de la réponse (en cas d erreur) <?xml version="1.0" encoding="utf-8"?> <gateway> <version>1.0</version> <declined> <errornum>code</errornum> <errorlabel>label</errorlabel> </declined> </gateway> errornum errorlabel Code d erreur Information texte sur l erreur Les erreurs possibles sont : 100 Flux XML non trouvé 101 Format XML incorrect 102 Login invalide 103 Code abonné manquant 104 Abonnement non trouvé 105 Erreur interne 106 Abonnement non actif 107 Erreur interne 108 Erreur interne 999 Requête incorrecte f Script de test des flux XML Vous trouverez ci dessous un petit script PHP5 (extension curl nécessaire) à utiliser en ligne de commande vous permettant de tester vos flux XML. 33

34 Le flux envoyé doit être dans un fichier texte. La réponse du serveur est affichée sur la sortie standard. Exemple d appel :./testxml.php flux.txt./testxml.php * Envoi le flux contenu dans le fichier flux.txt Envoi les flux de tous les fichiers dont les noms commencent par «xml». Code : #!/usr/local/php5/bin/php // La ligne ci dessus doit être modifiée selon la configuration de votre système <?php function sendxml($xml,$url="") { $turl=parse_url($url); if (!isset($turl['path'])) $turl['path']='/'; } $curl = curl_init(); curl_setopt($curl,curlopt_timeout,10); curl_setopt($curl,curlopt_post,1); curl_setopt($curl,curlopt_ssl_verifypeer,false); curl_setopt($curl,curlopt_useragent,"testmonelib"); curl_setopt($curl,curlopt_url,$turl['scheme'].'://'.$turl['host'].$turl['path']); curl_setopt($curl,curlopt_postfields,'ext_xml='.urlencode($xml)); ob_start(); if (curl_exec($curl)!==true) return false; $output = ob_get_contents(); ob_end_clean(); curl_close($curl); return $output; if ($argv[1]=='*') { $t_files=array(); if ($handle = opendir('.')) { while (false!== ($file = readdir($handle))) { if (eregi("^xml",$file)) { $t_files[]=$file; } } closedir($handle); } sort($t_files); } else { $t_files=array($argv[1]); } foreach($t_files as $filename) { echo ("Envoi de \"$filename\"\n"); $tosend=file_get_contents($filename); $rx=sendxml($tosend,' echo ("Réponse passerelle:\n$rx\n \n"); }?> 34

35 Annexe A Validation et grillage de code par script PHP S applique au micro paiement simple, EZShot et MultiShot. Le principe est le suivant : a L utilisateur saisi son code dans un formulaire sur votre site (codeinput.html), lequel point vers le script de validation en PHP (codecheck.php) installé sur votre site. b Si le code saisi est valide, alors un flag est positionné à «1» dans la session de l utilisateur et il est ensuite redirigé vers la page payante (pageok.php). c Si le code saisi n est pas valide, alors l utilisateur est redirigé vers une page d erreur. d «pageok.php» soit vérifié que l utilisteur est bien autorisé en vérifiant la position du flag. Si la partie payante du site contient plusieurs pages, alors ce test doit être effectué sur chacune d elles. S il est nécessaire de supprimer l autorisation à l utilisateur, il suffit de supprimer le flag. Formulaire HTML de la page «codeinput.html» <form action="checkcode.php" method="post"> <input type="text" name="code" size="8" maxlength="8" /> <input type="submit" value=" Go! " /> </form> «codecheck.php» <?php session_start(); unset($_session['monelibok']); $idpos = ; $idzos = ; // Identifiant du point de vente A MODIFIER // Identifiant de la zone de vente A MODIFIER if (!isset($_post['code'])) { // Erreur exit; } $code = trim($_post['code']); $checkurl = " &ext_frm_code0=$code"; $r = file( $checkurl ); if (is_array($r)) { $res = trim($r[0]); } else { $res="err"; } 35 if ($res=='ok') {

36 // Le code est valide. $_SESSION['monelibok']=1; // Ici, faire ce que vous voulez si le code est ok. //exemple : redirection vers une page : header("location: pageok.php"); header("location: pageok.php"); exit; } // Le code n'est pas correct // Afficher une erreur ou rediriger vers une page d'erreur //exemple : redirection vers une page : header("location: mapagepasok.php");?> «pageok.php» <?php session_start(); if (!isset($_session['monelibok']) $_SESSION['monelibok']!=1) { // Accès non autorisé exit; } // Ici vous faites ce que vous voulez... // Si vous désirez que l'utilisateur ne puisse pas revenir sur cette page ensuite, il faut enlever le flag comme ceci : unset($_session['monelibok']);?> 36