PayPal Paiement différé (Mode Order) PayZen 2.4

Transcription

1 PayPal Paiement différé (Mode Order) PayZen 2.4 Version du document 2.1

2 Sommaire 1. HISTORIQUE DU DOCUMENT CONTACTER L'ASSISTANCE TECHNIQUE PAYPAL : PAYER EN LIGNE SANS SAISIR VOS COORDONNÉES BANCAIRES UTILISER PAYPAL Prérequis... 7 Créer un compte PayPal... 7 Paramétrer votre Back Office pour utiliser PayPal...7 Gérer les habilitations...8 Associer un compte PayPal à une boutique Visualiser le déroulement d'un paiement PayPal sur la page de paiement Visualiser une transaction PayPal (paiement différé) dans le Back Office S'informer sur la garantie de paiement avec PayPal ÉTABLIR LE DIALOGUE AVEC LA PLATEFORME DE PAIEMENT GÉNÉRER UN FORMULAIRE DE PAIEMENT Créer un paiement différé PayPal UTILISER DES FONCTIONS COMPLÉMENTAIRES Transmettre les données de livraison Transmettre les données de la commande Transmettre les données de l'acheteur Gérer les moyens de paiement proposés à l'acheteur CONTRÔLER LA COHÉRENCE DES CHAMPS CALCULER LA SIGNATURE ENVOYER LA DEMANDE DE PAIEMENT Rediriger l'acheteur vers la page de paiement Gérer les erreurs ANALYSER LE RÉSULTAT DU PAIEMENT Récupérer les données retournées dans la réponse Calculer la signature Comparer les signatures Analyser la nature de la notification Identifier le type d'opération Traiter les données de la réponse - Paiement différé PayPal IDENTIFIER LES OPÉRATIONS AUTORISÉES SUR LES TRANSACTIONS PAYPAL (PAIEMENT DIFFÉRÉ) Valider une transaction...36 Valider une transaction dont le statut est A valider...36 Valider une transaction dont le statut est A valider et autoriser Modifier une transaction Annuler une transaction Editer la référence d'une commande Renvoyer l' de confirmation de la transaction à l'acheteur Renvoyer l' de confirmation de la transaction au marchand Remiser une commande en plusieurs fois Remiser partiellement une commande... 42

3 12.9. Effectuer un remboursement sur une transaction remisée... 43

4 1. HISTORIQUE DU DOCUMENT Version Auteur Date Commentaire 2.1 Lyra Network 21/09/2015 Informations complémentaires sur la protection des marchands PayPal. 2.0 Lyra Network 06/10/2014 Version initiale format DITA 1.0 Lyra Network 24/08/2011 Version initiale 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. Droit de propriété intellectuelle - 4 / 43

5 2. CONTACTER L'ASSISTANCE TECHNIQUE En cas de problème de connexion au Back Office, utilisez le lien «mot de passe oublié ou compte bloqué». Pour toute question technique ou demande d'assistance, nos services sont disponibles du lundi au vendredi, de 9h à 18h : par téléphone au : par depuis la France, (Numéro Azur Coût d un appel local depuis un poste fixe) depuis l'étranger, support@payzen.eu Pour faciliter le traitement de vos demandes, il vous sera demandé de communiquer votre identifiant de boutique (numéro à 8 chiffres). Cette information est disponible dans l' d'inscription de votre boutique, ou dans le Back Office (menu Paramétrage > Boutique > Configuration). Droit de propriété intellectuelle - 5 / 43

6 3. PAYPAL : PAYER EN LIGNE SANS SAISIR VOS COORDONNÉES BANCAIRES PayPal est un moyen de paiement qui permet aux marchands de recevoir sur leur site des paiements par carte et par compte PayPal. Payer en ligne avec PayPal c'est payer sans communiquer des données financières au marchand. Un acheteur réalise un paiement en s'identifiant avec une adresse et un mot de passe. Droit de propriété intellectuelle - 6 / 43

7 4. UTILISER PAYPAL Ce chapitre présente le paiement en ligne PayPal. Il vous guidera pas à pas dans l'intégration de ce moyen de paiement Prérequis Côté marchand L'ajout du moyen de paiement PayPal sur votre site marchand est très simple. Elle consiste en : La création d'un compte PayPal si vous n'en possédez pas. L'utilisation d'un compte PayPal si vous en possédez un. L'activation de l'option Paiement via PayPal auprès de votre contact commercial de votre plateforme de paiement. Côté acheteur L'adhésion à PayPal est gratuite et s'effectue depuis le site Internet de PayPal. L'acheteur doit : Créer un compte PayPal en enregistrant une adresse et un mot de passe. Renseigner l'ensemble des informations propres à son identité, son adresse... Renseigner l'ensemble des informations bancaires demandées. Créer un compte PayPal 1. Vous devez créer un compte marchand sur PayPal à cette adresse Internet : Il peut aussi être utile de créer un compte marchand sur PayPal en mode Sandbox (mode Test) afin d effectuer des tests d intégration. Vous pouvez le faire à cette adresse Internet : 2. Sélectionnez la solution PayPal la plus adaptée aux besoins de votre activité. A la fin de l'inscription, PayPal envoie un de confirmation d'inscription. Suivez la procédure pour valider votre inscription. Dans le cas contraire, votre compte ne sera pas activé. Paramétrer votre Back Office pour utiliser PayPal 1. Connectez-vous à votre Back Office en renseignant votre login et votre mot de passe. La page des transactions de la boutique s'affiche. 2. Cliquez sur le menu Paramétrage > Société > Comptes PayPal. 3. Cliquez sur Ajouter un compte. La boîte de dialogue Ajout d'un compte PayPal s'affiche. Droit de propriété intellectuelle - 7 / 43

