Ajouter le bouton de paiement FullCB Guide d'implémentation

Transcription

1 Ajouter le bouton de paiement FullCB Guide d'implémentation Version du document 1.2

2 Sommaire 1. HISTORIQUE DU DOCUMENT CONTACTER L'ASSISTANCE TECHNIQUE FULLCB : PAYER EN 3 OU 4 FOIS PAR CARTE BANCAIRE PROPOSER LA SOLUTION FULLCB SUR LA PAGE DE PAIEMENT Prérequis Comprendre le déroulement d'un paiement FullCB Afficher le détail d'une transaction FullCB depuis le Back Office Marchand ÉTABLIR LE DIALOGUE AVEC LA PLATEFORME DE PAIEMENT SE CONNECTER AU BACK OFFICE MARCHAND CONFIGURER LES NOTIFICATIONS Configurer la notification à la fin du paiement Configurer la notification en cas d'abandon/annulation Configurer la notification sur modification par batch Activer le rejeu automatique GÉNÉRER VOTRE FORMULAIRE DE PAIEMENT Construire votre formulaire de paiement FullCB 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 Calculer la signature Comparer les signatures Traiter les données spécifiques à la réponse d'un paiement FullCB IDENTIFIER LES OPÉRATIONS AUTORISÉES SUR LES TRANSACTIONS Effectuer un remboursement sur une transaction remisée Renvoyer l' de confirmation de la transaction au marchand Renvoyer l' de confirmation de la transaction à l'acheteur... 31

3 1. HISTORIQUE DU DOCUMENT Version Auteur Date Commentaire 1.2 Lyra Network 16/01/2018 Ajout des chapitres Établir le dialogue avec la plateforme de paiement Configurer les notifications et sous chapitres Calculer la signature Comparer les signatures 1.1 Lyra Network 07/06/2017 Mise à jour du document 1.0 Lyra Network 30/03/2017 Création du document Ce document et son contenu sont strictement confidentiels. Il n est pas contractuel. Toute reproduction et/ou distribution de ce document ou de toute ou partie de son contenu à une entité tierce sont strictement interdites ou sujettes à une autorisation écrite préalable de Lyra Network. Tous droits réservés. Tous droits réservés - 3 / 31

4 2. CONTACTER L'ASSISTANCE TECHNIQUE Vous cherchez de l'aide? Consultez notre FAQ sur notre site 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 via votre Back Office Marchand : support@payzen.eu menu Aide > Contacter le support 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 Marchand (menu Paramétrage > Boutique > Configuration). Tous droits réservés - 4 / 31

5 3. FULLCB : PAYER EN 3 OU 4 FOIS PAR CARTE BANCAIRE PayZen a enrichi sa plateforme de paiement en y intégrant la solution de paiement FullCB, moyen de paiement en 3 ou 4 fois par carte bancaire avec BNPP Personal Finance. Le paiement en 3 ou 4 fois par carte bancaire avec BNPP Personal Finance permet à un acheteur de financer ses achats en ligne en toute sécurité. Cette solution propose ainsi aux acheteurs une facilité de paiement pour échelonner le réglement de leur commande en 3 ou 4 fois. Des frais de dossiers existent sous la forme suivante : Pour un paiement en 3x : 1,4 % du montant de l'achat avec un plafonnement à 9 euros. Pour un paiement en 4x : 2,1 % du montant de l'achat avec un plafonnement à 12 euros. Ces frais de dossiers sont à régler par l'acheteur sauf si le marchand propose une opération sans frais. Dans ce cas, les frais de dossiers sont pris en charge entièrement par le marchand. Pour proposer la solution à ses clients, le marchand est redevable d une commission de paiement contributive d une partie de la charge du coût du risque qui est fixée contractuellement avec BNPP Personal Finance. Une réponse de principe est fournie immédiatement à l'acheteur au moment de l'achat. Si cette réponse est positive : Le marchand est crédité du montant de la commande selon les conditions établies avec BNPP Personal Finance. L'acheteur est débité de la 1ère échéance. Si le marchand n'offre pas les frais de dossiers, ils seront débités de cette échéance. BNPP Personal Finance se charge de récupérer les mensualités auprès de l'acheteur. Il débitera les 2 ou 3 échéances restantes. Cette facilité de paiement porte sur une durée de moins de 90 jours, elle n est donc pas soumise à la réglementation du crédit consommation. Tous droits réservés - 5 / 31

