Réussir l intégration de Payzen

Réussir l intégration de Payzen Version 1.4b Réussir l intégration de Payzen 1/16

SUIVI, HISTORIQUE Rédaction, Vérification, Approbation Rédaction Vérification Approbation Nom Date/Visa Nom Date/Visa Nom Date/Visa Lyra-Network 10/06/2013 Lyra-Network 10/06/2013 Lyra-Network 10/06/2013 Historique du document Version Auteur Date Commentaires 1.4b Lyra-Network 10/06/2013 Mise à jour 1.4a Lyra-Network 23/05/2012 Mise à jour 1.4 Lyra-Network 27/12/2012 Mise à jour 1.3 Lyra-Network 29/05/2012 Mise à jour 1.2 Lyra-Network 06/12/2011 Mise à jour 1.0 Lyra-Network 01/07/2011 Création 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 Réussir l intégration de Payzen 2/16

SOMMAIRE Suivi, historique... 2 1. Principe Général.... 4 2. Etape 1: Envoyer un formulaire de paiement en post... 5 3. Etape 2: Analyser le formulaire URL serveur en post... 6 3.1: Notion d url serveur.... 6 3.2: URL serveur étendue... 7 3.3: Extrait des paramètres renvoyés... 7 3.4: Analyse d un paiement... 8 3.5: Comment visualiser l appel à l URL serveur... 9 3.6: Non synchronisation des paiements sur le site marchand... 9 4. Etape 3: le retour à la boutique (facultatif)... 10 5. Phase de test... 11 5.1: Test de paiement... 11 5.2: Vérifier le bon fonctionnement de l url serveur... 11 5.3: Génération du certificat de production... 12 6. Passage en production... 13 7. Annexes... 14 7.1: Calcul de la signature.... 14 7.2: Certificat de TEST.... 15 7.3: Certificat de Production... 15 7.4: Personnalisation de la page de paiement.... 15 8. ASSISTANCE TECHNIQUE... 16 Réussir l intégration de Payzen 3/16

1. PRINCIPE GENERAL. BOUTIQUE Etape 1: Formulaire de paiement (https) PAYZEN Etape 2: Appel Url serveur Etape 3: Retour à la boutique L implémentation technique se résume à 3 étapes : Comprendre et lire ces 3 étapes est essentiel pour implémenter le paiement. Réussir l intégration de Payzen 4/16

2. ETAPE 1: ENVOYER UN FORMULAIRE DE PAIEMENT EN POST L appel à la plateforme de paiement est réalisé via l envoi d un formulaire posté en https. Ce formulaire contient au minimum les paramètres obligatoires listés ci-dessous ainsi qu une variable signature unique par formulaire attestant de son authenticité. L URL de la page de paiement est : https://secure.payzen.eu/vads-payment/ Paramètres obligatoires (minimum) vads_amount Montant de la transaction dans la plus petite unité de la devise (centime pour ) vads_currency Devise : 978 pour euro vads_site_id Identifiant boutique à récupérer dans le back office vads_trans_id Identifiant transaction : unique au moins sur une même journée nombre à 6 chiffres vads_trans_date Date de la transaction : fuseau horaire UTC (ex 20110710201030 ) vads_version Valorisé à V2 vads_payment_config Type de paiement valorisé à SINGLE pour un paiement en 1 fois vads_page_action Pour un paiement simple ce champ à valorisé à PAYMENT vads_action_mode INTERACTIVE : correspond au cas où l acquisition des données carte est déléguée à la plateforme. vads_ctx_mode Mode de fonctionnement TEST ou PRODUCTION signature Signature unique pour chaque paiement Pour plus d informations sur les différents paramètres disponibles lors de l envoi du formulaire vous pouvez vous référer à la documentation disponible sur : http://www.payzen.eu/support.php Signature : Pour calculer la signature il est nécessaire de récupérer le certificat de test ou de production dans l outil de gestion de caisse. (ONGLET PARAMETRAGE /BOUTIQUE/[NOM DE LA BOUTIQUE]/CONFIGURATION) Pour plus d information sur le calcul de la signature se reporter au chapitre annexe ou à la documentation sur http://www.payzen.eu/support.php Remarque : Utilisation des balises html <iframe> et <frame> Une iframe (inline frame) est utilisée pour afficher une page web dans une autre page web. Exemples de codes interdits : L utilisation des iframes pour afficher la page de paiement est interdite pour des raisons de sécurité <FRAMESET> <FRAME SRC="https://secure.payzen.eu/vads-payment/"> </FRAMESET> <iframe src="https:// secure.payzen.eu/vads-payment/"></iframe> Réussir l intégration de Payzen 5/16

