Documentation d Intégration CB Paysite Cash

Transcription

1 Documentation d Intégration CB Paysite Cash VERSION DU 07/01/ Configuration des paramètres du site dans votre interface commerçant Configuration générale du site Configuration liste noire des pays Configuration liste noire des porteurs Générateur d'url de paiement Configuration options Agent OpenMembers Configuration des mails de confirmation des abonnements Configuration graphique des pages de paiement Marque blanche Upload des images Gestion des abonnements Gestion des membres Files d attente Logs L affiliation Paysite Cash Considérations sur les systèmes d affiliation Configuration de l affiliation : Paramètres généraux Configuration de l affiliation : % personnalisés par affilié Paramètres d entrée sur la page de paiement Paramètres communs Options pour les abonnements Option pour les offres d essai (trial) Désactiver un ou plusieurs réseaux bancaires Option pour CB

2 3.6. Code erreur en mode debug Paramètres de retour sur les urls transaction ok / nok Paramètres de retour sur l url de confirmation Paramètres communs Options pour les abonnements Exemples de variables renvoyées Alertes de paiement Paramétrage de l url d alertes de paiement Données contenues dans le message d alerte de paiement Explication des codes d alerte Transactions de test Option de mise en attente Gestion à distance via l utilisation des APIs Paysite Cash Validation/Suppression distante de transaction Remboursement distant de transaction Récupération de l état d une transaction à distance Annulation distante d abonnement Modification distante d abonnement Récupération de l état d un abonnement à distance Comment utiliser le système de manière sécurisée Paramétrage et installation de l Open Members Agent Installation Configuration Page de choix des abonnements Accès distant aux statistiques Stats affiliés Stats webmasters

3 Par respect pour l environemment, merci de n imprimer ce document qu en cas de nécessité. 3