6 4. PROPOSER LA SOLUTION FULLCB SUR LA PAGE DE PAIEMENT Informations importantes relatives à l'ajout de ce moyen de paiement : Type d'intégration Uniquement disponible via une intégration par formulaire de paiement en redirection. Restriction Pas d'intégration possible via les Web Services. Nom du champ pour personnaliser la liste des moyens de paiement vads_payment_cards Valeur de vads_payment_cards FULLCB3X ou FULLCB4X Exemple Pour proposer par exemple Visa, MasterCard et FullCB sur la page de paiement, la ligne de code dans le formulaire de paiement est la suivante : <input type="hidden" name="vads_payment_cards" value="visa;mastercard;fullcb3x;fullcb4x" /> Remarque : Si la liste ne contient qu'un type de carte, la page de saisie des données de ce moyen de paiement sera directement présentée. Sinon la page de sélection des moyens de paiement sera présentée. Si ce paramètre est vide (conseillé) alors tous les moyens de paiement éligibles (devises, contraintes techniques, etc.) associés à la boutique seront proposés Prérequis Côté marchand Faire la demande auprès de BNPP Personal Finance. Obtenir son N d agrément FullCB. Avoir le type de paiement autorisé. En fonction du type de contrat souscrit, le marchand sera autorisé à proposer : soit le paiement en 3 fois. soit le paiement en 3 fois et le paiement en 4 fois. Le paiement FullCB n'est proposé à l'acheteur que si le montant de la commande se situe dans une fourchette définie par BNPP Personal Finance. Les montants minimum et maximum sont fixés par marchand et sont entre 100 et 1500 euros. Côté acheteur Souscrire à la solution en acceptant le paiement des frais de dossier auprès de BNPP Personal Finance, dans le parcours de paiement. Rappel : si le marchand offre les frais de dossier, l'acheteur n'aura pas à les payer. Tous droits réservés - 6 / 31

7 Avoir en possession une carte d'identité en période de validité et accepter de fournir les informations personnelles requises au moment de l'achat. Faire un versement comptant obligatoire par carte bancaire de 1/3 du montant de l achat et le solde en 2 mensualités égales sans intérêt pour du 3xCB. de 25% du montant de l achat et le solde en 3 mensualités égales sans intérêt pour du 4xCB. Remarque : Seules les cartes mastercard, Visa et CB dont la durée de validité restante est d'au moins 6 mois, peuvent être acceptées au moment de l'achat. En revanche, les cartes Visa Electron, VPAY, maestro, American Express, e-carte Bleue, cartes étrangères, cartes exclusivement de retrait et cartes virtuelles de paiement ne sont pas acceptées Comprendre le déroulement d'un paiement FullCB 1. L'acheteur valide son panier. Image 1 : Cinématique d'un paiement Full CB 2. L'acheteur renseigne les informations de livraison et de facturation (nom, prénom, adresse, etc.) 3. Le site marchand redirige l'acheteur vers la plateforme de paiement. Cette redirection s'effectue 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 une demande de paiement du Guide d'implémentation API Formulaire disponible sur notre site documentaire. La plateforme de paiement, après vérification des paramètres et de leur signature, présente la page de paiement. 4. L'acheteur sélectionne le moyen de paiement : Paiement en 3 fois CB Paiement en 4 fois CB Tous droits réservés - 7 / 31

8 La plateforme redirige l'acheteur vers la page de paiement Cetelem, la marque commerciale de l'organisme de paiement BNPP Personal Finance. 5. L'acheteur complète le formulaire avec ses informations personnelles. Remarque : les frais de dossiers éventuels et l'échéance de paiement sont présentés dans cette page dès cette étape. Dans le cas où les frais de dossier sont offerts par le marchand, le montant sera valorisé à 0. Les champs requis dans le formulaire sont listés ci-dessous. Certaines informations comme le nom, le prénom et l'adresse complète sont déjà préremplies dans le formulaire. Ville Nationalité Civilité Téléphone Type de pièce d'identité Nom Date de naissance N de la pièce Prénom Pays de naissance Délivrée le Adresse Département de naissance Code postal Ville de naissance Date de délivrance de la pièce d'identité Tous droits réservés - 8 / 31

9 6. L'acheteur saisit ses coordonnées bancaires pour le paiement de la première échéance. La page de paiement reste grisée tant que les informations personnelles ne sont pas valides. Dans le cas d'un paiement favorable, l'ensemble des contrôles est réalisé en temps réel, l'authentification 3DS est systématique. 7. L'acheteur valide les conditions générales du contrat de financement et la demande de mise en œuvre immédiate. 8. L'acheteur clique sur Suivant pour afficher le récapitulatif. 9. L'acheteur vérifie les données saisies et clique sur Valider mon paiement. Il a encore la possibilité de modifier ses informations personnelles à ce niveau. Tous droits réservés - 9 / 31