3. ETAPE 2: ANALYSER LE FORMULAIRE URL SERVEUR EN POST 3.1: Notion d url serveur. L URL serveur est le seul mécanisme à implémenter pour synchroniser automatiquement le site de paiement et votre site marchand. A la fin d un paiement, la plateforme de paiement appelle systématiquement l url serveur renseignée dans le back-office marchand. Cet appel a pour but d informer le site marchand de l état du paiement (même si le client ne revient pas sur le site). Le marchand pourra ainsi valider sa commande si le paiement est accepté. L appel est une requête HTTP ou en HTTPS contenant un POST dans lequel sont valorisés des paramètres permettant l analyse du paiement (accepté ou refusé etc ). L url serveur (en mode TEST ou PRODUCTION) doit être renseignée dans le back office marchand. (Onglet Paramétrage /Boutique/[Nom de la boutique]/configuration) Remarque importantes Cette URL est toujours appelée avec un formulaire HTTP POST, et ce quelque soit la valeur du paramètre vads_return_mode. L url serveur est le seul mécanisme qui doit permettre le lancement des tâches dépendantes du paiement. (Mise à jour du statut de la commande dans votre back office boutique, envoie d émail, déstockage produit etc ) En cas d échec de l appel de l url serveur, la plateforme de paiement envoie un mail à l administrateur de la boutique avec la raison de l échec (erreur http etc ) Vous pourrez alors rejouer l url serveur depuis le back office de la solution de paiement. Attention : l URL serveur peut être appelée plusieurs fois, il donc nécessaire que votre implémentation prenne cela en considération. Réussir l intégration de Payzen 6/16

3.2: URL serveur étendue En fonction des options commerciales souscrites, la plateforme de paiement pourra effectuer un appel vers l url serveur dans les cas suivants : Remboursement effectué depuis le back office Annulation d une transaction depuis le back office Validation d une transaction depuis le back office Modification d une transaction depuis le back office Abandon d une transaction depuis le back office 3.3: Extrait des paramètres renvoyés vads_result Paramètres minimum Code retour général. Si égal à «00» le paiement est accepté, sinon le paiement est refusé. Ce paramètre permet de définir le statut de la transaction. Exemples de valeurs : REFUSED => le paiement a été refusé. AUTHORISED => le paiement a été accepté pour le montant total de la transaction et est en attente de remise en banque. vads_trans_status AUTHORISED_TO_VALIDATE => le paiement a été accepté mais est en attente de validation manuelle de la part du marchand. Sans cette validation, la transaction basculera dans le statut Expiré une fois le délai de capture dépassé. WAITING_AUTHORISATION => le paiement est en attente d autorisation. Une prise d empreinte a été réalisée pour valider les données de la carte bancaire car le délai de remise en banque est strictement supérieur à 7 jours. La demande d autorisation pour le montant total sera réalisée ultérieurement, avec un risque que le paiement soit refusé. WAITING_AUTHORISATION_TO_VALIDATE => le paiement est en attente d autorisation et de validation manuelle. Une prise d empreinte a été réalisée pour valider les données de la carte bancaire car le délai de remise en banque est strictement supérieur à 7 jours. Sans validation de part du marchand, la transaction basculera dans le statut Expiré une fois le délai de capture dépassé. vads_auth_result 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 Si contient FULL => Paiement accepté pour le montant total de la transaction. vads_auth_mode vads_trans_id signature Si contient MARK => Paiement enregistré mais non encore autorisé (il s'agit seulement d'une empreinte qui permet de valider les données cartes mais pas la capacité de paiement de l acheteur). L'autorisation pour le montant total sera réalisée ultérieurement avec un risque de paiement refusé. (Se reporter à la documentation pour plus d'information). MARK concerne les paiements avec une date de remise en banque au-delà de la durée de validité de l autorisation (7 jours pour la France). Si votre délai de remise en banque est inférieur à 7 jours pour CB/Visa/Mastercard en France, FULL est la seule valeur possible. Valorisé à l identique à la valeur reçue dans le formulaire de paiement Signature renvoyée et calculée par la plateforme de paiement Pour plus d information sur les paramètres renvoyés dans l url serveur se reporter à la documentation disponible sur http://www.payzen.eu/support.php Réussir l intégration de Payzen 7/16