4 1. Configuration des paramètres du site dans votre interface commerçant Si vous souhaitez récupérer les informations de transaction CB dans votre base de données locale, spécifier des comportements de retour différents suivant les paramètres de retour d une transaction ou encore que Paysite Cash gère vos membres (abonnements), suivez les procédures décrites plus bas (chapitres 4 à 13) Configuration générale du site Id site : le numéro identifiant votre site dans notre plateforme. Notez le bien, vous devrez l utiliser pour chaque utilisation de notre plateforme (appel de page de paiement, appel d API, lien vers la page de support, configuration de modules Paysite-Cash dans boutiques en ligne, configuration d agent, etc ). Mode test : Si le mode test est actif alors les transactions de test (test=1 dans l url) seront considérées comme valides et traitées comme telles, donc confirmées par url avec gestion des utilisateurs. Url référante : elle indique à notre plateforme de quel domaine les transactions financières proviennent pour le site en question. Elle empêche le passage de transactions depuis un autre domaine. Généralement identique à l url principale du site. Vous pouvez si vous le souhaitez spécifier plusieurs url référantes pour un même site, séparées par un point-virgule («;») Url de retour après paiement : Entrer au besoin l url vers laquelle sera automatiquement redirigé le client lorsque son paiement est en attente bancaire. Attention le retour sur cette url ne veut pas dire que le paiement est accepté mais simplement qu il a été traité par la plateforme Paysite Cash (voir chapitre 4) (vous pouvez par ex faire un test sur cette page sur le statut de la transaction - refusé ou accepté - et décider du message affiché en fonction de la réponse de la plateforme). Url de retour après paiement annulé : Entrer au besoin l url sur laquelle sera automatiquement redirigé un client ayant annulé son paiement en cliquant sur le bouton «annuler» (voir chapitre 4). Url de confirmation backoffice : Entrer au besoin (si vous voulez enregistrer ou traiter localement vos transactions CB) l url vers laquelle les informations de transaction seront envoyées par POST. En cas de non réponse de cette url, la plateforme Paysite Cash réessayera ultérieurement. Attention : mettre l adresse complète du fichier (ex : Nom d utilisateur et mot de passe de l url de confirmation : Il est vivement conseillé de sécuriser votre url backoffice via un.htaccess et.htpasswd. Vous pouvez indiquer ici le nom d utilisateur et le mot de passe correspondant le cas échéant. Url zone membres : Utilisée à titre indicatif, n affecte pas le fonctionnement de votre site. Autoriser non cohérence pays CB / Pays IP : Cette option vous permet d agir sur l algorithme de vérification de cohérence. Si vous sélectionnez «non», vous n allez accepter que les transactions réalisées par un client qui se trouve dans son propre pays. A utiliser lorsque l on travaille avec des pays a risques. Autoriser les fre s : Cette option vous permet d agir sur l algorithme de vérification antifraude. Il peut s avérer utile de refuser les fre s pour réduire les tentatives de fraudes. Autoriser les multi abonnements : Cette option permet d empêcher un client de s abonner plusieurs fois avec le même ou le même numéro de CB. Dans le cas d utilisation de l agent de gestion de membres, cette option n affecte que les numéros de CB car le test de l adresse est réalisé par défaut et il est impossible de prendre plus d un abonnement avec le même . Sans utilisation de l agent, cette option s applique sur les numéros de CB et les s. Par défaut les multi-abonnements ne sont pas autorisés. Vous pouvez les autoriser dans des cas précis où le client a la possibilité de souscrire à plusieurs abonnements différents sur le même site. Langues : Vous devez sélectionner au moins une des langues disponibles dans la liste.

5 Clef APIs : Cette clé est une clé unique vous permettant d utiliser nos différentes APIs de manière sécurisée. Elle vous permet d être reconnu par notre plateforme lors des appels à nos différentes APIs. Voir le chapitre 9 pour l utilisation de nos APIS. Inscription SMS mailing : pour les sites ayant la vérification par SMS activée (voir dans les options de vérification SMS), vous pouvez choisir d enregistrer les numéros de téléphones récoltés pour la vérification SMS dans votre compte paysite-cash et vous en servir pour communiquer avec votre client par la suite. Ceci suppose que le client a donné son accord au préalable, en cochant la case sur la page de paiement Configuration liste noire des pays Dans cette section, vous pouvez choisir les pays pour lesquels vous voulez accepter ou refuser les transactions. Le pays est détecté à partir de l adresse IP et non des paramètres régionaux configurés sur l ordinateur de l utilisateur Configuration liste noire des porteurs Dans cette section, vous pouvez ajouter les adresses des porteurs pour lesquels vous voulez refuser les transactions. Lorsque qu un porteur essayera de payer sur votre site avec une adresse listée ici, le paiement lui sera refusé Générateur d'url de paiement Le générateur d url vous permet de générer facilement le code des boutons Paysite-Cash à insérer sur votre site en remplissant un formulaire. Son utilisation est relativement simple : Montant : entrez le montant correspondant au bouton que vous voulez créer. Montant2 : entrez le montant que vous souhaitez prélever in fine dans le cas d un abonnement avec période d essai. Le «Montant» décrit ci-dessus désigne alors dans ce cas le montant du premier prélèvement pour la période d essai. Langue : choisissez la langue par défaut qui sera affichée au client. Vous pouvez en dessous choisir de forcer la langue sélectionnée ou de permettre au client d afficher la langue de son choix, suivant ses paramètres régionaux. Abonnement : cocher dans le cas ou le paiement concerne un abonnement ;. nb de prélèvements au total : nombre de prélèvements prévus incluant le premier (exemple dans le cas d un abonnement de 6 mois avec prélèvement mensuel : 6).. Période : période séparant chaque prélèvement. Dans le cas où vous désirez proposer une période d essai, ce paramètre désigne la durée de la période d essai.. Période2 : dans le cas où vous désirez proposer une période d essai, et si celle-ci est d une longueur différente à la période normale, ce paramètre indique la période qui séparera chacun des prélèvements suivant la période d essai. Mode test : cochez si vous désirez effectuer des paiements de test avec le bouton que vous allez créer. Remarque : dans ce cas, vous devrez recréer un bouton avec cette option non-cochée pour le passage en production et l usage réel. Champ divers : entrez ici des informations additionnelles que vous désirez transmettre lors d un paiement (identifiant interne, commentaire, etc ). Laissez vide dans le cas où vous désirez spécifier un numéro d affilié (voir ci-dessous). Id affilié Paysite Cash : entrez ici le numéro d affilié spécifique au bouton que vous voulez créer le cas échéant. Ce numéro étant stocké dans le champ divers, vous devez laisser ce dernier vide dans le cas où vous souhaitez spécifier un numéro d affilié.

6 GO! : La validation du formulaire vous affiche une nouvelle page contenant deux parties : - La partie haute vous affiche le code et vous permet de le copier/coller directement dans votre page html - La partie basse vous donne un aperçu de l aspect du bouton ainsi que des textes et liens ajoutés au dessus et en dessous dans le code. NB : Cet outil permet la création simple de bouton Paysite-Cash et n est pas prévu pour une utilisation avancée. Pour tirer partie au mieux des options avancées offertes par la plateforme Paysite-Cash, veuillez vous reporter aux chapitres concernées (3 à 5) Configuration options Agent OpenMembers NB : Cette partie ne concerne que les commerçants utilisant notre agent de gestion des membres.!!! Attention : l agent doit avoir été préalablement installé et configuré!!! Url de l agent : Url à laquelle est installé l agent (complète, avec «/index.php» à la fin). Nom d utilisateur et mot de passe de l agent : Ces informations ont été saisies à l installation de l agent. Clé secrète : Cette information a été saisie à l installation de l agent. Htacces, liste d IPs d autorisées sans authentification : Entrer ici les adresses IP/réseaux à autoriser pour des accès kits par exemple (une adresse IP par ligne). Htpasswd, import de membres existants : Si vous avez déjà des membres, entrez ici les données de votre.htpasswd au format : «user:pass_crypté». Réécriture journalière du htpasswd : Activé par défaut. Cela permet une réécriture «saine» complète du htpasswd tous les jours à partir de la liste des membres actifs. Dans le cas où vous utilisez un autre système de paiement CB qui accèderait au même fichier.htpasswd, vous ne devez surtout pas activer cette option. NB : Comme indiqué dans la partie précédente, vous avez à disposition dans votre espace éditeur un générateur d url. Dans le cas où vous utilisez l agent CB pour la gestion des users/pass il faut impérativement utiliser ce générateur car en mode abonnement une clef (&key=) est ajoutée pour éviter les modifications de prix et autre par url Configuration des mails de confirmation des abonnements NB : Cette partie ne concerne que les sites pour lesquels les écritures de nom d utilisateur/mot de passe sont gérées directement par la plateforme Paysite Cash via l agent CB. Format s : normal ou html. En mode html, les mails doivent contenir les balises html. Si vous voulez insérer des images, elles doivent être appelées avec leur adresse complète, ex : début abonnement : Oui / Non. Envoie un mail lors d un nouvel abonnement en se basant sur le contenu inséré dans «Message début». fin abonnement : Oui / Non. Envoie un mail lors de la fin d un abonnement en se basant sur le contenu inséré dans «Message fin». Url de la zone client : Utilisez cette url dans les mails de confirmation afin que les membres puissent se désabonner et réinitialiser leur mot de passe.

7 L url est la suivante : (XXXX devant être remplacé par le numéro du site). Message début : Entrez ici le texte que vous désirez envoyer au client pour confirmer sa souscription à votre abonnement. Utilisez les balises : <#username#> et <#password#> qui seront remplacées lors de l envoi du mail par le nom d utilisateur et le mot de passe du client. Message fin : Entrez ici le texte que vous souhaitez envoyer au client pour lui confirmer la désactivation de son compte le cas échéant. Remarque : la plate forme Paysite Cash réassignera automatiquement une vente à l affilié initial si le client se réabonne. Remarque : vous avez la possibilité d envoyer les messages dans plusieurs langues différentes. Ce choix dépend des langues que vous avez activées pour votre site : vous devez impérativement avoir enregistré un texte pour les messages de début et de fin dans chacune des langues que vous avez activées dans la configuration générale du site concerné Configuration graphique des pages de paiement Les choix de couleurs et polices sont globaux (page CB, page de retour après transaction et zone support clients). Vous avez aussi la possibilité de changer le logo «paiement sécurisé Paysite-Cash» en haut à gauche par votre propre image à uploader dans le champ prévu à cet effet juste en dessous (vous pouvez par ailleurs mettre des images différentes suivant la langue choisie par l utilisateur). Vous avez la possibilité de personnaliser encore plus la page de paiement et la page de support client en encapsulant notre page entre une entête et un pied de page (header/footer). Vous pouvez utilisez les variables divers et id_client que vous envoyez à la page de paiement en ajoutant dans l'en-tête ou le pied de page les tags : pour divers: <# divers #> pour id_client <# id_client #> Si dans vos codes html header et footer il y a des images, ces dernières doivent être uploadées sur le serveur Paysite Cash et appelées via SSL sinon une erreur de sécurité pouvant déconcerter les clients se produirait (voir ci-dessous pour l upload des images). Les images doivent ensuite être appelées via l url suivante : X étant le numéro de votre site Marque blanche NB : Cette partie concerne les sites désirant utiliser un système de marque blanche : vous avez la possibilité d envoyer les paramètres de personnalisation directement dans l url d appel de la page de paiement. Ainsi vous pouvez si vous le voulez donner des couleurs différentes suivant par exemple le type de client qui va payer ou l endroit d où il vient. Les paramètres définis pour chaque site peuvent donc être déterminés par url (hors logo et header/ footer). Il faut les envoyer par GET uniquement de la manière suivante : &var=valeur. Liste de variables : font : nom de la police ou liste de polices séparées par une «,» et avec un urlencode. size : taille de la police avec px, ex 12px txtcolor : couleur du texte, ex #AAAAAA bgcolor : couleur de fond de la page, ex #BBBBBB title : couleur du texte dans les titres des tableaux, ex #CCCCCC

8 titlebg : couleur de fond des cellules titres des tableaux, ex #DDDDDD tablebg : couleur de fond du tableau principal, ex #EEEEEE alink : cf référence HTML avisited : cf référence HTML ahover : cf référence HTML aactive : cf référence HTML 1.9. Upload des images Vous pouvez ici uploader les images que vous souhaitez insérer dans vos pages personnalisées. Contactez notre administrateur pour créer le répertoire qui contiendra ces images avant de les uploader Gestion des abonnements Cette section permet de lister les abonnements actifs et inactifs, de supprimer les abonnements de test inactifs et d annuler des abonnements actifs. Remarque : un abonnement inactif est soit un abonnement terminé soit un abonnement non terminé qui à reçu une demande d annulation de prélèvement ou encore un abonnement avec 1 seul prélèvement au total Gestion des membres Cette section permet de lister les membres actifs (uniquement si vous utilisez notre agent de gestion des membres). Vous pouvez aussi réinitialiser les mots de passe. Vous avez la possibilité de créer des membres et de les supprimer, mais notez toutefois qu un membre manuellement crée a une durée illimitée et n est lié à aucun abonnement Files d attente Cette section permet de lister les files d attentes des confirmations des transactions et des gestions de nom d utilisateur/mot de passe. Cela permet notamment de visualiser s il y a des problèmes de communication avec le site et une fois les problèmes résolus de relancer les actions en file d attente afin de ne perdre aucune information Logs Cette section liste les logs de confirmations de transactions avec : chaîne envoyée et réponse de la page de confirmation du site (255 1 er caractères uniquement). A utiliser à des fins de débogage. 2. L affiliation Paysite Cash La plateforme Paysite Cash intègre un système d affiliation (publique et privée) avec paiement direct des affiliés. Ce chapitre va vous aider à en comprendre le fonctionnement Considérations sur les systèmes d affiliation Utilisation de l affiliation Paysite Cash Dans le cas ou vous voulez utiliser le système d affiliation Paysite Cash (affiliation activée pour votre site sur la plate forme), il vous suffit d encoder dans le champ divers la variable $partner (cf rubrique paramètres d entrée sur la page de paiement), le $partner envoyé doit être un id existant

9 d affilié sur la plate forme. Les montants à reverser aux affiliés sont calculés automatiquement et les statistiques sont disponibles directement dans les zones affilié et éditeur. Paysite Cash gère automatiquement l attribution d un identifiant affilié aux nouvelles ventes réalisées par un client revenant sur le site après sa première visite et ayant le même id_client ou . Le lien généré pour les affiliés est de la forme : Ce lien redirige automatiquement vers votre site en passant dans l url partner=x. Si vous souhaitez mettre en place des pages de ventes ou une marque blanche il vous faut configurer une page d outils de promotion personnalisés qui gèrent des liens du type : Ce lien redirigera sur la page toto.php de votre site en passant dans l url partner=x. Utilisation d un système d affiliation externe Normalement, avant chaque paiement, un utilisateur est créé dans la base de données locale. L identifiant affilié doit donc être assigné à ce moment la. Dans tous les cas le champ «divers» peut contenir des informations propres au système d affiliation et avec le format désiré lors de l envoi des paramètres de retour pour la confirmation backoffice, la plate forme Paysite Cash renvoie la variable «divers» sans la modifier (voir chapitre 5 dédié aux paramètres renvoyés sur l url backoffice) Configuration de l affiliation : Paramètres généraux NB : cette partie ne concerne que les commerçants utilisant le système d affiliation Paysite Cash. Lien inscription/activation affiliés : insérez ce lien directement dans votre page web pour l enregistrement de vos affiliés. En cliquant sur ce lien, vos affiliés vont être invités soit à se créer un compte dans notre plateforme s ils n en ont pas encore, soit à se connecter avec leur compte affilié s ils ont déjà un compte, et ajoutera dans les deux cas votre site préconfiguré (avec les pourcentages par défaut que vous aurez spécifiés par exemple) à leur liste de sites. Sécurisation anti fraude affiliés : oui / non, vous permet de contrôler qu un affilié ne fraude pas en passant des transactions personnellement sur son compte par votre site. % par défaut des affiliés : vous permet de configurer le pourcentage par défaut des affiliés (pour l ajout de nouveaux affiliés par exemple, ce sera le pourcentage configuré automatiquement). Réinitialiser les % affiliés : cochez si vous souhaitez réinitialiser les pourcentages de TOUS vos affiliés (ne pas utiliser si vous souhaitez garder certaines exceptions, ou alors ne pas oublier de les spécifier séparément de nouveau). Vous pouvez dans les options suivantes paramétrer des outils personnalisés d affiliation (copie d écran de votre site, message personnalisé aux affiliés) Configuration de l affiliation : % personnalisés par affilié NB : cette partie ne concerne que les commerçants utilisant le système d affiliation Paysite Cash. Vous pouvez ici spécifier des pourcentages personnalisés par affilié et par site, si vous souhaitez proposer des offres d affiliation différentes selon vos affiliés. 3. Paramètres d entrée sur la page de paiement

10 Vous trouverez ci-dessous une liste exhaustive des paramètres que vous pouvez passer à la page de paiement, en GET, POST, url_encode etc ainsi que leur signification. L url de la page de paiement est la suivante : Ajouter chaque variable à l url, séparée par un &. Exemple : Vous pouvez aussi envoyer les variables par POST depuis un formulaire. Conseil : utilisez une page PHP sur votre site qui va réaliser un header («location: https//.»), de façon à ce que l url avec les paramètres de paiement soient cachés Paramètres communs (*) = paramètre obligatoire. site : numéro de site dans l interface commerçant Paysite Cash (*) (int) montant : prix à débiter (*) (float) devise : EUR, USD, CHF, CAD, GBP, LVL, EEK, LTL, RON (*) (varchar 3) divers : envoi d informations supplémentaires. (blob) Encoder les informations comme suit dans le champ divers : base64_encode("var1=".$var1."&var2=".$var2) ; Dans le cas d utilisation de l affiliation Paysite Cash, «partner=$id_affilié» doit être envoyé dans le champ divers encodé en base 64. Ex : <? $divers = base64_encode("partner=9999");?> test : si test = 1, toutes les transactions sont validées quel que soit le numéro de carte (0/1) (voir rubrique sur les transactions de test) id_client : identifiant client de votre client (nombre entier) (int 4) ref : votre référence interne unique pour chaque transaction (varchar 50) du client (varchar 255) lang : langue de la page, fr ou us. Si vide, auto détection (char 2) wait : option de mise en attente des transactions. Si wait = 1, La transaction doit être validée dans l admin ou via l API de validation distante des transactions (voir plus bas) (0/1) debug : option d affichage des erreurs sans redirection sur la page de retour après paiement NOK voir utilisation plus bas (0/1) nocurrencies : permet de ne pas afficher le choix de changement de devise, envoyer yes comme valeur pour désactiver l'option. Par défaut si la variable n'est pas ajoutée l'option de choix de changement de devise est activée. (yes/no) description : description du produit/service qui apparaîtra sur la page de paiementas (varchar 255)

11 3.2. Options pour les abonnements subscription : si subscription = 1, défini que c est un abonnement (*)(0/1) periode : nombre de jours ou mois entre les prélèvements suivi de «j» pour jours «m» pour mois (*)(varchar 6) Ex : 10j = 10 jours, 10m= 10 mois nb_redebit : nombre total de prélèvements (inclus le 1 er ), entre 1 et x pour illimité (*) (tinyint 4) user : nom d utilisateur souhaité pour le membre (varchar 50) Si vide en mode abonnement et si vous avez configuré l agent de gestion des membres, un nom d utilisateur et un mot de passe sont générés de manière unique par le système. pass : mot de passe souhaité pour le membre (varchar 50) Si vide et si le nom d utilisateur est défini, un mot de passe est généré par le système. Dans les 2 cas le membre reçoit une confirmation par de son nom d utilisateur/mot de passe. Attention, en mode abonnement et lorsque le site utilise l agent de gestion de membres, l adresse dans le champ doit impérativement être envoyée à la page de paiement, une vérification d unicité dans la base des membres du site est réalisée Option pour les offres d essai (trial) Une offre d essai est une offre ou le prix et/ou la durée du «rebill» in fine est différent du prix/période de l abonnement initial. Ex : abonnement avec offre d essai de 3 jours pour 3 facturé par la suite à 29 tous les mois. Pour cela il faut utiliser les paramètres suivants : periode2 : nombre de jours au mois entres les prélèvements qui suivent la période d essai initiale définie dans ce cas par «periode». Attention : Si vous renseignez periode2, vous devez impérativement renseigner aussi montant2, même si sa valeur est identique à celle de montant. montant2 : montant des prélèvements qui suivront la période d essai initiale dont le prix est fixé par «montant». Attention : «montant2» ne peux pas dépasser 50 fois «montant» Désactiver un ou plusieurs réseaux bancaires Par défaut le commerçant a la possibilité d accepter tous les réseaux bancaires, par exemple: amex, visa, mc, jcb. Si Vous avez besoin de désactiver l un ou l autre réseau bancaire, il faut utiliser une des variables suivantes: no_amex: pour désactiver les cartes amex. no_visa: no_mc: no_jcb: pour désactiver les cartes visa. pour désactiver les cartes mc. pour désactiver les cartes jcb.

12 E.g.: no_visa=1 signifie que le commerçcant a désactivé les cartes visa pour cette transaction, or no_visa=1&no_mc=1 pour désactiver les deux, les cartes visa et mc Option pour CB30 Si votre site a l option CB30 activée vous pouvez utiliser cette fonctionnalité en envoyant la variable author: 1 Cette option n est pas activée pour le site par défaut Code erreur en mode debug error wrong subscription parameters (rebill periode) : le champ periode2 ou nb_redebit est mal défini. error wrong subscription parameters (on trials minimum of 2 bills) : il faut au minimum 2 prélèvements sur une offre d essai. error wrong subscription parameters (signup periode) : le champ periode ou nb_redebit est mal défini. empty site id : champ site non défini. error referer : le referer détecté n est pas celui défini dans le profil du site. test transactions only : le site n est pas activé pour passer des transactions réelles. no language activated for site : aucune langue n a été activée pour le site. error mauvais format d . error empty currency : champ devise non envoyé. wrong currency : champ devise incorrect. error empty amount : champ montant non envoyé. error price out of range : le prix est hors des limites fixées dans le profil du site. error rebill price out of range regarding to signup price : le prix du rebill ne peut être au maximum que 20 fois supérieur au prix de l offre d essai. error empty for subcription with remote agent : lorsque l agent est utilisé, l doit impérativement être envoyé sur la page de paiement. error user or already exists in members table : un membre existe déjà pour le site avec le nom d utilisateur ou l envoyé. error already exists in members table : un membre existe déjà pour le site avec l envoyé. 4. Paramètres de retour sur les urls transaction ok / nok Si vous avez paramétré une url de retour après paiement ok et/ou nok, les paramètres suivants vous sont renvoyés par GET : id_trans : identifiant unique généré par la plate pour la transaction concernée id_client : votre id_client envoyé sur la page de paiement

13 divers : votre champ divers envoyé sur la page de paiement langue : FR, US, ES, DE, IT correspondant au choix de langue effectué par le client sur la page de paiement ref : votre référence interne envoyée sur la page de paiement wait : "1" est renvoyé si la transaction est en attente validation manuelle NB : les url de retour ne doivent pas être utilisées à des fins de traitement des données!! Leur unique but est de permettre au webmaster de contrôler et faciliter la navigation du client. Elles ne sont pas prévues pour le traitement des transactions en backoffice, vous devez pour cette partie utiliser l url de confirmation backoffice dont l utilisation est décrite ci-dessous. 5. Paramètres de retour sur l url de confirmation Si vous avez paramétré une url confirmation backoffice, les paramètres suivants vous sont renvoyés par POST : 5.1. Paramètres communs test : = 1 si il s agit d une transaction de test countrycode : renvoie le code pays de la carte bancaire au format ISO (2 caractères). id_trans : identifiant unique généré par la plate forme pour la transaction concernée : XXXXXXXXX XXXXXXXXXc XXXXXXXXXr XXXXXXXXXi // cas normal // annulation // remboursement // contestation ref : votre référence interne envoyée sur la page de paiement langue : choix de langue effectué par le client sur la page de paiement (FR, US, ES, DE, IT) montant : montant du débit effectif montant_org : montant dans la devise choisie par le client sur la page de paiement montant_sent : montant envoyé par le commerçant à la page de paiement devise : devise du débit effectif (EUR uniquement pour le moment) devise_org : devise choisie par le client sur la page de paiement (EUR, USD, CAD, GBP, CHF, LVL, EEK, LTL, RON) devise_sent : devise envoyée par le commerçant à la page de paiement (EUR, USD, CHF, CAD, GBP, LVL, EEK, LTL, RON) id_client : votre id_client envoyé sur la page de paiement du client divers : votre champs divers envoyé sur la page de paiement ip : adresse IP du client id_phone : id du numéro de téléphone utilisé pour la vérification SMS

14 sms_mailing : (yes/no) indique si le client a donné son accord sur la page de paiement pour l utilisation de son numéro de téléphone time : timestamp de la transaction type : 0 - transaction unique 1 - abonnement (prélèvement initial) 2 - abonnement (prélèvements suivants) 3 - fin d abonnement (dans ce cas, on a toujours etat = end) etat : ok - transaction acceptée ko - transaction refusée wait transaction en attente de validation end - fin d abonnement refund - remboursement chargeback contestation 5.2. Options pour les abonnements nb_redebit : nombre prélèvements au total (inclus le 1 er ) periode : période entre les prélèvements num_abo : numéro de l abonnement next_rebill_time : Timestamp, envoyé si la transaction est un abonnement ou un réabonnement, représente la date du prochain réabonnement. subscription_end_time : Timestamp, envoyé si la transaction est annulée, représente la date de fin d abonnement. Remarques : Les confirmations de fin d abonnement sont envoyées au moment où le membre ou l admin annule l abonnement et non à la fin effective de la période d abonnement (dans le cas d un abonnement avec 1 seul prélèvement la confirmation de fin est envoyée en même temps que le signup). Par contre la gestion de nom d utilisateur/mot de passe via l agent de gestion des membres prend en compte la fin de période pour supprimer le membre. Cas particulier des remboursements (refund) et impayés (chargeback) : Ils sont aussi confirmés sur l url backoffice de la manière suivante : La transaction initiale est repostée à l identique avec ajouté à l id_trans «r» pour un remboursement ou «i» pour un impayé, la variable etat prend comme valeur respectivement : «refund» ou «chargeback» et pour finir la variable time contient le timestamp à la création du remboursement ou de l impayé Exemples de variables renvoyées Voici quelques exemples de variables envoyées à votre url de confirmation backoffice : Transaction simple acceptée (prise comme base de comparaison pour les suivantes) : site=9999&id_trans=psc &ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_org

15 =50&devise_org=EUR&montant_sent=50&devise_sent=EUR&id_client=3333& =tot pe=0&binmatch=0&fre =0&anonymousproxy=0&score=0&proxyscore=0&spamscore= 0&etat=ok&divers=2fd433b3e1f224fa385b650478daa633&cc_num=5130XXXXXXXXXX99&c c_whitelist=no&sms_confirmed=no&author=0 Transaction simple refusée : site=9999&id_trans=psc &ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_org =50&devise_org=EUR&montant_sent=50&devise_sent=EUR&id_client=3333& =tot o@lulu.com&lname=holmes&fname=sherlock&ip= &time= &ty pe=0&binmatch=0&fre =0&anonymousproxy=0&score=0&proxyscore=0&spamscore= 0&etat=ko&divers=2fd433b3e1f224fa385b650478daa633&cc_num=5130XXXXXXXXXX99&c c_whitelist=no&sms_confirmed=no&author=0 Transaction simple en attente de validation manuelle du commerçant : site=9999&id_trans=psc &ref=22222&langue=fr&countrycode= &montant=50&devise=eur&montant_org=50&devise_org=eur&montant_sent=50&devise _sent=eur&id_client=3333& =toto@lulu.com&lname=holmes&fname=sherlock&ip = &time= &type=0&binMatch=0&fre =0&anonymousProxy =0&score=0&proxyScore=0&spamScore=0&etat=wait&divers=2fd433b3e1f224fa385b daa633&cc_num=5130XXXXXXXXXX99&cc_whitelist=no&sms_confirmed=no&author=0 Notez que le countrycode est vide dans ce cas car l information n a pas encore été récupérée (elle n est récupérée que lorsque la transaction est traitée). Transaction simple remboursée : site=9999&id_trans=psc r&ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_or g=50&devise_org=eur&montant_sent=50&devise_sent=eur&id_client=3333& =to to@lulu.com&lname=holmes&fname=sherlock&ip= &time= &t ype=0&binmatch=0&fre =0&anonymousproxy=0&score=0&proxyscore=0&spamscore =0&etat=refund&divers=2fd433b3e1f224fa385b650478daa633&cc_num=5130XXXXXXXXXX 99&cc_whitelist=no&sms_confirmed=no&author=0 Transaction simple contestée : site=9999&id_trans=psc i&ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_org =50&devise_org=EUR&montant_sent=50&devise_sent=EUR&id_client=3333& =tot o@lulu.com&lname=holmes&fname=sherlock&ip= &time= &ty pe=0&binmatch=0&fre =0&anonymousproxy=0&score=0&proxyscore=0&spamscore= 0&etat=chargeback&divers=2fd433b3e1f224fa385b650478daa633&cc_num=5130XXXXXXX XXX99&cc_whitelist=no&sms_confirmed=no&author=0 Début d abonnement : site=9999&id_trans=psc &ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_org =50&devise_org=EUR&montant_sent=50&devise_sent=EUR&montant2=100&montant2_org =100&id_client=3333& =toto@lulu.com&lname=holmes&fname=sherlock&ip= &time= &nb_redebit=10&periode=1m&periode2=1m&num_abo=46900 &type=1&binmatch=0&fre =0&anonymousproxy=0&score=0&proxyscore=0&spamsco re=0&etat=ok&divers=2fd433b3e1f224fa385b650478daa633&cc_num=5130xxxxxxxxxx9 9&cc_whitelist=no&sms_confirmed=no&author=0&next_rebill_time= re-débit sur abonnement :

16 site=9999&id_trans=psc &ref=22222&langue=fr&countryCode=FR&montant=50&devise=EUR&montant_org =50&devise_org=EUR&montant_sent=50&devise_sent=EUR&id_client=3333& =tot _redebit=9&num_abo=46900&type=2&binmatch=0&fre =0&anonymousproxy=0&score =0&proxyScore=0&spamScore=0&etat=ok&divers=2fd433b3e1f224fa385b650478daa633 &cc_num=5130xxxxxxxxxx99&cc_whitelist=no&sms_confirmed=no&author=0&next_reb ill_time= Notez la mise à jour de nb_redebit en fonction du nombre de re-débits restant. Fin d abonnement : site=9999&id_trans=psc &ref=22222&langue=fr&countryCode=FR&id_client=3333& =toto@lulu.co m&lname=holmes&fname=sherlock&ip= &time= &num_abo=469 00&type=3&etat=end&divers=2fd433b3e1f224fa385b650478daa633&cc_num=&cc_white list=no&sms_confirmed=no&author=0&subscription_end_time= Notez que le numéro de carte n est pas renvoyé dans ce cas. Il y a beaucoup de variations possibles suivant les options configurées pour votre site et suivant les paramètres de la transaction, mais ces cas sont les plus généralement rencontrés et vous pouvez sans problème vous baser sur ceux-ci pour le codage de votre script backoffice. 6. Alertes de paiement 6.1. Paramétrage de l url d alertes de paiement L url peut être paramétrée dans l interface éditeur, dans la configuration générale du site : «confirmation backoffice des alertes». Une fois l url configurée, vous recevrez les alertes de paiement Données contenues dans le message d alerte de paiement Dans l alerte de paiement vous trouverez les données suivantes : site : le numéro du site dans l interface éditeur Paysite Cash id_trans : numéro de transaction unique généré par la plateforme du client data : vos valeurs, envoyées depuis le champs divers de la page paiement. Ref : votre référence interne unique error_code : code d alerte 6.3. Explication des codes d alerte 1 - le total dépasse 1000 EUR. 2 - l utilisateur à déjà effectué sur le site une transaction dont le paiement à été accepté. 3 - d autres paiements ont été effectués avec le même et une autre carte bancaire. 4 - l utilisateur à déjà effectué des impayés.

17 5 - utilisation de la carte par un tiers. 6 contenant le ticket de transaction non reçu par le porteur de carte. 7. Transactions de test Pour réaliser des transactions de test, il faut ajouter le paramètre "test=1" dans l url d appel de la page de paiement. Par défaut la transaction est validée (remplir tous les champs avec des informations factices, sauf l adresse qui doit être valide qui est vérifiée même en mode test). Pour simuler un paiement refusé, le numéro de carte bancaire à utiliser est : Exemple de remplissage de formulaire pour transaction de test (validée) : Type de carte : Visa Numéro de carte : Date de validité de la carte : Mois : 05 Année : 2025 Code CVV2 : 123 Nom sur la carte : azerty Prénom sur la carte : azerty Pays de la banque émettrice : France Adresse votre- @votre-domain.com 8. Option de mise en attente Dans certains cas vous pouvez avoir besoin de valider les paiements un par un. Pour que les transactions soient mises en attente vous devez ajouter dans l url le paramètre "wait=1". Lorsqu une transaction en attente est soumise par le client vous recevez sur l url de confirmation backoffice (si cette dernière a été configurée pour le site) les mêmes paramètres que pour une transaction valide mais avec "etat=wait". Vous alors avez la possibilité de valider la transaction pour en lancer le traitement ou bien de l annuler depuis votre interface éditeur Paysite Cash, ou bien d effectuer ces traitements à distance, en utilisant nos API (voir ci-dessous) 9. Gestion à distance via l utilisation des APIs Paysite Cash Si votre interface éditeur vous permet de gérer tout ce qui concerne la plateforme Paysite Cash pour votre(vos) site(s), vous pouvez aussi effectuer nombre d opérations sur ces transactions à distance, en appelant les APIs Paysite Cash. Vous trouverez ci-dessous une liste des APIs les plus couramment utilisées avec le détail de leur utilisation. Pour une utilisation extensive des APIs Paysite Cash, reportez-vous à la documentation spécifique aux APIs. L utilisation de toutes les APIs Paysite Cash nécessite une clé (champ Key à envoyer dans l url) que vous trouverez dans votre interface éditeur, section «configuration générale du site» Validation/Suppression distante de transaction Vous pouvez valider une transaction à distance en utilisant l url suivante : De la même manière, vous pouvez supprimer une transaction à distance en utilisant l url suivante : X : id de votre site Y : clé API spécifiée dans votre interface éditeur Z : id de la transaction au format PSC-****-**-****

18 9.2. Remboursement distant de transaction Vous avez la possibilité de rembourser une transaction à distance via l url suivante : X : id de votre site Y : clé API spécifiée dans votre interface éditeur Z : id de la transaction au format PSC-****-**-**** Si le remboursement a été effectué correctement, l API génère une transaction de remboursement avec l id_trans PSC-****-**-****r, envoie un mail de confirmation et une confirmation sur l url backoffice, et retourne "ok" Récupération de l état d une transaction à distance Vous avez la possibilité de récupérer l état d une transaction via l url suivante : X : id de votre site Y : clé API spécifiée dans votre interface éditeur Z : id de la transaction au format PSC-****-**-**** T : votre référence interne unique pour la transaction (Z et T sont au choix, vous pouvez vous contenter de l un des deux uniquement) Retourne une réponse du type : etat=ok&langue=fr&montant=12&devise=eur&id_client=0& =toto@toto.com&ip=xxx&type=1 &divers=xxx&vat= Annulation distante d abonnement Lorsque vous utilisez une application tierce de gestion de zone membre comme PHPMembers, vous pouvez piloter la gestion de fin d abonnement par url. Il faut envoyer une requête http sur l url suivante : X : id de votre site Y : clé API spécifiée dans votre interface éditeur Z : numéro d abonnement indiqué sur la confirmation automatique 9.5. Modification distante d abonnement Lorsque vous utilisez une application tierce de gestion de zone membre, vous pouvez générer une demande de modification du prix du rebill de l abonnement sans passer par votre interface éditeur. Il suffit d envoyer une requête http sur l url suivante : X : id du site Y : clé API spécifiée dans votre interface éditeur Z : numéro d abonnement confirmé sur la confirmation automatique T : nouveau montant pour le rebill (séparateur décimal «.» et non «,»)

19 Toute demande de modification génère une demande de confirmation au client avec une url à cliquer afin d éviter tout abus Récupération de l état d un abonnement à distance Comme pour les transactions, vous avez la possibilité de récupérer l état d un abonnement via l url suivante : X : id du site Y : clé API spécifiée dans votre interface éditeur Z : numéro d abonnement confirmé sur la confirmation automatique T : votre référence interne unique pour la transaction qui avait entraîné l abonnement U : de l abonné concerné (Z, T et U sont au choix, un seul suffit) Retourne une réponse du type : periode=3j&periode2=1m&numbills=4&active=yes&next_rebill_time= &id_client=0 &id_partner=999 (le next_rebill_time est sous la forme d un timestamp) 10. Comment utiliser le système de manière sécurisée Utilisez le champ divers pour faire un checksum des informations envoyées <?php $key = md5("secret_key".$id_client.$montant.$devise); $divers = base64_encode("key=".$key."&partner=".$partner);?> Votre code appelant l url de paiement sera donc de la forme : <a href= echo $divers;?> >lien</a> NB : Dans le cas d un abonnement, vous pouvez ajouter les informations relatives à l abonnement au champs divers. Ensuite dans le fichier de traitement des confirmations : <?php?> $divers = $_POST['divers']; Parse_str(base64_decode($divers)); $montant_org = $_POST['montant_org']; $devise_org = $_POST['devise_org']; $id_client = $_POST['id_client']; $keynew = md5("secret_key".$id_client.$montant_org.$devise_org); if($keynew!= $key) {Die('cheat');} Ainsi si une des valeurs id_client, montant ou devise à été modifiée, la clef n est pas bonne et vous pouvez donc invalider la transaction.

20 11. Paramétrage et installation de l Open Members Agent Paysite Cash met à votre disposition son Open Members Agent qui permet à la plateforme Paysite Cash de gérer pour vous votre zone membre (ajout / suppression de membres). Voici comment l installer sur votre serveur et comment le configurer dans votre espace éditeur (voir la documentation spécifique pour plus de détails) Installation Téléchargez le fichier zip dans notre centre de support ( et décompressez-le. Uploadez ensuite les dossiers et les fichiers à la racine de votre site. Les fichiers de l agent sont logiquement dans le répertoire /agent. Effectuez un CHMOD 777 sur le répertoire /agent et /members, vous pouvez renommer /members à votre convenance, suivant le nom du répertoire contenant votre zone membre Configuration Lancez l url de l agent : Cliquez sur Configuration, voici les informations à remplir : Full disk path to agent script dir : chemin complet où est installé le script de l agent, normalement pré détecté. Full disk path to members dir : chemin complet où est installée la zone membre, normalement pré détecté si le répertoire zone membre est /members, n oubliez pas de corriger sinon. Full disk path to htpasswd dir : chemin complet où est stocké le fichier htpasswd de mots de passe, par défaut le répertoire /members. Pour des raisons de sécurité vous pouvez le déplacer à votre convenance. Attention : si PHP fonctionne en safe mode, l agent ne pourra pas écrire hors du wwwroot. Htpasswd file name : nom du fichier de mots de passe, par défaut :.htpasswd. Site name : nom du site qui apparaîtra dans l invite de saisie de mot de passe. Secure key : chaîne de caractères de votre choix qui servira pour communiquer avec la plateforme. Ip source 1 : Ip source 2 : Url autorization 401 required : url vers laquelle vous voulez que soient redirigées les erreurs d authentification (facultatif). Username : nom d utilisateur de l agent, évitez les chaînes simples ou courtes. Password : mot de passe de l agent, évitez les chaînes simples ou courtes. NB : Si vous utilisez l agent de gestion des membres, c est la plate forme Paysite Cash qui envoie les mails de confirmation et qui gère les problèmes de mots de passe perdus. 12. Page de choix des abonnements Vous trouverez sur le forum un modèle à jour de page php permettant la saisie parmi les options d abonnements que vous souhaitez ainsi que l adresse du client. A utiliser avec l agent Open Members.