8 4. Renseignez votre PayPal professionnel. 5. Sélectionnez le mode du compte. Sandbox : mode TEST Live : mode PRODUCTION 6. Cliquez sur Créer. Gérer les habilitations Pour recevoir les paiements sur le compte PayPal, il est indispensable de donner l habilitation. 1. Sélectionnez votre compte PayPal. Le détail du compte PayPal s'affiche dans la partie inférieure de l'écran. 2. Dans l'encadré Gestion des habilitations, cliquez sur le bouton Donner l'habilitation. En cliquant sur ce bouton, vous êtes redirigés vers le site PayPal. 3. Connectez-vous avec votre identifiant et votre mot de passe sur le site Internet de PayPal. 4. Suivez les instructions afin d'accepter les permissions. 5. Cliquez sur Sauvegarder. Associer un compte PayPal à une boutique Pour proposer le moyen de paiement PayPal sur votre page de paiement il faut associer le contrat PayPal créé à votre boutique. 1. Sélectionnez votre compte PayPal. Le détail du compte PayPal s'affiche dans la partie inférieure de l'écran. 2. Dans l'encadré Boutiques associées, cochez la boutique que vous souhaitez associer au compte PayPal. 3. Cliquez sur Sauvegarder. Droit de propriété intellectuelle - 8 / 43

9 4.2. Visualiser le déroulement d'un paiement PayPal sur la page de paiement Le diagramme ci-dessous présente la cinématique des échanges du point de vue de l'acheteur. 1. L'acheteur valide son panier. Image 1 : Cinématique des échanges - Vue acheteur 2. Le site marchand redirige l acheteur vers la plateforme de paiement. Cette redirection se fait sous la forme d'un formulaire HTML POST en HTTPS. Les paramètres qui le composent sont décrits dans le chapitre Générer un formulaire de paiement. 3. La plateforme de paiement, après vérification des paramètres et de leur signature, présente la page de sélection du moyen de paiement. Image 2 : Sélection du moyen de paiement Si le moyen de paiement a été spécifié dans le formulaire, l acheteur passe directement à l étape L acheteur sélectionne le moyen de paiement PayPal. 5. Il clique sur Valider. La plateforme de paiement vous invite à patienter quelques instants. Elle vous redirige vers le site de PayPal. 6. L'acheteur est invité à choisir son mode de paiement. Il peut se connecter à son compte PayPal pour payer ou bien créer un compte PayPal pour payer plus rapidement à l'avenir. 7. Si l'acheteur possède un compte PayPal, il s'identifie grâce à son adresse et son mot de passe. Si L'acheteur ne possède pas de compte PayPal, il sélectionne sa carte et renseigne les différentes informations demandées. 8. L'acheteur vérifie les informations liées à son paiement. Droit de propriété intellectuelle - 9 / 43

10 9. L'acheteur clique sur Payer. 10.L'acheteur est redirigé vers la plateforme de paiement. En cas de succès, une page de résumé est présentée à l'acheteur récapitulant les informations de la transactions. Un lien en bas de la page permet de retourner à la boutique. En cas d'échec, un message s'affiche. L'acheteur est informé du refus de la demande de paiement. Un lien en bas de la page permet de retourner à la boutique Visualiser une transaction PayPal (paiement différé) dans le Back Office Les transactions sont visibles dans le Back Office depuis le menu Gestion > Transactions. Une transaction dont le paiement est différé apparaît directement dans l'onglet Paiement en cours. 1. Sélectionnez une transaction PayPal. 2. Effectez un clic droit puis sélectionnez Afficher le détail de la transaction. Image 3 : Onglet Paiement en cours - PayPal La boîte de dialogue Détail d'une transaction en cours apparaît. Droit de propriété intellectuelle - 10 / 43

11 Parmi les informations présentées, vous trouverez: Le type de la transaction Image 4 : Détail d'une transaction en cours PayPal Débit dans le cadre d'un paiement. Crédit dans le cadre d'un remboursement. Le montant de la transaction La date de création de la transaction Le paiement pour cet exemple est réalisé le 13/10/2014. Le statut de la transaction Statut "En attente d'autorisation". Seule une demande d'empreinte est réalisée. L'autorisation sera faite ultérieuerement. La date de présentation demandée La date demandée pour cet exemple est le 23/10/2014, soit 10 jours après la date de création de la transaction. La demande d'autorisation sera rélisée le 20/10/2014, soit 3 jours avant la date de présentation demandée. Le compte PayPal de l'acheteur qui a effectué le paiement La mention empreinte Elle spécifie le montant, le résultat du retour de l'empreinte, le numéro de l'empreinte et la date de création de la transaction. Le certificat PayPal de la transaction Droit de propriété intellectuelle - 11 / 43

12 4.4. S'informer sur la garantie de paiement avec PayPal PayPal ne garantit aucun paiement. Cependant un paiement accepté est un paiement transféré. Si vous utilisez le mode Order (paiement différé), il est important de respecter les délais de remise. Cependant dès la remise effectuée, l argent est transféré sans exception. Si PayPal retourne un statut de paiement accepté, l argent est toujours transféré. Droit de propriété intellectuelle - 12 / 43

13 5. ÉTABLIR LE DIALOGUE AVEC LA PLATEFORME DE PAIEMENT Le dialogue avec la plateforme de paiement est décrit dans le guide d'implémentation du formulaire de paiement disponible ici: Droit de propriété intellectuelle - 13 / 43

14 6. GÉNÉRER UN FORMULAIRE DE PAIEMENT Pour générer une demande de paiement, vous devez construire un formulaire html comme suit : <form method="post" action=" <input type="hidden" name="parametre1" value="valeur1" /> <input type="hidden" name="parametre2" value="valeur2" /> <input type="hidden" name="parametre3" value="valeur3" /> <input type="hidden" name="signature" value="signature"/> <input type="submit" name="payer" value="payer"/> </form> Il contient: Les éléments techniques suivants : Les balises <form> et </form> qui permettent de créer un formulaire HTML. L attribut method="post" qui spécifie la méthode utilisée pour envoyer les données. L attribut action=" qui spécifie où envoyer les données du formulaire. Les données du formulaire : L identifiant de la boutique, Les caractéristiques du paiement en fonction du cas d utilisation, Les informations complémentaires en fonction de vos besoins, La signature qui assure l'intégrité du formulaire. Ces données sont ajoutées au formulaire en utilisant la balise <input>: <input type="hidden" name="parametre1" value="valeur1" /> Pour valoriser les attributs name et value, référez-vous au chapitre Dictionnaire de données du guide d'implémentation du formulaire. Toutes les données du formulaire doivent être encodées en UTF-8. Les caractères spéciaux (accents, ponctuation etc ) seront ainsi correctement interprétés par la plateforme de paiement. Dans le cas contraire, le calcul de signature sera erroné et le formulaire sera rejeté. Le bouton Payer qui va permettre l envoi des données : <input type="submit" name="payer" value="payer"/> Droit de propriété intellectuelle - 14 / 43

