Plateforme Systempay Correspondance entre SP PLUS et SYSTEMPAY Paiement Simple et en plusieurs fois
Rédaction, Vérification, Approbation Rédaction Vérification Approbation Nom Date/Visa Nom Date/Visa Nom Date/Visa Lyra-Network 21/12/2010 Lyra-Network 21/12/2010 Lyra-Network 21/12/2010 Historique du document Version Auteur Date Commentaires 1.0 Lyra-Network 23/09/2009 Création du document Confidentialité Toutes les informations contenues dans ce document sont considérées comme confidentielles. L utilisation de celles-ci en dehors du cadre de cette consultation ou la divulgation à des personnes extérieures est soumise à l approbation préalable de Lyra Network.
SOMMAIRE 1. Objectif...4 2. CGI ou KIT marchand SP PLUS...4 3. Principe Général Systempay...4 4. URL de la page de paiement...4 5. Correspondance des champs...5 5.1: Champ version... 5 5.2: Champ siret... 5 5.3: Champ montant... 5 5.4: Champ devise... 6 5.5: Champ langue... 6 5.6: Champ référence... 7 5.7: Champ moyen... 7 5.8: Champ modalité... 8 5.9: Champ valauto... 9 5.10: Champ dat1... 10 5.11: Champ email :... 10 5.12: Champ urlretour... 11 5.13: Champ arg1, arg2, arg3... 12 5.14: Champ hmac... 12 5.15: Champ méthode... 13 5.16: Champ taxe :... 13 5.17: Champ validite... 13 6. Paramètres supplémentaires obligatoires pour Systempay...14 7. URL de notification complémentaire...14 7.1: Appel URL Serveur... 14 7.2: Appel URL Serveur Etendu... 15 7.3: Appel de l'url serveur pour les transactions annulées ou abandonnées... 15 7.4: Analyse des paramètres retournés dans l URL Serveur... 15 8. Statut de la transaction et URL serveur...16 9. ASSISTANCE TECHNIQUE...16
1. Objectif Cette documentation s adresse à tous les commerçants ayant une boutique intégrant la solution de paiement SPPLUS et qui sont en cours de migration vers la solution de paiement Systempay. Cette documentation décrit la correspondance des champs entre les deux solutions. Cependant, la lecture du guide de démarrage de votre nouvelle offre est un pré-requis à la bonne compréhension de ce document. 2. CGI ou KIT marchand SP PLUS La différence fondamentale dans la mise œuvre de SYSTEMPAY, c est qu il n y a pas de CGI à installer sur votre serveur. La solution SYSTEMPAY, basée sur un POST de formulaire en https, est donc compatible quel que soit l environnement d hébergement de votre boutique en ligne et ne demande aucun droit spécifique à votre hébergeur. 3. Principe Général Systempay BOUTIQUE Etape 1: Formulaire de paiement (https) Envoi de paramètres en mode POST SYSTEMPAY Etape 2: Appel Url serveur Envoi de paramètres en mode POST Etape 3: Retour à la boutique à l initiative de l internaute Envoi de paramètre selon le mode défini dans le formulaire de paiement envoyé lors de la demande de paiement 4. URL de la page de paiement SPPLUS URL PAGE DE PAIEMENT SYSTEMPAY https://www.spplus.net/paiement/init.do https://paiement.systempay.fr/vads-payment/ Vous devez envoyer un formulaire https en mode POST vers l url de la page de paiement. Les paramètres POST sont composés de paramètres commençant par vads_ et du paramètre signature. Installation du module de paiement Systempay pour Magento Lyra Network- 4/16
5. Correspondance des champs 5.1: Champ version version vads_version Valeur à coder: V2 Paramètre obligatoire pour systempay Il doit être valorisé et transmis à V2 Pour passer de SSPLUS à Systempay, vous devez remplacer la valeur 1 par V2 5.2: Champ siret siret vads_site_id 8 chiffres Le champ siret présent dans la solution SPPLUS trouve son équivalence dans le champ identifiant boutique appelé site_id dans la solution de paiement SYSTEMPAY. La différence fondamentale entre SPPLUS et Systempay est que Systempay permet d avoir plusieurs boutiques (paramètre vads_site_id) sous le même Siret. Paramètre obligatoire pour systempay : Ce paramètre a été attribué lors de l'inscription à la plateforme de paiement. Sa valeur est consultable depuis l outil de gestion de caisse dans l onglet «Paramétrages» / «Boutique» par toutes les personnes habilitées. 5.3: Champ montant montant vads_amount Montant en cts pour Euro Ex :10056 pour 100,56 euros Paramètre obligatoire pour systempay Contrairement à SPPLUS, Systempay attend un montant exprimé dans la plus petite unité de la devise (en centimes pour la devise euro), sans présence de. [point] ou de, [virgule]. Ce format permet de traiter les devises sans centime (YEN, Franc Pacifique, etc) Exemple : pour un montant de 100,56 euros le champ vads_amount envoyé dans le formulaire de paiement doit être valorisé à 10056 et non à 100,56. Vous devez multiplier pour l euro votre montant par 100 pour passer de SPPLUS à Systempay. Lyra Network- 5/16
5.4: Champ devise devise vads_currency 978 pour Euro Paramètre obligatoire pour systempay Ce Paramètre indique la monnaie à utiliser, selon la norme ISO 4217 (code numérique).http://www.iso.org/iso/support/currency_codes_list-1.htm Pour l Euro, la valeur est 978. Pas de différence entre SPPLUS et Systempay. 5.5: Champ langue langue vads_language Voir tableau ci dessous Paramètre facultatif pour Systempay. Ce paramètre précise la langue dans laquelle doit être affichée la page de paiement (norme ISO 639-1). Les langues possibles sont les suivantes : vads_language Codification ISO 639-1 Allemand de Anglais en Chinois zh Espagnol es Français fr Italien it Japonais jp Portugais pt Lyra Network- 6/16
5.6: Champ référence Compris entre reference vads_trans_id 000000 et 899999 Longueur 6 chiffres Paramètre obligatoire pour systempay. Il est constitué de 6 caractères numériques et doit être unique pour chaque transaction pour une boutique donnée au minimum sur la journée. Il est à la charge du site marchand de garantir cette unicité sur la journée. Il doit être impérativement compris entre 000000 et 899999. La tranche 900000 et 999999 est interdite. 5.7: Champ moyen moyen vads_payment_card Valeur conseillée : vide Paramètre facultatif pour Systempay. Il contient la liste des types des moyens de paiement à la disposition de l internaute, séparés par des " ;" [point-virgule]. Si la liste ne contient qu'un type de carte, la page de saisie des données du paiement sera directement présentée. Sinon la page de sélection des moyens de paiement sera affichée. Si ce paramètre est vide alors l ensemble des moyens de paiement défini dans l outil de gestion de caisse (back office commerçant) sera présenté en sélection. Par défaut la valeur VIDE est conseillée ou ne pas de poster le champ. Les différents réseaux possibles sont : Réseau de la carte Aurore Amex CB Eurocard / MasterCard Visa Maestro e-carte bleue Cofinoga Paypal Paypal SandBox (mode test) Paysafecard Valorisation payment_cards AURORE-MULTI AMEX CB MASTERCARD VISA MAESTRO E-CARTEBLEUE COFINOGA PAYPAL PAYPAL_SB PAYSAFECARD Lyra Network- 7/16
5.8: Champ modalité modalite = 1x vads_payment_config Valeur SINGLE modalite= 2x vads_payment_config Valeur:exemple MULTI:first=5000;count=2;period=30 modalité=3x vads_payment_config Valeur:exemple MULTI:first=5000;count=3;period=30 Dans le cas du paiement multiple les paramètres dat2, dat3, mnt2, mnt3, pourcentacpte, per liées à SP PLUS n ont pas d équivalence. Vous pouvez donc supprimer ces variables de votre code. Paramètre obligatoire pour systempay vads_payment_config Ce paramètre obligatoire indique le type du paiement : - SINGLE indique un paiement unitaire. - MULTI indique un paiement en plusieurs fois. Dans ce cas, le paramètre est constitué de la chaîne «MULTI:», suivi par des paires clés/valeurs séparées par des «;». Les paramètres sont les suivants : «first» indique le montant du premier paiement. «count» indique le nombre de paiements total. «period» indique l intervalle en nombre de jours entre 2 paiements. Exemple: vads_currency=978 vads_amount=10000 vads_payment_config=multi:first=5000;count=3;period=30 Dans cette configuration : Le montant total de l achat est de 100 euros, Un premier paiement de 50 euros sera effectué à aujourd hui + «vads_capture_delay» jours. Un deuxième paiement de 25 euros sera effectué à aujourd hui + «vads_capture_delay» + 30 jours. Un troisième et dernier paiement de 25 euros sera effectué à aujourd hui + «vads_capture_delay» + 60 jours. Le total des 3 transactions fait bien sûr 100 euros au final. Lyra Network- 8/16
5.9: Champ valauto valauto vads_validation _mode Voir valeur dans le tableau cidessous Paramètre facultatif pour Systempay. Le paramètre validation_mode (vads_ validation_mode ) précise le mode de validation de la transaction (manuellement par le commerçant, ou automatiquement par la plateforme). Dans le mode Manuel, le commerçant doit valider le paiement via l'outil de gestion de caisse afin que celui-ci soit remis en banque. Dans le mode automatique le paiement sera remisé en banque automatiquement en fonction de la date de remise demandée (voir champ capture_delay) Si ce paramètre est vide ou n est pas posté alors la valeur par défaut sera celle définie dans l outil de gestion de caisse (back office commerçant). Ce paramètre est configurable dans l outil de gestion de caisse (l onglet Paramétrages / Boutique /[nom de la boutique]/onglet configuration) valauto valeur vide (pas d équivalence) Valorisation vads_validation_mode Absent ou vide dans le formulaire de paiement Signification Configuration par défaut de la boutique retenue (paramétrable dans l outil de gestion de caisse) t 0 Validation automatique f 1 Validation manuelle s Aucune correspondance Notion non existante dans Systempay Dans la solution SPPLUS il était possible de valoriser le champ valauto à «s» mode semi automatique. Il n y a pas de correspondance dans la solution Systempay Lyra Network- 9/16
5.10: Champ dat1 dat1 vads_capture_delay Format : numérique Longueur : 3 Paramètre facultatif pour Systempay. Dans SSPLUS, vous deviez préciser la date exacte de remise alors que pour Systempay, vous définissez le délai en nombre de jours à partir de la date de création de la transaction. Ce paramètre indique le délai en nombre de jours avant remise en banque. Si ce paramètre n est pas transmis, alors la valeur par défaut sera utilisée. Cette valeur par défaut est paramétrable dans le back office commerçant par toutes les personnes dûment habilitées (l onglet Paramétrages /Boutique/[nom de la boutique]/onglet configuration) 5.11: Champ email : email vads_cust_email Format mail Paramètre facultatif pour Systempay. L envoi de mail de confirmation de paiement au client est optionnel dans Systempay. La valorisation de ce champ ne veut pas dire que l email sera envoyé. L option envoi d email doit être associée à votre boutique. Ce paramètre défini l adresse e-mail du client, nécessaire pour envoyer un mail récapitulatif de la transaction. Lorsque ce paramètre est transmis, alors il sera enregistré dans l outil de gestion da caisse et affecté au paiement dans l onglet client. Lyra Network- 10/16
5.12: Champ urlretour urlretour vads_url_return Format URL Paramètre facultatif pour Systempay. Dans le cas où l acquisition des données bancaires est déléguée à la plateforme de paiement, ce paramètre défini l URL où sera redirigé par défaut le client après un clic sur le bouton " retourner à la boutique ". Si cette URL n est pas présente dans la requête, alors c est la configuration dans l outil de gestion de caisse qui sera prise en compte. Il est possible de configurer des URL de retour, en mode TEST et en mode PRODUCTION. Ces paramètres sont nommés «URL de retour de la boutique» et «URL de retour de la boutique en mode test» respectivement, et sont accessibles dans l onglet «Configuration» lors du paramétrage d une boutique. Si toutefois aucune URL n est présente, que ce soit dans la requête ou dans le paramétrage de la boutique, alors le bouton «retourner à la boutique» redirigera vers l URL générique de la boutique (paramètre nommé «URL» dans la configuration de la boutique). Cette page ne doit en principe effectuer aucun traitement car il n est pas certain que l internaute clique sur retourner à la boutique. Différence entre SSPLUS et Systempay : Il est possible dans Systempay de préciser plusieurs URL de retour (en cas de succès, échec etc ) Il est possible aussi de paramétrer un retour automatique à la boutique. Il est possible de préciser dans quel mode les paramètres seront renvoyés (mode POST, GET). Par défaut aucun paramètre n est renvoyé. Pour en savoir plus sur ces 4 points veuillez vous référer à la documentation d implémentation de SYSTEMPAY Lyra Network- 11/16
5.13: Champ arg1, arg2, arg3 arg1 arg2 arg3 vads_order_info Format : Alpha numérique vads_order_info2 Longueur : 255 vads_order_info3 Différence entre SSPLUS et Systempay : Les champs arg1 et arg2 sont limités à 128 octets quand leur longueur est de 256 dans Systempay. Par contre arg3 fait 255 caractères Paramètre facultatif pour Systempay. Ces paramètres peuvent par exemple servir à stocker un résumé de la commande. Si dans la solution SPPLUS ces champs étaient utilisés pour stocker des informations liés au client vous retrouverez dans Systempay des champs spécifiques prévus à cet effet. Téléphone Téléphone mobile Adresse Ville Code postal Etc. Pour en savoir plus sur ces champs veuillez vous référer à la documentation d implémentation de SYSTEMPAY 5.14: Champ hmac hmac signature Voir calcul signature ci- dessous La signature sera constituée de l intégralité des champs dont le nom commence par la chaîne «vads_». Les champs doivent être triés par ordre alphabétique. Dans le calcul de la signature, l ordre alphabétique des paramètres doit être respecté. Les valeurs de ces champs doivent être concaténées entre elles avec le caractère «+». Au résultat de cette concaténation, vous devrez concaténer la valeur du certificat de test ou de production. Ce certificat est disponible dans l outil de gestion de caisse, back office marchand, dans l onglet Paramétrages / Boutique /[nom de la boutique]/onglet configuration. Lyra Network- 12/16
Exemple : si les paramètres de la requête sont les suivants : - vads_version = V2 - vads_page_action = PAYMENT - vads_action_mode = INTERACTIVE - vads_payment_config = SINGLE - vads_site_id = 12345678 - vads_ctx_mode = TEST - vads_trans_id = 654321 - vads_trans_date = 20090501193530 - vads_amount = 1524 - vads_currency = 978 et la valeur du certificat pour le mode TEST est "1122334455667788" L ordre alphabétique des paramètres sera le suivant : vads_action_mode, vads_amount, vads_ctx_mode, vads_currency, vads_page_action, vads_payment_config, vads_site_id, vads_trans_date, vads_trans_id, vads_version. Il faudra rajouter à ces paramètres la valeur du certificat. La chaîne à utiliser pour le calcul du HASH via l algorithme SHA-1 sera donc la suivante : INTERACTIVE+1524+TEST+978+PAYMENT+SINGLE+12345678+20090501193530+654321+V2+11223 34455667788 En bleu, il s agit de la valeur du certificat. Attention le certificat est différent en fonction du mode TEST ou PRODUCTION La signature à transmettre n est pas égale à cette chaine, mais au résultat du hachage de cette chaine à l aide de l algorithme SHA-1. 5.15: Champ méthode Le champ methode n a pas de correspondance dans la solution systempay. 5.16: Champ taxe : Le champ taxe n a pas de correspondance dans la solution systempay. 5.17: Champ validite Le champ validite n a pas réellement de correspondance dans la solution systempay. Par contre, veuillez vous référer au champ vads_trans_date défini au paragraphe suivant. Lyra Network- 13/16
6. Paramètres supplémentaires obligatoires pour Systempay Veuillez noter qu en plus des paramètres obligatoires vus précédemment vous devez aussi envoyer dans le formulaire de paiement les paramètres ci-dessous. vads_transdate vads_page_action vads_action_mode vads_ctx_mode Paramètres obligatoires (minimum) Date de la transaction : fuseau horaire UTC (ex 20110710201030 ) - (format AAAAMMJJhhmmss) Pour un paiement simple ce champ à valorisé à PAYMENT INTERACTIVE : correspond au cas où l acquisition des données carte est déléguée à la plateforme. Valeur TEST ou PRODUCTION (en fonction du mode de fonctionnement) 7. URL de notification complémentaire 7.1: Appel URL Serveur La notion d url de notification complémentaire est appelée dans la solution SYSTEMPAY URL SERVEUR (étape 2 dans le schéma du chapitre 2). Cette URL se paramètre dans le back office marchand de Systempay (Paramétrages / Boutique /[nom de la boutique]/onglet configuration). Contrairement à SPPLUS L url serveur est appelée une seule fois après la finalisation du paiement par l internaute qu il soit accepté ou refusé. L url serveur n est jamais appelée lorsqu un paiement est remis en banque il n y a pas à ce jour de paramètre indiquant un statut de la transaction. Les paramètres renvoyés précisent seulement si le paiement a été accepté ou refusé. Lyra Network- 14/16
7.2: Appel URL Serveur Etendu Cette fonctionnalité doit être activée dans votre profil commerçant dans Systempay par votre chargé d affaire. Cette fonctionnalité permet de notifier votre boutique dans le cas suivant : Une autorisation a été effectuée sur un paiement en attente d autorisation Un paiement en attente d autorisation est un paiement dont la date de remise en banque était strictement supérieure à 6 jours lors de sa création (Champ vads_capture_delay>6) 7.3: Appel de l'url serveur pour les transactions annulées ou abandonnées Cette fonctionnalité doit être activée dans votre profil commerçant dans Systempay par votre chargé d affaire Cette fonctionnalité permet de notifier votre boutique dans le cas suivant : Un client a cliqué sur "annuler et retourner à la boutique" lors du paiement Un client n a pas finalisé son paiement dans le délai de 10 minutes. Par exemple : un client a été redirigé sur la page de paiement mais n a fait aucune action durant 10 minutes 7.4: Analyse des paramètres retournés dans l URL Serveur L analyse du paiement s effectue en fonction des paramètres retournés en mode POST dans votre URL serveur. Dans cette requête est présente une signature qui permet de vérifier l authenticité de la source. Vous pouvez vérifier que cette requête a bien été générée par Payzen et non par un tiers. La règle de calcul de la signature est la même que celle vue ci-dessus. Une fois l authenticité vérifiée, vous pourrez analyser les paramètres liés au paiement et traiter la commande si le paiement est accepté. Ci-joint un extrait des paramètres clefs renvoyés : vads_result vads_extra_result vads_trans_id Signature Paramètres minimum Code retour général. Si égal à "00" le paiement est accepté, sinon le paiement est refusé. Code retour de la demande d'autorisation retournée par la banque émettrice, si disponible (vide sinon). Exemples de valeur 00 paiement accepté 14 carte invalide 05 ne pas honorer Valorisé à l identique à la valeur reçue dans le formulaire de paiement Signature renvoyée et calculée par la plateforme de paiement Lyra Network- 15/16
Pour plus d information sur les paramètres renvoyés dans l url serveur se reporter à la documentation «guide d implémentation» 8. Statut de la transaction et URL serveur Dans la solution de paiement Systempay il n y a pas à ce jour de paramètre renvoyé à l url serveur définissant le statut de transaction. Si toutefois vous utilisiez la notion de statut vous pouvez retrouver cette notion dans le journal des opérations envoyés par mail ou déposé sur un serveur FTP (espace FTP soumis à souscription) 9. ASSISTANCE TECHNIQUE Pour toute question technique, vous pouvez nous contacter par téléphone au 0 810 004 724 Accessible les jours ouvrés du lundi au vendredi de 09h00 à 18h00 (heure légale française). (Tarification de ce numéro: Coût d un appel local depuis un poste fixe) Lyra Network- 16/16