10 10.La plateforme de paiement affiche le résultat de la transaction. L'acheteur est redirigé vers la plateforme PayZen. En cas de succès, les détails du paiement sont présentés à l'acheteur avec la possibilité de télécharger le ticket en format PDF. En cas d'échec, un message s'affiche. L'acheteur est informé du refus de la demande de paiement. Un lien permet de retourner à la boutique Afficher le détail d'une transaction FullCB depuis le Back Office Marchand Les transactions sont visibles dans le Back Office Marchand depuis le menu Gestion > Transactions. Depuis le menu Gestion, le marchand a accès aux transactions réelles et aux transactions de TEST. Remarque : Suivant ses droits d accès, les transactions de TEST (exemple : profil développeur) et/ou les transactions réelles (exemple : profil comptable) peuvent s'afficher. Par défaut l interface affiche le contenu de l onglet Transactions en cours. Il liste toutes les transactions de la journée. Si vous souhaitez visualiser les paiements remis en banque, cliquez sur l onglet Transactions remisées. Pour visualiser le détail d'une transaction : 1. Sélectionnez une transaction FullCB. Tous droits réservés - 10 / 31

11 2. Effectuez un clic droit puis sélectionnez Afficher le détail de la transaction ou double cliquez sur la transaction à visualiser.. La boîte de dialogue Détail d'une transaction apparaît. Image 2 : Exemple de détail d'une transaction remisée Parmi les informations présentées, vous trouverez Le moyen de paiement utilisé L'identifiant de la transaction Le montant de la transaction Rappel : BNPP Personal Finance crédite le marchand de la totalité de la transaction. la date de création de la transaction La date de remise demandée le statut de la transaction Tous droits réservés - 11 / 31

12 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 API Formulaire disponible sur le site documentaire. Le dialogue entre le site marchand et la plateforme de paiement s effectue par un échange de données. Pour créer un paiement, ces données sont envoyées au moyen d'un formulaire HTML via le navigateur de l acheteur. A la fin du paiement, le résultat est transmis au site marchand de deux manières : automatiquement au moyen de notifications appelées URL de notification instantanée (également appelée IPN pour Instant Payment Notification). par le navigateur lorsque l acheteur clique sur le bouton pour revenir au site marchand. Pour assurer la sécurité des échanges, les données sont signées au moyen d une clé (anciennement appelée "certificat") connue uniquement du marchand et de la plateforme de paiement. Tous droits réservés - 12 / 31

13 6. SE CONNECTER AU BACK OFFICE MARCHAND Votre Back Office est accessible à l adresse URL suivante : 1. Saisissez votre identifiant de connexion. Votre identifiant de connexion vous a été communiqué par ayant pour objet Identifiants de connexion - [nom de votre boutique]. 2. Saisissez votre mot de passe. Votre mot de passe vous a été communiqué par ayant pour objet Identifiants de connexion - [nom de votre boutique]. 3. Cliquez sur Valider. Au bout de 3 erreurs dans la saisie du mot de passe, le compte de l utilisateur est bloqué. Cliquez alors sur Mot de passe oublié ou compte bloqué pour réinitialiser. Tous droits réservés - 13 / 31