15 6.1. Créer un paiement différé PayPal Un paiement différé est un paiement comptant qui consiste à octroyer un délai entre la date d'acquisition d'un bien et son paiement. Ce délai avant remise à PayPal peut être définit dans le formulaire de paiement via le paramètre vads_capture_delay. Dans le cas d'un paiement différé, le délai de remise est strictement supérieur à 0. Comme pour un paiement par carte bancaire, le comportement diffère si le délai de remise est supérieur à la durée de validité de l autorisation. Via PayPal une autorisation n est valable que trois jours (au lieu de 6 pour une carte bancaire). Si le délai de remise est inférieur ou égal à 3 jours: Une autorisation est effectuée le jour du paiement. La remise sera faite le jour de la date de présentation demandée. Si le délai de remise est supérieur à 3 jours: Le jour du paiement, une opération semblable à la prise d empreinte est effectuée. L autorisation sera réalisée 3 jours avant la date de présentation demandée. La remise est toujours faite le jour de la date de présentation. 1. Utilisez l'ensemble des champs présents dans le tableau ci-dessous pour construire votre formulaire de paiement. Nom du champ Description Valeur vads_site_id Identifiant de la boutique Ex : vads_ctx_mode Mode de fonctionnement TEST ou PRODUCTION vads_trans_id Numéro de la transaction Ex : vads_trans_date vads_amount Date et heure UTC du formulaire de paiement Montant du paiement (dans sa plus petite unité monétaire) Ex : Ex : 3000 pour 30 euros vads_currency Code de la devise utilisée pour le paiement Ex : 978 pour euro vads_action_mode Mode d acquisition des données de la carte SILENT ou INTERACTIVE vads_page_action Action à réaliser PAYMENT vads_version Version du protocole d échange V2 vads_payment_config Type de paiement SINGLE vads_payment_card Moyen de paiement PAYPAL vads_capture_delay Délai avant remise en banque Ex : 2 vads_validation_mode Précise le mode de validation de la transaction (manuellement par le marchand, ou automatiquement par la plateforme). Tableau 1 : Liste des champs - Paiement comptant immédiat 2. Valorisez le champ vads_payment_config à SINGLE. 3. Valorisez le champ vads_capture_delay avec une valeur supérieure à 0. 0 ou 1 ou absent ou vide 4. Valorisez le champ vads_payment_card à PAYPAL si vous souhaitez ne faire apparaître que PayPal en tant que moyen de paiement sur votre page de paiement. Si vous souhaitez effectuer des paiements de tests, valorisez le champ vads_payment_card à PAYPAL_SB. Droit de propriété intellectuelle - 15 / 43

16 5. Valorisez le champ vads_currency avec le code de la devise souhaitée en utilisant le tableau cidessous: Devise Codification ISO 4217 Devise Codification ISO 4217 Baht thailandais 764 Moroccan Dirham 504 Couronne danoise 208 Nouveau dollar de Taïwan 901 Couronne islandaise 352 Nouvelle Livre turque 949 Couronne norvégienne 578 Kuwaiti Dinar 414 Couronne suédoise 752 Dinar Tunisien 788 Couronne tchèque 203 Peso argentin 032 Dollar australien 036 Peso mexicain 484 Dollar canadien 124 Peso philippin 608 Dollar de Hong Kong 344 Rand sud-africain 710 Dollar de Singapour 702 Real de Brésil 986 Dollar des États-Unis 840 Renminbi yuan chinois 156 Dollar néo-zélandais 554 Ringgit malais 458 Euro 978 Rouble russe 643 Forint hongrois 348 Rupiah indonésienne 360 Franc CFP 953 Won de Corée du Sud 410 Franc suisse 756 Yen 392 Indian rupee 356 Zloty polonais 985 Livre sterling Valorisez le champ vads_validation_mode à 0 pour une validation automatique ou à 1 pour une validation manuelle. Par défaut, le mode de validation est automatique. Si ce champ est absent ou vide, le mode par défaut sera utilisé. 7. Ajoutez les champs optionnels en fonction de vos besoins (voir chapitre Utiliser des fonctions complémentaires). 8. Calculer la valeur du champ signature en utilisant l'ensemble des champs de votre formulaire dont le nom commence par vads_ (voir chapitre Calculer la signature). Droit de propriété intellectuelle - 16 / 43

17 7. UTILISER DES FONCTIONS COMPLÉMENTAIRES PayPal a mis en place un programme de protection des marchands qui permet de protéger un marchand en cas de litige avec son acheteur. Afin de bénéficier de cette protection lors de la vente d'objets physiques, il faut impérativement transmettre la description des produits et l'adresse de livraison à la plateforme de paiement afin que celle-ci les transmette à son tour à PayPal. Les données de livraison correspondent à tous les champs qui commencent par vads_ship_. Pour plus de détails, veuillez vous référer au chapitre Transmettre les données de la livraison. Si ces informations ne sont pas transmises à PayPal, le marchand ne pourra bénéficier d'aucune protection. La protection n est pas automatiquement attribuée à tous les marchands. Pour plus de renseignements, veuillez contacter PayPal ou rendez-vous sur leur site internet à l'adresse webapps/mpp/paypal-safety-and-security. Pour obtenir un formulaire personnalisé et adapté à vos besoins, vous pouvez utiliser des fonctions complémentaires parmi la liste ci-dessous : Gérer les moyens de paiement proposés à l'acheteur sur la page de paiement Transmettre des informations sur l acheteur (civilité, adresse ..) Transmettre des informations sur la livraison (adresse ) Transmettre des informations sur la commande (référence, contenu du panier ) Droit de propriété intellectuelle - 17 / 43