3.4: Analyse d un paiement L analyse du paiement s effectue en fonction des paramètres envoyé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 est bien été générée par Payzen et non par un tiers]. 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é. Exemple d algorithme d analyse des paramètres : Contrôle de la signature reçue Signature OK NON Ne pas tenir compte de cette réponse ou vérifier que le calcul de signature est correct. OUI Contrôle du type de la transaction vads_operation_type CREDIT DEBIT La transaction est un débit ayant comme caractéristique : Statut : vads_trans_status Résultat : vads_result Identifiant : vads_trans_id Montant : vads_amount La transaction est un remboursement ayant comme caractéristique : Statut : vads_trans_status Montant : vads_amount Identifiant : vads_trans_id Montant Effectif : vads_effective_amount Type de paiement : vads_payment_config Numéro de séquence : vads_sequence_number Résultat d autorisation : vads_auth_result Garantie de paiement : vads_warranty_result Statut 3DS : vads_threeds_status Réussir l intégration de Payzen 8/16

3.5: Comment visualiser l appel à l URL serveur Chaque appel à l URL serveur est enregistré par la plateforme de paiement. Pour vérifier l appel à l URL serveur, depuis le back-office, faites un double clic sur le paiement, puis allez dans l onglet Historique. La colonne Info contient le statut de l appel à l URL serveur. 3.6: Non synchronisation des paiements sur le site marchand Erreurs fréquentes : URL serveur non renseignée dans le back office «outil de gestion de caisse», URL serveur qui pointe sur la page d accueil du site marchand et qui n exécute aucun traitement, URL serveur qui ne peut être appelée car bloquée par un fichier.htaccess URL serveur bloquée par votre firewall, Module Paypal pour Prestashop incompatible avec les autres moyens de paiement, Redirection à l arrivée qui entraine la perte des valeurs postées. L url serveur contient toujours les paramètres postés. Ne pas les trouver est toujours une erreur d implémentation du côté du site marchand, Les paramètres postés dans l URL serveur peuvent évoluer par ajout de nouveaux champs. Ne jamais calculer la signature en se basant sur une liste fixe et prédéfinie correspondant à votre comportement au moment de votre implémentation. Réussir l intégration de Payzen 9/16

4. ETAPE 3: LE RETOUR A LA BOUTIQUE (FACULTATIF) Le retour à la boutique permet à l internaute de revenir à la boutique après un clic sur le bouton "retour boutique» présent sur la page de paiement. Dans le formulaire de paiement il est possible de renseigner plusieurs URL de retour : url en cas de succès, url en cas d annulation, url en cas de refus, etc (Se référer à la documentation pour connaître tous les cas possibles) Il est conseillé dans le cas du retour à la boutique d analyser le contenu des paramètres en fonction du contexte de retour que vous voulez afficher à votre client: Par exemple : retour à l accueil de votre site retour sur un refus où vous pouvez proposer un moyen de paiement alternatif retour sur un message de remerciement ou de synthèse de commande si paiement accepté. Il est aussi possible de paramétrer un retour automatique à la boutique en ajoutant un paramètre dans le formulaire lors de l appel à la page de paiement. (Utilisé par les marchands qui font du GOOGLE ANALYTICS) La documentation est disponible sur http://www.payzen.eu/support.php Par défaut nous ne renvoyons aucun paramètre dans l URL retour à la boutique, mais vous pouvez définir dans le formulaire de paiement comment recevoir les paramètres via le champ vads_return_mode (valorisé lors de la construction de votre formulaire de paiement. c.f Etape 1). GET POST NONE Valeur de vads_return_mode les paramètres sont renvoyés en mode GET. les paramètres sont renvoyés en mode POST (non recommandé). aucun paramètre n est envoyé. Réussir l intégration de Payzen 10/16

5. PHASE DE TEST 5.1: Test de paiement Lorsque le formulaire de paiement posté est correct une liste de cartes de test correspondant à des scénarii différents vous sera proposée. Il suffit de cliquer sur un numéro de carte de test pour remplir le champ de saisie pour remplir les champs de la page de paiement et ensuite cliquer sur "Valider". 5.2: Vérifier le bon fonctionnement de l url serveur A la fin du paiement, vérifier que l appel à l url serveur en mode test a fonctionné correctement et que par conséquent votre système d information s est mis à jour correctement. En cas de problème dans la réception des informations sur votre URL serveur, vous pouvez consulter l historique d une transaction. Double cliquez sur une transaction pour faire apparaitre la fenêtre de détail. Allez dans l onglet Historique et recherchez la ligne Appel URL serveur. La colonne Info. contient le résultat de l appel (SENT ou FAILED) ainsi que la réponse affichée par votre script si cela est prévu dans votre code. Réussir l intégration de Payzen 11/16