14 7. CONFIGURER LES NOTIFICATIONS Plusieurs types de notifications sont mises à disposition dans le Back Office Marchand. Elle permettent de gérer les évènements (abandon par l'acheteur, annulation par le marchand, validation par le marchand...) qui génèreront un appel vers le site marchand et de configurer l'url de la page à contacter. Pour accéder à la gestion des règles de notification : 1. Allez dans le menu : Paramétrage > Règles de notifications. Image 3 : Règles de notification 7.1. Configurer la notification à la fin du paiement Dans votre Back Office Marchand, vous devez paramétrer une URL qui sera systématiquement appelée après un paiement. Elle informera le site marchand du résultat du paiement même si votre client n a pas cliqué sur retour à la boutique. Ce paramètre s appelle URL de notification à la fin du paiement. Pour paramétrer cette notification : 1. Effectuez un clic droit sur la ligne URL de notification à la fin du paiement. 2. Sélectionnez Activer la règle. 3. Effectuez à nouveau un clic droit sur URL de notification à la fin du paiement. 4. Sélectionnez Gérer la règle. 5. Renseignez l URL de votre page dans les champs URL à appeler en mode TEST et URL à appeler en mode PRODUCTION. 6. Renseignez le champ Adresse(s) (s) à avertir en cas d échec. 7. Pour spécifier plusieurs adresses s, séparez-les par un point-virgule. Tous droits réservés - 14 / 31

15 8. Configurez le Rejeu automatique en cas d échec. Cette option permet de renvoyer automatiquement la notification vers le site marchand en cas d'échec, et ce, jusqu'à 4 fois. Pour plus d'informations, reportez-vous au chapitre Activer le rejeu automatique du Guide d'implémentation API Formulaire. 9. Sauvegardez vos modifications. Si la plateforme n'arrive pas à joindre l'url de votre page, alors un est envoyé à l'adresse spécifiée. Il contient : Le code HTTP de l'erreur rencontrée Des éléments d'analyse en fonction de l'erreur Ses conséquences La procédure à suivre depuis le Back Office Marchand pour renvoyer la requête vers l URL déjà définie plus haut Configurer la notification en cas d'abandon/annulation La plateforme de paiement peut notifier systématiquement le site marchand : En cas d abandon/annulation de la part de l acheteur, via le bouton Annuler et retourner à la boutique. Lorsque l'acheteur n'a pas terminé son paiement avant l'expiration de sa session de paiement. La durée maximale d'une session de paiement est de 10 minutes. Pour paramétrer cette notification : 1. Effectuez un clic droit sur la ligne URL de notification sur annulation. 2. Sélectionnez Gérer la règle. 3. Renseignez l URL de votre page dans les champs URL à appeler en mode TEST et URL à appeler en mode PRODUCTION. 4. Renseignez Adresses(s) (s) à avertir en cas d échec. 5. Pour spécifier plusieurs adresses séparez-les par un point-virgule. 6. Configurez le Rejeu automatique en cas d échec. Cette option permet de renvoyer automatiquement la notification vers le site marchand en cas d'échec, et ce, jusqu'à 4 fois. 7. Sauvegardez vos modifications. Si la plateforme n'arrive pas à joindre l'url de votre page, alors un est envoyé à l'adresse spécifiée. Il contient : Le code HTTP de l'erreur rencontrée Des éléments d'analyse en fonction de l'erreur Ses conséquences Tous droits réservés - 15 / 31

16 La procédure à suivre depuis le Back Office Marchand pour renvoyer la requête vers l URL déjà définie plus haut. Tous droits réservés - 16 / 31

17 7.3. Configurer la notification sur modification par batch Dans le cas où vous avez activé le moyen de paiement Oney, vous devez activer cette règle pour que votre site marchand soit averti de l acceptation ou du refus des commandes de la part d'oney. Cette règle est désactivée par défaut. Il est recommandé d'activer cette notification pour des transactions Klarna afin d'être notifié de la remise. Le champ ocrnumber est retourné parmi les données véhiculées Pour paramétrer cette notification : 1. Effectuez un clic droit sur la ligne URL de notification sur modification par batch. 2. Sélectionnez Gérer la règle. 3. Renseignez l URL de votre page dans les champs URL à appeler en mode TEST et URL à appeler en mode PRODUCTION. 4. Renseignez le champ Adresse(s) (s) à avertir en cas d échec. 5. Configurez le Rejeu automatique en cas d échec. Cette option permet de renvoyer automatiquement la notification vers le site marchand en cas d'échec, et ce, jusqu'à 4 fois. 6. Sauvegardez vos modifications. 7. Activez la règle, en effectuant un clic droit sur URL de notification sur modification par batch et sélectionnez Activer la règle. Si la plateforme n'arrive pas à joindre l'url de votre page, alors un est envoyé à l'adresse spécifiée. Il contient : Le code HTTP de l'erreur rencontrée Des éléments d'analyse en fonction de l'erreur Ses conséquences La procédure à suivre depuis le Back Office Marchand pour renvoyer la requête vers l URL déjà définie plus haut Activer le rejeu automatique Cette option permet de renvoyer automatiquement la notification vers le site marchand en cas d'échec, et ce, jusqu'à 4 fois. Une notification sera considérée en échec si le code retour HTTP renvoyé par le serveur marchand ne fait pas partie de la liste suivante: 200, 201, 202, 203, 204, 205, 206, 301, 302. Les codes retours HTTP sont standardisés par le W3C dans le RFC Le rejeu automatique ne s'applique pas aux notifications déclenchées manuellement depuis le Back Office Marchand. Pour activer le rejeu automatique : 1. Depuis le Back Office Marchand, allez dans le menu : Paramétrage > Règles de notifications. 2. Effectuez un clic droit sur une des règles de notifications affichées. Tous droits réservés - 17 / 31

18 3. Sélectionnez Gérer la règle. 4. Renseignez le champ Adresse(s) (s) à avertir en cas d échec. 5. Configurez le Rejeu automatique en cas d échec. Les tentatives d'appel sont programmées à heures fixes toutes les 15 minutes (00, 15, 30, 45). Après chaque tentative infructueuse, un d'alerte est envoyé à l'adresse saisie précédemment. L'objet de l' d'alerte contient le numéro de la tentive d'envoi de la notification. Il est présenté sous la forme attempt # suivi du numéro de tentative. Exemple d'objet d'un d'alerte reçu suite au premier échec de notification à la fin d'un paiement : [MODE TEST] Ma Boutique - Tr. réf / ECHEC lors de l'appel de votre URL de notification [unsuccessful attempt #1] Exemple d'objet d' reçu lors d'un deuxième échec : [MODE TEST] Ma Boutique - Tr. réf / ECHEC lors de l'appel de votre URL de notification [unsuccessful attempt #2] Exemple d'objet d' reçu lors d'un troisième échec : [MODE TEST] Ma Boutique - Tr. réf / ECHEC lors de l'appel de votre URL de notification [unsuccessful attempt #3] Pour notifier au site marchand l'échec de la dernière tentative de notification, l'objet de l' comportera la mention attempt #last. Exemple d'objet d' reçu lors de la dernière tentative : [MODE TEST] Ma Boutique - Tr. réf / ECHEC lors de l'appel de votre URL de notification [unsuccessful attempt #last] Pour chacun des s reçus, le contenu de l' détaillera : le problème rencontré des éléments d'analyse en fonction de l'erreur ses conséquences la procédure à suivre depuis le Back Office Marchand pour renvoyer la requête vers l URL définie à l étape 4 Remarque : Après la quatrième tentative, il est toujours possible de rejouer l'url de notification. Ceci peut être effectué manuellement depuis votre Back Office Marchand. Attention, pendant la période de rejeu automatique, tout appel manuel à l'url de notification influera sur le nombre de tentatives automatiques : un appel manuel réussi provoquera l'arrêt du rejeu automatique un appel manuel en échec n'aura aucun impact sur le rejeu automatique en cours. 6. Sauvegardez vos modifications. Remarque : Lors du rejeu automatique, certaines informations ne sont pas enregistrées en base de données ou sont modifiées. Exemples de champs non disponibles / non enregistrés en base de données : vads_page_action Tous droits réservés - 18 / 31

19 vads_payment_config vads_action_mode Exemples de champs envoyés avec des valeurs différentes : vads_url_check_src valorisé à RETRY vads_trans_status. Le statut de la transaction suite à cette opération varie en fonction de son statut au moment où l'url est appelée vads_hash valorisé différemment en tenant compte des nouvelles valeurs signature valorisé différemment en tenant compte des nouvelles valeurs Tous droits réservés - 19 / 31

20 8. GÉNÉRER VOTRE 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 (voir chapitre Calculer la signature). 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 API 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"/> 8.1. Construire votre formulaire de paiement FullCB L intégration du paiement 3-4 fois par carte bancaire avec FullCB nécessite la transmission d un certain nombre de paramètres dans le formulaire de paiement, ainsi que certaines restrictions sur les paramètres existants. Nous indiquons ici les paramètres qui sont pris en compte pour un paiement FullCB avec leurs éventuelles restrictions. 1. Utilisez les champs présents dans le tableau ci-dessous pour valoriser les informations techniques obligatoires sur le formulaire de paiement. Nom du champ Description Format Requis Valeur vads_action_mode Mode d acquisition des données de la carte string (enum) oui INTERACTIVE Tous droits réservés - 20 / 31

21 Nom du champ Description Format Requis Valeur vads_ctx_mode Mode de fonctionnement string (enum) oui Les valeurs possibles sont : - TEST pour des transactions de test. - PRODUCTION pour des transactions réelles. vads_page_action Action à réaliser string (enum) oui PAYMENT vads_site_id Identifiant de la boutique n8 oui Ex : vads_version Version du protocole d échange string (enum) oui V2 Précisions sur certains champs : vads_action_mode Seule la valeur INTERACTIVE peut être valorisée. Il s'agit d'un paiement avec redirection. L'acheteur saisit les informations de la carte sur la page de paiement. vads_page_action Seule la valeur PAYMENT peut être valorisée. Cette valeur permet de réaliser des paiements. 2. Utilisez les champs présents dans le tableau ci-dessous pour valoriser les informations obligatoires sur la transaction devant figurer dans le formulaire de paiement. Nom du champ Description Format Requis Valeur vads_amount Montant du paiement (dans sa plus petite unité monétaire) n..12 oui Ex : 3000 pour 30,00 EUR vads_capture_delay Délai avant remise en banque n..3 oui 0 Remarque : tout délai de remise supérieur à 0 jour spécifié dans le requête sera ignoré car il s'agit d'un débit immédiat. vads_currency Code de la devise Euro n3 oui 978 vads_payment_config Type de paiement string (enum) oui SINGLE vads_trans_id Numéro de la transaction n6 oui Ex : vads_order_id Numéro de la commande an9 oui Ex : vads_validation_mode Mode de validation string (enum) oui 0 vads_trans_date Précisions sur certains champs : vads_currency Date et heure UTC du formulaire de paiement Seule la devise Euro peut être valorisée. Son code est 978. vads_trans_id n14 oui Ex : Cet identifiant est composé de 6 caractères numérique et doit être unique pour chaque transaction pour une boutique donnée sur la journée. vads_validation_mode Seule la validation automatique peut être paramétrée. Le paiement sera remis de manière automatique à la banque. 3. Utilisez les champs présents dans le tableau ci-dessous pour valoriser les informations obligatoires sur l'acheteur devant figurer dans le formulaire de paiement. Afin de faciliter le parcours client, les informations saisies seront récupérées pour pré-renseigner le formulaire de demande de crédit que l'acheteur doit remplir. Nom du champ Description Format Requis Valeur vads_cust_title Civilité de l'acheteur string Ex : M, Mme ou Mlle vads_cust_last_name Nom de l'acheteur an..63 oui Ex : Dupont Tous droits réservés - 21 / 31

22 Nom du champ Description Format Requis Valeur vads_cust_first_name Prénom de l'acheteur an..63 oui Ex : Jean vads_cust_address Rue de l acheteur. Peut contenir espace, virgule, point, apostrophe, tiret et slash (/) ans..255 oui Ex : rue du test vads_cust_zip Code postal de l acheteur n5 oui Ex : vads_cust_city vads_cust_cell_phone vads_cust_phone vads_cust_country Ville de l acheteur Peut contenir espace, slash, tiret et apostrophe. Numéro de téléphone portable de l'acheteur de 0 à 9 sans espace Remarque : au moins un des deux champs vads_cust_cell_phone et vads_cust_phone est obligatoire Numéro de téléphone de l'acheteur sans espace Permet de spécifier le code du pays de l acheteur à la norme ISO Seul le code pays de la France peut être valorisé. an..128 oui Ex : Toulouse n10 Ex : n10 Ex : a2 oui FR vads_cust_ Adresse de l acheteur. ans..255 oui Ex: prenom.nom@exemple.fr vads_cust_id Référence de l acheteur sur le site marchand. Cette référence ne doit comporter ni espace, ni caractère spécial ou accentué. an..8 Ex : vads_cust_status Type d'acheteur string (enum) oui PRIVATE Précisions sur certains champs : vads_cust_country Seule la France peut être valorisée. Son code (norme ISO 3166) est FR. vads_cust_status Seule la valeur PRIVATE peut être valorisée (particulier). Une société (COMPANY) ne peut bénéficier de ce moyen de paiement. 4. Utilisez les champs présents dans le tableau ci-dessous pour valoriser les informations sur la livraison devant figurer dans le formulaire de paiement. Si les informations de livraison ne sont pas paramétrées alors les champs requis pour l'adresse de facturation seront automatiquement utilisés. Nom du champ Description Format Valeur vads_ship_to_city Ville an..128 Toulouse vads_ship_to_country Code pays suivant la norme ISO 3166 a2 FR vads_ship_to_delay Délai de livraison string (enum) Ex : IMMEDIATE Donnée obligatoire si le champ vads_ship_to_speed est valorisé à PRIORITY vads_ship_to_delivery_ company_name Nom du transporteur ans..127 Ex : mon transporteur vads_ship_to_first_name Prénom ans..63 Jean vads_ship_to_last_name Nom ans..63 Dupont vads_ship_to_phone_num Numéro de téléphone n10 Ex : vads_ship_to_speed Mode de livraison (rapidité) string (enum) Ex : STANDARD vads_ship_to_status Type d'adresse de livraison string (enum) Ex : PRIVATE vads_ship_to_street Adresse postale. ans..127 rue de l'innovation vads_ship_to_street2 Complément ou suite ou détail de l'adresse ans..127 Tous droits réservés - 22 / 31

23 Nom du champ Description Format Valeur vads_ship_to_zip Code postal an vads_ship_to_speed Les valeurs possibles sont les suivantes : STANDARD pour un délai de livraison normal. EXPRESS pour un délai de livraison rapide. PRIORITY pour un délai de livraison personnalisé rapide (Click & Collect). La valeur PRIORITY implique l'utilisation du champ vads_ship_to_delay. vads_ship_to_status Les valeurs possibles sont : PRIVATE pour une livraison à domicile. COMPANY pour une livraison dans une entreprise. 5. 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). Tous droits réservés - 23 / 31

24 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_ du type d'algorithme choisi dans la configuration de la boutique de la clé (certificat) La valeur de la clé est disponible dans votre Back Office Marchand depuis le menu Paramétrage > Boutique > onglet Certificats. Le type d'algorithme est défini dans votre Back Office Marchand depuis le menu Paramétrage > Boutique > onglet Configuration. Pour un maximum de sécurité, il est recommandé d'utiliser l'algorithme HMAC-SHA-256 ainsi qu'une clé alphanumé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 la clé de test ou de production en les séparant avec le caractère "+". 5. Selon l'algorithme de signature défini dans la configuration de votre boutique: a. si votre boutique est configurée pour utiliser "SHA-1", appliquez la fonction de hachage SHA-1 sur la chaîne obtenue à l'étape précédente. b. si votre boutique est configurée pour utiliser "HMAC-SHA-256", calculez et encodez au format Base64 la signature du message en utilisant l'algorithme HMAC-SHA-256 avec les paramètres suivants: la fonction de hachage SHA-256, la clé de test ou de production (en fonction de la valeur du champ vads_ctx_mode) comme clé partagée, le résultat de l'étape précédente comme message à authentifier. 6. Sauvegardez le résultat de l'étape précédente dans le champ signature. Tous droits réservés - 24 / 31

25 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="5124" /> <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_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="123456" /> <input type="hidden" name="vads_version" value="v2" /> <input type="hidden" name="signature" value="yca5do5tnvsnkdc/ep1bj2xa19z9q3iwpy9/rpesfs0= " /> <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+5124+TEST+978+PAYMENT+SINGLE V2 3. On ajoute la valeur de la clé de test à la fin de la chaîne en la séparant par le caractère "+". Dans cet exemple, la clé de test est INTERACTIVE+5124+TEST+978+PAYMENT+SINGLE V Si vous utilisez l algorithme SHA-1, appliquez le à la chaîne obtenue. Le résultat à transmettre dans le champ signature est : 59c96b34c74b9375c332b0b6a32e6deeec87de2b 5. Si votre boutique est configurée pour utiliser "HMAC-SHA-256", calculez et encodez au format Base64 la signature du message en utilisant l'algorithme HMAC-SHA-256 avec les paramètres suivants: la fonction de hachage SHA-256, la clé de test ou de production (en fonction de la valeur du champ vads_ctx_mode) comme clé partagée, le résultat de l'étape précédente comme message à authentifier. Le résultat à transmettre dans le champ signature est : yca5do5tnvsnkdc/ep1bj2xa19z9q3iwpy9/rpesfs0= Tous droits réservés - 25 / 31

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_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="me@example.com" /> <input type="hidden" name="vads_page_action" value="payment" /> <input type="hidden" name="vads_payment_cards" value="masterpass" /> <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_version" value="v2" /> <input type="hidden" name="signature" value="nm25dplkebtgehcdhn8mbt4ki6aji/odawhczcnafvy="/> <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 description du code erreur pour vous aider à identifier les causes possibles. 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 les causes possibles pour ce code d'erreur pour faciliter le diagnostic, l ensemble des champs contenus dans le formulaire. Une description des codes d'erreur avec leurs causes possibles est disponible sur notre site. Tous droits réservés - 26 / 31

27 11. ANALYSER LE RÉSULTAT DU PAIEMENT L'analyse du résultat du paiement est décrit dans le Guide d'implémentation API Formulaire disponible sur notre site documentaire. Dans ce document, seul le traitement des données spécifiques à la réponse de ce moyen de paiement est abordé Calculer la signature La signature se calcule selon la même logique utilisée lors de la création du formulaire de paiement. Les données transmises par la plateforme de paiement sont encodées en UTF-8. Toute altération des données reçues aboutira à un calcul de signature erroné. 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. Concaténez les valeurs de ces champs en les séparant avec le caractère "+". 4. Concaténez le résultat avec la clé de test ou de production en les séparant avec le caractère "+". 5. Selon l'algorithme de signature défini dans la configuration de votre boutique: a. si votre boutique est configurée pour utiliser "SHA-1", appliquez la fonction de hachage SHA-1 sur la chaîne obtenue à l'étape précédente. b. si votre boutique est configurée pour utiliser "HMAC-SHA-256", calculez et encodez au format Base64 la signature du message en utilisant l'algorithme HMAC-SHA-256 avec les paramètres suivants: la fonction de hachage SHA-256, la clé de test ou de production (en fonction de la valeur du champ vads_ctx_mode) comme clé partagée, le résultat de l'étape précédente comme message à authentifier. Tous droits réservés - 27 / 31

28 11.2. 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. Les signatures ne correspondent pas en cas : d erreur d'implémentation (erreur dans votre calcul, problème d encodage UTF-8, etc.), d erreur dans la valeur de la clé utilisée ou dans celle du champ vads_ctx_mode (problème fréquent lors du passage en production), de tentative de corruption des données Traiter les données spécifiques à la réponse d'un paiement FullCB L'URL de notification instantanée contiendra les informations ci-dessous. Nom du champ Description Valeur vads_trans_status Statut du paiement Les valeurs possibles sont : Valeur CAPTURED CANCELLED REFUSED EXPIRED Description Remisé La transaction est remise en banque. Annulé Annulation par l'acheteur, l'acquéreur ou par la plateforme. Refusé Expirée La date d'expiration de la demande d'autorisation est atteinte et le marchand n a pas validé la transaction. Le porteur ne sera donc pas débité. vads_auth_mode Mode d autorisation vads_payment_config Type du paiement SINGLE vads_amount vads_currency vads_capture_delay Montant dans la plus petite unité de la devise Devise utilisée pour le paiement Délai en nombre de jours avant remise en banque. Pour plus de détails, se référer au Guide d'implémentation API Formulaire disponible sur notre site documentaire. Seule la valeur FULL est possible. Autorisation du montant total de la transaction. Le marchand est crédité de la totalité du montant. L'échéancier est pris en charge par l'organisme de financement. Ex : 3000 pour 30,00 EUR Remarque : tout délai de remise supérieur à 0 jour spécifié dans le requête sera ignoré. Tous droits réservés - 28 / 31

29 Nom du champ Description Valeur vads_card_brand Type de carte utilisée pour le paiement vads_sequence_number Une seule échéance car le marchand est crédité de l intégralité de la somme. vads_presentation_date vads_action_mode vads_contract_used Date de remise en banque Mode d'acquisition des informations de la carte. Valeur du contrat associée à la transaction. FULLCB3X ou FULLCB4X 1 La transaction est en remise immédiate. INTERACTIVE Exemple : Tableau 1 : Liste des champs à analyser Tous droits réservés - 29 / 31

30 12. IDENTIFIER LES OPÉRATIONS AUTORISÉES SUR LES TRANSACTIONS Le Back Office Marchand met à disposition un certain nombre d'opérations sur les transactions effectuées avec ce moyen de paiement. Dans la liste des transactions : 1. Sélectionnez une transaction. 2. Effectuez un clic droit pour afficher la liste des opérations autorisées. Les opérations autorisées sur une transaction en cours sont les suivantes : Renvoyer l' de confirmation de la transaction à l'acheteur Renvoyer l' de confirmation de la transaction au marchand Les opérations autorisées sur une transaction remisée sont les suivantes : Effectuer un remboursement total ou partiel Renvoyer l' de confirmation de la transaction à l'acheteur Renvoyer l' de confirmation de la transaction au marchand Effectuer un remboursement sur une transaction remisée Il est possible de rembourser une partie ou la totalité d'un montant d'une transaction effectuée avec une carte de crédit. 1. Effectuez un clic droit sur une transaction 2. Sélectionnez Effectuer un remboursement. La boîte de dialogue Remboursement de la transaction s'affiche. Image 4 : Effectuer un remboursement 3. Renseignez le montant que vous souhaitez rembourser. 4. Cliquez sur Effectuer le remboursement. Le détail de cette opération s'affiche Renvoyer l' de confirmation de la transaction au marchand Pour renvoyer l' de confirmation de la transaction au marchand. Tous droits réservés - 30 / 31

31 1. Recherchez la transaction. 2. Effectuez un clic droit sur la transaction et cliquez sur Renvoyer l' de confirmation de la transaction au marchand. Un message de confirmation d'envoi apparait. 3. Cliquez sur OK Renvoyer l' de confirmation de la transaction à l'acheteur Pour renvoyer l' de confirmation de la transaction à l'acheteur en cas de non réception ou en cas de correction de l adresse Recherchez la transaction. 2. Effectuez un clic droit sur la transaction. 3. Effectuez un clic droit sur la transaction et cliquez Renvoyer l' de confirmation de la transaction à l'acheteur. La boîte de dialogue pour saisir l'adresse de l'acheteur s'affiche. 4. Saisissez l'adresse Cliquez sur OK. Tous droits réservés - 31 / 31