18 7.1. Transmettre les données de livraison Le marchand peut transmettre les données de livraison de l'acheteur (adresse, civilité, numéro de téléphone etc ). Pour bénéficier de la protection des marchands PayPal, ces données doivent obligatoirement être transmises via le formulaire de paiement. La protection ne concerne que les commandes donnant lieu à une expédition. L'adresse de livraison connue chez PayPal doit être exactement celle à laquelle est envoyée le colis. Ces données seront affichées dans le Back Office en consultant le détail de la transaction (onglet Livraison). 1. Utilisez l ensemble des champs nécessaires à votre cas d utilisation (voir chapitre Générer un formulaire de paiement) pour construire votre formulaire de paiement. 2. Utilisez les champs facultatifs ci-dessous en fonction de vos besoins. Ces champs seront renvoyés dans la réponse avec la valeur transmise dans le formulaire. Nom du champ vads_ship_to_status vads_ship_to_name vads_ship_to_first_name* vads_ship_to_last_name* vads_ship_to_legal_name* vads_ship_to_phone_num* vads_ship_to_street_number vads_ship_to_street* vads_ship_to_street2* vads_ship_to_district vads_ship_to_zip* vads_ship_to_city* vads_ship_to_state* Description Statut (PRIVATE: pour particulier / COMPANY pour une entreprise). Déprécié. Nom de l acheteur. Utilisez vads_ship_to_first_name et vads_ship_to_last_name. Prénom. Nom. Raison sociale. Numéro de téléphone. Numéro de rue. Adresse postale. Deuxième ligne d adresse. Quartier. Code postal. Ville. Etat / Région. vads_ship_to_country* Code pays suivant la norme ISO 3166 Remarque : Tableau 2 : Liste des champs - Détails de la livraison Les champs marqués d'une astérisque (*) sont obligatoires et doivent être correctement renseignés pour bénéficier de la protection des marchands PayPal. Cette liste est donnée à titre inficatif et peut faire l'objet d'une évolution chez PayPal. Veuillez lire les Conditions d Utilisation de PayPal pour bénéficier de cette protection des marchands. 3. Calculez la valeur du champ signature en utilisant l ensemble des champs de votre formulaire, dont le nom commence par vads_ (voir chapitre Calculer la signature). Droit de propriété intellectuelle - 18 / 43

19 7.2. Transmettre les données de la commande Le marchand peut indiquer dans son formulaire de paiement s il souhaite transmettre les informations de la commande (numéro de la commande, description, contenu du panier etc ). Ces données seront affichées dans le Back Office en consultant le détail de la transaction (onglet Panier). 1. Utilisez l ensemble des champs nécessaires à votre cas d utilisation (voir chapitre Générer un formulaire de paiement) pour construire votre formulaire de paiement. 2. Utilisez les champs facultatifs ci-dessous en fonction de vos besoins. Ces champs seront renvoyés dans la réponse avec la valeur transmise dans le formulaire. Nom du champ vads_order_id vads_order_info vads_order_info2 vads_order_info3 vads_nb_products vads_product_labeln vads_product_amountn vads_product_typen vads_product_refn vads_product_qtyn vads_shipping_amount vads_tax_amount vads_insurance_amount Description Numéro de commande. Description de la commande. Description de la commande. Description de la commande. Nombre d articles. Libellé de l article. N correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Montant de l article. N correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Type de l article. N correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Référence de l article. N correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Quantité d article. N correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Montant des frais de livraison. Montant des taxes pour l'ensemble de la commande. Montant de l'assurance pour l'ensemble de la commande. Tableau 3 : Liste des champs - Détails de la commande 3. Valorisez le champ vads_nb_products avec le nombre d'articles contenu dans le panier. Remarque : Ce champ est obligatoire pour que le panier soit pris en compte. 4. Valorisez le champ vads_product_amountn avec le montant des différents articles contenus dans le panier dans l'unité la plus petite de la devise. 0 correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). 5. Valorisez le champ vads_product_typen avec la valeur correspondant au type de l'article. 0 correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). Valeur FOOD_AND_GROCERY AUTOMOTIVE ENTERTAINMENT HOME_AND_GARDEN HOME_APPLIANCE AUCTION_AND_GROUP_BUYING FLOWERS_AND_GIFTS COMPUTER_AND_SOFTWARE HEALTH_AND_BEAUTY SERVICE_FOR_INDIVIDUAL SERVICE_FOR_BUSINESS Description Produits alimentaires et d'épicerie Automobile / Moto Divertissement / Culture Maison et jardin Equipement de la maison Ventes aux enchères et achats groupés Fleurs et cadeaux Ordinateurs et logiciels Santé et beauté Services à la personne Services aux entreprises Droit de propriété intellectuelle - 19 / 43

20 Valeur SPORTS CLOTHING_AND_ACCESSORIES TRAVEL HOME_AUDIO_PHOTO_VIDEO TELEPHONY Description Sports Vêtements et accessoires Voyage Son, image et vidéo Téléphonie Tableau 4 : Valeurs associées à vads_product-type0 6. Valorisez le champ vads_product_labeln avec le libellé de chacun des articles contenus dans le panier. 0 correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). 7. Valorisez le champ vads_product_qtyn avec la quantité de chacun des articles contenus dans le panier. 0 correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). 8. Valorisez le champ vads_product_refn avec la référence de chacun des articles contenus dans le panier. 0 correspond à l'indice de l'article (0 pour le premier, 1 pour le second...). 9. Valorisez le champ vads_shipping_amount avec le montant des frais de livraison pour l'ensemble de la commande. Le montant est exprimé dans l'unité la plus petite de la devise. Le centime pour l'euro. 10.Valorisez le champ vads_tax_amount avec le montant des taxes pour l'ensemble de la commande. Le montant est exprimé dans l'unité la plus petite de la devise. Le centime pour l'euro. 11.Valorisez le champ vads_insurance_amount avec le montant de l'assurance pour l'ensemble de la commande. Le montant est exprimé dans l'unité la plus petite de la devise. Le centime pour l'euro. 12.Contrôlez la valeur du champ vads_amount. Elle doit correspondre au montant total de la commande. Remarque : L'équation utilisée est la suivante : Somme ( vads_product_qty(n) x vads_product_amount(n) ) + vads_shipping_amount + vads_tax_amount + vads_insurance_amount = vads_amount Si la valeur renseignée dans le champ vads_amount est incorrecte, votre formulaire de paiement est rejeté pour une erreur de montant. 13.Calculez la valeur du champ signature en utilisant l ensemble des champs de votre formulaire, dont le nom commence par vads_ (voir chapitre Calculer la signature). Droit de propriété intellectuelle - 20 / 43