5.3: Génération du certificat de production Il est conditionné par la réalisation des tests qui sont demandés dans l outil de gestion de caisse (onglet Paramétrage/Boutique / [Nom de votre boutique]/ Certificats) : Pour valider chaque test, vous devrez effectuer un achat sur votre boutique, en utilisant au moins un numéro de chaque ligne. Chaque colonne correspond à un type de carte différent (CB/VISA, MASTERCARD, MAESTRO, VISA- ELECTRON). Une fois tous les tests validés, vous pourrez cliquer sur le bouton Générer le certificat de production. Réussir l intégration de Payzen 12/16

6. PASSAGE EN PRODUCTION Pour paramétrer votre boutique en mode production vous devez effectuer les 5 étapes suivantes : 1. La phase de test terminée vous pouvez demander auprès des services Payzen la génération du certificat de production ou le générer vous-même suivant la délégation donnée à la création de la boutique. 2. Modifier la variable précisant le mode de fonctionnement (vads_ctx_mode). Cette variable devra être valorisée à "PRODUCTION" en majuscule, sans abréviation en lieu et place de la valeur "TEST". 3. Affecter à la variable dans laquelle vous stocker votre certificat, la valeur du certificat de Production. 4. Renseigner l url serveur en mode production dans le back office Payzen. 5. Il est fortement conseillé de faire un paiement réel, de vérifier votre crédit en compte et de vérifier le bon fonctionnement de l url serveur. Remarque : Le mode TEST reste disponible même après avoir généré la clef de production. Il suffit de poster des formulaires de paiement utilisant le mode TEST et le certificat de TEST. Réussir l intégration de Payzen 13/16

7. ANNEXES 7.1: Calcul de la signature. La signature sera constituée de l intégralité des champs dont le nom commence par la chaîne «vads_». Les champs doivent être triés par ordre alphabétique. Les valeurs de ces champs doivent être concaténées entre elles avec le caractère «+». Au résultat de cette concaténation, on concatènera la valeur du certificat employé (certificat de test ou de production). Appliquer l algorithme SHA1 pour obtenir la valeur de la signature Erreur fréquente : Le caractère + n est pas présent entre les champs. Dans le calcul de la signature, l ordre alphabétique des paramètres doit être respecté. La signature à transmettre n est pas égale à cette chaine, mais au hachage de cette chaine à l aide de l algorithme SHA-1. Exemple : Paramètres de la requête envoyée à la plateforme de paiement: - 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 - Valeur du certificat en fonction du mode =1122334455667788 L ordre alphabétique des paramètres est le suivant : - vads_action_mode - vads_amount - vads_ctx_mode - vads_currency - vads_page_action - vads_payment_config Réussir l intégration de Payzen 14/16

- vads_site_id - vads_trans_date - vads_trans_id - vads_version Il faudra rajouter à ces paramètres la valeur du certificat 1122334455667788 La chaîne à utiliser pour le hachage à l aide de l algorithme SHA-1 sera donc la suivante : INTERACTIVE+1524+TEST+978+PAYMENT+SINGLE+12345678+20090501193530+654321+V2+1122334455 667788 La signature à envoyer dans le champ nommé signature est: 606b369759fac4f0864144c803c73676cbe470ff 7.2: Certificat de TEST. Le certificat de test est une chaîne qui vous servira à calculer une signature unique pour chaque paiement. Le certificat de test est disponible dans le back office Payzen (onglet paramétrage /boutique /[Nom de la boutique]/certificat). 7.3: Certificat de Production Le certificat de production est une chaîne qui vous servira à calculer une signature unique pour chaque paiement de production. Le certificat de production est disponible dans le back office Payzen (onglet paramétrage /boutique /[Nom de la boutique]/certificat). Celui-ci ne sera plus visible dès lors que vous aurez finalisé un paiement réel via le formulaire pour des raisons de sécurité. 7.4: Personnalisation de la page de paiement. Vous pouvez charger depuis le back office votre logo qui apparaîtra alors sur la page de paiement. Si vous souhaitez des paramètres plus avancés vous devez souscrire à l option personnalisation avancée. Cette option vous permet depuis le back office de modifier les CSS originales (mobile et écran classique), ou encore d ajouter plusieurs CSS. Vous pourrez à tout moment avant de valider la CSS pré-visualiser le rendu visuel. Réussir l intégration de Payzen 15/16

8. ASSISTANCE TECHNIQUE Pour tout problème d accès au back office Payzen, il convient d utiliser les liens «compte bloqué» ou «mot de passe oublié» disponible sur la page de connexion du back office Payzen. Pour toute question technique, vous pouvez nous contacter par téléphone au 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 Réussir l intégration de Payzen 16/16