21 7.3. Transmettre les données de l'acheteur Le marchand peut transmettre des informations concernant l acheteur (adresse , civilité, numéro de téléphone etc ). Ces données constitueront les informations de facturation. Toutes les données qui seront transmises via le formulaire de paiement seront affichées dans le Back Office en consultant le détail de la transaction (onglet Acheteur). 1. Utilisez l ensemble des champs nécessaires à votre cas d utilisation (voir chapitre Générer un formulaire de paiement) pour construire votre formulaire de paiement. 2. Utilisez les champs facultatifs ci-dessous en fonction de vos besoins. Ces champs seront renvoyés dans la réponse avec la valeur transmise dans le formulaire. Nom du champ vads_cust_ vads_cust_id vads_cust_title vads_cust_status vads_cust_name vads_cust_first_name vads_cust_last_name vads_cust_legal_name vads_cust_cell_phone vads_cust_phone vads_cust_address_number vads_cust_address vads_cust_district vads_cust_zip vads_cust_city vads_cust_state Description Adresse de l acheteur. Référence de l acheteur sur le site marchand. Civilité de l acheteur. Statut (PRIVATE: pour particulier / COMPANY pour une entreprise). Déprécié. Utilisez vads_cust_first_name et vads_cust_last_name. Prénom. Nom. Raison sociale de l'acheteur. Numéro de téléphone mobile. Numéro de téléphone. Numéro de rue. Adresse postale. Quartier. Code postal. Ville. Etat / Région. vads_cust_country Code pays suivant la norme ISO Tableau 5 : Liste des champs - Détails de l'acheteur 3. Calculez la valeur du champ signature en utilisant l ensemble des champs de votre formulaire, dont le nom commence par vads_ (voir chapitre Calculer la signature). Exemple de formulaire de paiement avec informations sur l'acheteur <form method="post" action=" <input type="hidden" name="vads_action_mode" value="interactive" /> <input type="hidden" name="vads_amount" value="4000" /> <input type="hidden" name="vads_capture_delay" value="0" /> <input type="hidden" name="vads_ctx_mode" value="test" /> <input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_cust_country" value="fr" /> <input type="hidden" name="vads_cust_ " value="dupont.albert@exemple.com" /> <input type="hidden" name="vads_cust_first_name" value="albert" /> <input type="hidden" name="vads_cust_last_name" value="dupont" /> <input type="hidden" name="vads_cust_title" value="m." /> <input type="hidden" name="vads_page_action" value="payment" /> <input type="hidden" name="vads_payment_config" value="single" /> <input type="hidden" name="vads_site_id" value=" " /> <input type="hidden" name="vads_trans_date" value=" " /> <input type="hidden" name="vads_trans_id" value="522754" /> <input type="hidden" name="vads_version" value="v2" /> <input type="hidden" name="signature" value="7896adcaf db9715afa123531f42"/> <input type="submit" name="payer" value="payer"/> </form> Droit de propriété intellectuelle - 21 / 43

22 7.4. Gérer les moyens de paiement proposés à l'acheteur Il est possible de personnaliser les moyens de paiement que vous souhaitez proposer à l acheteur. 1. Utilisez l ensemble des champs nécessaires à votre cas d utilisation (voir chapitre Générer un formulaire de paiement) pour construire votre formulaire de paiement. 2. Valorisez le champ vads_payment_cards en utilisant le tableau ci-dessous (pour plus de valeurs, veuillez-vous référer au guide d'implémentation du formulaire de paiement sur notre site Internet avec une seule valeur si vous ne souhaitez pas afficher la page de sélection des moyens de paiement. avec une liste de valeurs séparées par un ";" pour afficher la page de sélection des moyens de paiements. Valeur ACCORD_STORE ACCORD_STORE_SB ALINEA ALINEA_CDX ALINEA_CDX_SB ALINEA_SB AMEX AURORE-MULTI BANCONTACT BIZZBEE_CDX BIZZBEE_CDX_SB BRICE_CDX BRICE_CDX_SB CB CDGP COF3XCB COF3XCB_SB COFINOGA CORA_BLANCHE CORA_PREM CORA_VISA DINERS E-CARTEBLEUE E_CV IDEAL ILLICADO ILLICADO_SB JCB JOUECLUB_CDX JOUECLUB_CDX_SB JULES_CDX JULES_CDX_SB MAESTRO MASTERCARD ONEY ONEY_SANDBOX PAYLIB Description Carte de paiement Banque Accord Carte de paiement Banque Accord - Sandbox Carte Privative Alinea Carte cadeau Alinea Carte cadeau Alinea - SandBox Carte Privative Alinea - SandBox American Express Carte Aurore Carte Maestro Bancontact Mistercash Carte cadeau Bizzbee Carte cadeau Bizzbee - Sandbox Carte cadeau Brice Carte cadeau Brice - Sandbox CB Carte Privilège 3 fois CB Cofinoga 3 fois CB Cofinoga - Sandbox Carte Be Smart Carte Cora Blanche Carte Cora Premium Carte Cora Visa Carte Diners Club E-carte bleue E-chèque vacance Virement bancaire Carte cadeau Illicado Carte cadeau Illicado - Sandbox Carte JCB Carte cadeau Jouéclub Carte cadeau Jouéclub - Sandbox Carte cadeau Jules Carte cadeau Jules - Sandbox Maestro MasterCard Paiement en 3/4 fois Oney FacilyPay Paiement en 3/4 fois Oney FacilyPay - Sandbox Paylib Droit de propriété intellectuelle - 22 / 43

23 Valeur PAYPAL PAYPAL_SB PAYSAFECARD POSTFINANCE POSTFINANCE_EFIN RUPAY S-MONEY SCT SDD SOFORT_BANKING TRUFFAUT_CDX VISA VISA_ELECTRON Description PayPal PayPal - Sandbox Carte prépayée Paysafecard PostFinance PostFinance mode E-finance Moyen de paiement Indien S-Money Virement SEPA Prélèvement SEPA Sofort Carte cadeau Truffaut Visa Visa Electron 3. Calculez la valeur du champ signature en utilisant l ensemble des champs de votre formulaire, dont le nom commence par vads_ (voir chapitre Calculer la signature ). Exemple de formulaire de paiement avec liste de choix de moyens de paiement: <form method="post" action=" <input type="hidden" name="vads_action_mode" value="interactive" /> <input type="hidden" name="vads_amount" value="30000" /> <input type="hidden" name="vads_capture_delay" value="0" /> <input type="hidden" name="vads_ctx_mode" value="test" /> <input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_page_action" value="payment" /> <input type="hidden" name="vads_payment_cards" value="visa;mastercard;paypal" /> <input type="hidden" name="vads_payment_config" value="single" /> <input type="hidden" name="vads_site_id" value=" " /> <input type="hidden" name="vads_trans_date" value=" " /> <input type="hidden" name="vads_trans_id" value="239848" /> <input type="hidden" name="vads_version" value="v2" /> <input type="hidden" name="signature" value=""/> <input type="submit" name="payer" value="payer"/> </form> Droit de propriété intellectuelle - 23 / 43

24 8. CONTRÔLER LA COHÉRENCE DES CHAMPS Votre formulaire contient le champ vads_amount. Ce champ correspond au montant total de la commande. Afin d'assurer la validité de votre formulaire, la plateforme de paiement vérifie la valeur renseignée. L'équation utilisée est la suivante: Somme ( vads_product_qty(n) x vads_product_amount(n) ) + vads_shipping_amount + vads_tax_amount + vads_insurance_amount = vads_amount Si la valeur renseignée dans le champ vads_amount est incorrecte, votre formulaire de paiement est rejeté pour une erreur de montant. Droit de propriété intellectuelle - 24 / 43

25 9. CALCULER LA SIGNATURE Afin de pouvoir calculer la signature vous devez être en possession de la totalité des champs dont le nom commence par vads_ et du certificat (la valeur du certificat permet de calculer la signature numérique.). Pour calculer la signature : 1. Triez les champs dont le nom commence par vads_ par ordre alphabétique. 2. Assurez-vous que tous les champs soient encodés en UTF Concaténez les valeurs de ces champs en les séparant avec le caractère "+". 4. Concaténez le résultat avec le certificat de test ou de production, en les séparant avec le caractère "+". 5. Appliquez l algorithme SHA-1 pour obtenir la valeur de la signature. Exemple de paramètres envoyés à la plateforme de paiement: <form method="post" action=" <input type="hidden" name="vads_action_mode" value="interactive" /> <input type="hidden" name="vads_amount" value="1524" /> <input type="hidden" name="vads_ctx_mode" value="test" /> <input type="hidden" name="vads_currency" value=value="978" /> <input type="hidden" name="vads_page_action" value="payment" /> <input type="hidden" name="vads_payment_config" value="single" /> <input type="hidden" name="vads_site_id" value=" " /> <input type="hidden" name="vads_trans_date" value=" " /> <input type="hidden" name="vads_trans_id" value="654321" /> <input type="hidden" name="vads_version" value="v2" /> <input type="hidden" name="signature" value="606b369759fac4f c803c73676cbe470ff"/> <input type="submit" name="payer" value="payer"/> </form> Cet exemple de formulaire s'analyse de la manière suivante: 1. On trie par ordre alphabétique les champs dont le nom commence par vads_ : 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 2. On concatène la valeur de ces champs avec le caractère "+" : INTERACTIVE+1524+TEST+978+PAYMENT+SINGLE V2 3. On ajoute la valeur du certificat de test à la fin de la chaîne en la séparant par le caractère "+"). Dans cet exemple, le certificat de Test est : INTERACTIVE+1524+TEST+978++PAYMENT+SINGLE V On applique l algorithme SHA-1 à la chaîne obtenue. Le résultat à transmettre dans le champ signature est : 606b369759fac4f c803c73676cbe470ff. Droit de propriété intellectuelle - 25 / 43

26 10. ENVOYER LA DEMANDE DE PAIEMENT Pour chaque transaction, l acheteur doit être redirigé vers la page de paiement afin de finaliser son achat. Son navigateur doit transmettre les données du formulaire de paiement Rediriger l'acheteur vers la page de paiement L URL de la plateforme de paiement est la suivante : Exemple de paramètres envoyés à la plateforme de paiement: <form method="post" action=" <input type="hidden" name="vads_action_mode" value="interactive" /> <input type="hidden" name="vads_amount" value="2990" /> <input type="hidden" name="vads_capture_delay" value="0" /> <input type="hidden" name="vads_ctx_mode" value="test" /> <input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_cust_country" value="fr" /> <input type="hidden" name="vads_cust_ " value="nom.prenom@exemple.com" /> <input type="hidden" name="vads_page_action" value="payment" /> <input type="hidden" name="vads_payment_config" value="single" /> <input type="hidden" name="vads_site_id" value=" " /> <input type="hidden" name="vads_trans_date" value=" " /> <input type="hidden" name="vads_trans_id" value="362812" /> <input type="hidden" name="vads_validation_mode" value="0" /> <input type="hidden" name="vads_version" value="v2" /> <input type="hidden" name="signature" value="86b2a17b9a5fcefb6c0120c57b25ec86ad1704ee"/> <input type="submit" name="payer" value="payer"/> </form> Gérer les erreurs Si la plateforme détecte une anomalie lors de la réception du formulaire, un message d erreur sera affiché et l acheteur ne pourra pas procéder au paiement. En mode TEST Le message indique l origine de l erreur et propose un lien vers la FAQ pour vous aider à la corriger. En mode PRODUCTION Le message indique simplement à l acheteur qu un problème technique est survenu. Dans les deux cas, le marchand reçoit un d'avertissement. Il contient: l origine de l erreur un lien vers la FAQ pour faciliter le diagnostic l ensemble des champs contenus dans le formulaire. La FAQ est disponible à cette adresse : Droit de propriété intellectuelle - 26 / 43

27 11. ANALYSER LE RÉSULTAT DU PAIEMENT Pour traiter le résultat des paiements, le site marchand doit disposer d'un script sur une page dédiée (exemple : analyse_paiement.php). Cette page sera appelée automatiquement après chaque paiement (accepté ou refusé) : les paramètres liés au résultat du paiement sont envoyés en mode POST par la plateforme de paiement. Prérequis : L'URL de la page qui analyse le résultat du paiement devra obligatoirement être renseignée dans le Back Office (voir chapitre Paramétrer les notifications du guide d'implémentation du formulaire). Le marchand doit s'assurer que cette URL soit joignable par la plateforme de paiement et ce, sans redirection. Les redirections entrainent la perte des données présentes dans le POST. En cas de restriction mise en place du côté du site marchand, il faudra autoriser la plage d'adresses d'ip /24. La page ne devra pas comporter d'affichage HTML. L'accès aux ressources telles que les images ou feuilles de styles peuvent ralentir les échanges entre la plateforme de paiement et le site marchand. De plus, la plateforme lit systématiquement les 512 premiers caractères retournés par le site marchand. Ces caractères sont ensuite affichés dans l'historique des transactions. Evitez au maximum d'intégrer des tâches consommatrices de temps comme la génération de facture ou l'envoi d' dans ce script. Le temps du traitement influe directement sur le délai de l affichage de la page de résumé du paiement. Plus le traitement de la notification est long, plus l affichage est retardé. Au delà de 35s, la plateforme considèrera que l'appel a échoué (timeout). Echec de notification (IPN) En cas d'échec de l'appel à l URL de notification (IPN), un d'avertissement est envoyé à l adresse spécifiée dans le Back Office (voir chapitre Paramétrer les notifications du guide d'implémentation du formulaire). Il contient : le code HTTP de l erreur rencontrée, des éléments d analyses en fonction de l erreur, la procédure à suivre depuis le Back Office pour renvoyer la notification. Concevoir le script de traitement Le script de traitement devra comporter au moins les étapes ci-dessous: Récupérer la liste des champs présents dans la réponse envoyée en POST Calculer la signature Comparer la signature calculée avec celle réceptionnée Analyser la nature de la notification Droit de propriété intellectuelle - 27 / 43

28 Récupérer le résultat du paiement Le script peut par exemple tester l'état de la commande (ou l'information de votre choix) pour vérifier qu'elle n'ait pas déja été mise à jour. Une fois ces étapes réalisées, le script peut mettre à jour la base de données (nouvel état de la commande, mise à jour du stock, enregistrement des informations du paiement etc...) Récupérer les données retournées dans la réponse Les données retournées dans la réponse dépendent des paramètres envoyés dans le formulaire de paiement, du type de paiement réalisé et des options de votre boutique. Ces données constituent une liste de champs. Chaque champ contient une valeur réponse. La liste de champs peut être amenée à évoluer. Les données sont toujours envoyées en POST par la plateforme de paiement. Exemples : En PHP, les données seront stockées dans la super globale $_POST. En ASP.NET (C#), vous devez utiliser la propriété Form de la classe HttpRequest. En java, vous devez utiliser la méthode getparameter de l'interface HttpServletRequest. Le script devra effectuer une boucle pour récupérer la totalité des champs transmis Calculer la signature La signature se calcule selon la même logique utilisée lors de la création du formulaire de paiement. Tous les champs reçus doivent être pris en compte. Pour calculer la signature: 1. Prenez en considération la totalité des champs dont le nom commence par vads_. 2. Triez ces champs par ordre alphabétique. 3. Assurez-vous que tous les champs soient encodés en UTF Concaténez le résultat avec le certificat de test ou de production, en les séparant avec le caractère "+". 5. Appliquez l algorithme SHA-1 pour obtenir la valeur de la signature Comparer les signatures Pour s assurer de l intégrité de la réponse, vous devez comparer la valeur du champ signature reçue dans la réponse, avec celle calculée à l étape précédente. Si les signatures correspondent, alors vous pouvez considérer la réponse comme sûre et procéder à la suite de l analyse. sinon, le script devra lever une exception et avertir le marchand de l'anomalie (voir chapitre Traiter les erreurs). Droit de propriété intellectuelle - 28 / 43

29 Les signatures ne correspondent pas en cas : d erreur d'implémentation (erreur dans votre calcul, problème d encodage UTF8, etc.). d erreur dans la valeur du certificat utilisé ou dans celle du champ vads_ctx_mode (problème fréquent lors du passage en production). de tentative de corruption des données Analyser la nature de la notification Le champ vads_url_check_src permet de différencier les notifications en fonction de leur évènement déclencheur : création d'une transaction. renvoi de la notification depuis le Back Office par le marchand. Il précise la règle de notification appliquée : Valeur Règle appliquée PAY La valeur PAY sera envoyée dans les cas suivants : demande d'enregistrement d'un (REGISTER) paiement immédiat (paiement comptant ou première échéance d'un paiement en plusieurs fois) paiement différé à moins de 7 jours uniquement si le marchand a configuré la règle URL de notification à la fin du paiement. paiement abandonné ou annulé par l'acheteur uniquement si le marchand a configuré la règle URL de notification sur annulation. BO BATCH_AUTO Exécution de la notification depuis le Back Office (clic droit sur une transaction > Executer l'url de notification). La valeur BATCH_AUTO sera envoyée dans les cas suivants: REC paiement différé à plus de 7 jours échéances d'un paiement en plusieurs fois (hormis la première) uniquement si le marchand a configuré la règle URL de notification sur autorisation par batch. La notification sera envoyée lors de la demande d autorisation d'un paiement dont le statut est "En attente d autorisation". La valeur REC sera envoyée uniquement pour les paiements par abonnement si le marchand a configuré la règle URL de notification à la création d'un paiement par récurrence. MERCH_BO La valeur MERCH_BO sera envoyée : lors d'une opération réalisée depuis le Back Office (remboursement, modification, validation, duplicata), si le marchand a configuré la règle de notification : URL de notification sur une opération provenant du Back Office lors d'une annulation réalisée depuis le Back Office, si le marchand a configuré la règle de notification : URL de notification sur annulation Tableau 6 : Valeurs associées au champ vads_url_check_src En testant sa valeur, le script pourra réaliser un traitement différent en fonction de la nature de la notification. Par exemple : Si vads_url_check_src est valorisé à PAY ou BATCH_AUTO alors le script mettra à jour le statut de la commande,... Si vads_url_check_src est valorisé à REC alors le script récupèrera la référence de l'abonnement et incrémentera le nombre d'échéances échues en cas de paiement accepté,... Droit de propriété intellectuelle - 29 / 43

30 11.5. Identifier le type d'opération Le champ vads_operation_type permet de différencier : une opération de débit. une opération de remboursement. Valeur DEBIT CREDIT Description Opération de débit. Opération de remboursement. Tableau 7 : Valeur du champ vads_operation_type Par exemple : Si vads_operation_type est valorisé à DEBIT, le script met à jour la commande et enregistre les informations de la transaction. Si vads_operation_type est valorisé à CREDIT, le script met à jour le montant payé ou ajoute une nouvelle ligne de transaction dans la commande. Droit de propriété intellectuelle - 30 / 43

31 11.6. Traiter les données de la réponse - Paiement différé PayPal Ci-dessous un exemple d'analyse pour vous guider pas à pas lors du traitement des données de la réponse. 1. Identifiez le résultat du paiement en récupérant la valeur du champ vads_trans_status. Valeur ABANDONED AUTHORISED AUTHORISED_TO_VALIDATE CANCELED CAPTURED EXPIRED REFUSED WAITING_AUTHORISATION WAITING_AUTHORISATION_TO _VALIDATE UNDER_VERIFICATION NOT_CREATED Description Le paiement a été abandonné par l acheteur. La transaction n a pas été créée et n est donc pas visible dans le Back Office. En attente de remise La transaction est acceptée et sera remise en banque automatiquement à la date prévue. A valider La transaction, créée en validation manuelle, est autorisée. Le marchand doit valider manuellement la transaction afin qu'elle soit remise en banque. La transaction peut être validée tant que la date de remise n est pas dépassée. Si cette date est dépassée alors le paiement prend le statut Expiré. Le statut Expiré est définitif. Annulée La transaction est annulée par le marchand. Remisée La transaction est remise en banque. Expirée La date de remise est atteinte et le marchand n a pas validé la transaction. Refusée La transaction est refusée. En attente d autorisation Une autorisation d un euro est réalisée et acceptée par la banque émettrice. La demande d autorisation sera déclenchée automatiquement à J-1 avant la date de remise en banque. Le paiement pourra être accepté ou refusé. La remise en banque est automatique. A valider et autoriser Le délai de remise en banque est supérieur à la durée de validité de l'autorisation. Une autorisation d un euro a été acceptée. Le marchand doit valider manuellement la transaction afin que la demande d autorisation et la remise aient lieu. Spécifique à PayPal En attente de vérification par PayPal PayPal retient la transaction pour suspicion de fraude. Le paiement est alors dans l onglet Paiement en cours. La transaction n'est pas créée et n'est pas visible dans le Back Office. Tableau 8 : Valeurs associées au champ vads_trans_status 2. Enregistrez la commande en identifant la valeur du champ vads_order_id si vous l'avez transmis dans le formulaire de paiement. 3. Enregistrez la référence du paiement en identifiant la valeur du champ vads_trans_id. 4. Sauvegardez la valeur du champ vads_trans_date pour identifier la date de création de la transaction. 5. Sauvegardez la valeur du champ vads_presentation_date pour identifier la date de présentation du paiement. 6. Sauvegardez le montant et la devise utilisés. Pour cela, récupérez les valeurs des champs suivants: Droit de propriété intellectuelle - 31 / 43

32 Nom du champ vads_amount vads_currency vads_change_rate vads_effective_amount Description Montant du paiement dans sa plus petite unité monétaire. Code de la devise utilisée pour le paiement. Taux de change utilisé. Montant du paiement dans le devise réellement utilisée pour effectuer la remise en banque. 7. Enregistrez le mode et le résultat de l'autorisation. Pour cela: a. Sauvegardez la valeur du champ vads_auth_mode pour identifier le mode dans lequel a été effectué la demande d'autorisation. Valeur FULL MARK Description Une demande d autorisation a été réalisée pour le montant total. Une demande de préautorisation du montant de la transaction a été réalisée pour vérifier la validité du moyen de paiement. Tableau 9 : Valorisations du champ vads_auth_mode b. Sauvegardez la valeur du champ vads_auth_result pour connaître le résultat de la demande d'autorisation. Pour une autorisation acceptée, le champ vads_auth_result est valorisé à 00. Tout autre résultat indique que l'autorisation est refusée. Pour vous aider à comprendre les différentes valeurs caractérisant le résultat de la demande d'autorisation, voici une liste des codes fréquemment retournés : Valeur Description 00 Autorisation acceptée 03 Accepteur invalide Ce code est émis par la banque du marchand. Il correspond à un problème de configuration sur les serveurs d autorisation. (Ex: contrat clos, mauvais code MCC déclaré, etc..). Contactez le service client pour régulariser la situation. 05 Ne pas honorer Ce code est émis par la banque émettrice de la carte. Il peut être obtenu en général dans les cas suivants : Date d expiration invalide, CVV invalide, crédit dépassé, solde insuffisant (etc...) Pour connaître la raison précise du refus, l acheteur doit contacter sa banque. 51 Provision insuffisante ou crédit dépassé Ce code est émis par la banque émettrice de la carte. Ce code peut être obtenu si l acheteur ne dispose pas d un solde suffisant pour réaliser son achat. Pour connaître la raison précise du refus, l acheteur doit contacter sa banque. 56 Carte absente du fichier Ce code est émis par la banque émettrice de la carte. Le numéro de carte saisi est erroné ou le couple numéro de carte + date d'expiration n'existe pas. 57 Transaction non permise à ce porteur Ce code est émis par la banque émettrice de la carte. Ce code peut être obtenu en général dans les cas suivants : L acheteur tente d effectuer un paiement sur internet avec une carte de retrait, Le plafond d autorisation de la carte est dépassé. Pour connaître la raison précise du refus, l acheteur doit contacter sa banque. 59 Suspicion de fraude Ce code est émis par la banque émettrice de la carte. Ce code peut être obtenu en général suite à une saisie répétée de CVV ou de date d expiration erronée. Pour connaître la raison précise du refus, l acheteur doit contacter sa banque. Droit de propriété intellectuelle - 32 / 43