Définition des Webservices Ordre de paiement par email. Version 1.0

Définition des Webservices Ordre de paiement par email Version 1.0

Rédaction, Vérification, Approbation Rédaction Vérification Approbation Nom Date/Visa Nom Date/Visa Nom Date/Visa Historique du document Version Auteur Date Commentaires 1.0 Lyra-Network 24/06/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.

SOMMAIRE 1. Présentation...4 2. Description des types...5 2.1. PaymentOfferInfo... 5 2.2. PaymentOfferEntity... 6 2.3. PaymentOfferResponse... 6 2.4. Description des codes réponse... 7 3. Description des méthodes...8 3.1. Create... 8 3.2. Update... 8 4. Signature...9 5. L url serveur...10 6. Annexes...11 6.1. Les variables utilisateurs... 11

1. Présentation Ce document présente le webservice paymentoffer qui permet d automatiser les actions réalisables manuellement depuis l outil de gestion de caisse commerçant concernant les ordres de paiement par mail c'est-à-dire la création et la modification des ordres. Ces webservices ont été développés suivant le protocole SOAP (Simple Object Access Protocol) et sont décrits par le fichier wsdl suivant : https://paiement.systempay.fr/vads-ws/paymentoffer-v1?wsdl Afin de sécuriser les échanges, les webservices (SOAP) sont cryptés grâce au protocole HTTPS. De plus un mécanisme de signature a été mis en place afin de valider et d authentifier l échange des données. Il est possible d utiliser ce service pour créer ou modifier des ordres. Chaque création / modification correspond à un envoi de mail au(x) destinataires(s) représenté(s) par une liste d adresses email. Dans le cas d un envoi multiple, un ordre est créé par destinataire. Il y a donc autant d ordres que de destinataires, même s il s agit d un point de vue du commerçant d un même ordre. Ceci s explique par le fait qu il faille faire correspondre une transaction par destinataire. Dans le cas d un envoi multiple, le champ référence (si valorisé) est alors incrémenté de 1 sur 3 caractères numériques concaténés à la référence avec un tiret. Ex : [ref]-001, [ref]-002 Si le commerçant dans le champ référence met la valeur "recouvrement", et que l ordre est envoyé à trois destinataires (ou trois clients) alors 3 ordres seront créés avec les références suivantes: - Recouvrement-001 - Recouvrement-002 - Recouvrement-003 Il est possible de désactiver l envoi d email au client. La réponse renvoyée par le serveur contient la liste des ordres créés. Chaque ordre est donc associé à un identifiant numérique, une adresse email et un lien http contenant les informations de paiement. Ainsi, un commerçant peut utiliser son propre outil de mailing et insérer un lien de paiement valide pour un ordre et destinataire donnés. En mode modification, il est également possible de mettre à jour un ordre sans pour autant renvoyer de mail. Systempay Description des Webservices "ordre de paiement par email" @Lyra Network- 4/11

2. Description des types 2.1. PaymentOfferInfo Ce type permet de décrire les paramètres pour une création d un ordre de paiement par mail. Il doit être instancié avec au minimum les champs obligatoires valorisés par le système client. Cet objet sera passé en paramètre à la méthode de création d un ordre. Nom du champ Type Description shopid long Identifiant de la boutique reference Correspond à l order id de la transaction, ou référence de la commande, optionnel recipients List Liste des adresses emails : un ordre est créé par destinataire (Obligatoire, min 1, max 100). subject Objet de l email envoyé (Obligatoire) message Corps de l email envoyé (Obligatoire) sendmail boolean Envoie l email au destinataire si égal à true ctxmode Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") (Obligatoire) device En version 1.0 ne peut être que «MAIL» Il s agit de la valeur par défaut amount long Montant de la transaction en plus petite unité monétaire currency int Devise (Code monnaie ISO 4217, Euro : 978) validity Date Date de validité de l ordre : ne peut être antérieure à la date courante et de peut dépasser 90 jours à venir validationmode int 0 = Automatique, 1 = Manuelle (obligatoire) locale La locale qui utilisée par la page de paiement lorsque l utilisateur destinataire de l ordre procède à la transaction. Doit être choisie parmis les locales supportées par la plateforme : de,en,es,fr,it,ja,nl,pt,zh Exemple d initialisation en java : private PaymentOfferInfo initinfo() { PaymentOfferInfo info = new PaymentOfferInfo(); info.setshopid(pdv_id); info.setamount(1000); info.setcurrency(978); info.setctxmode("production"); info.getrecipients().add(mail1); info.getrecipients().add(mail2); info.setlocale("fr"); info.setmessage(body); info.setreference("ref-ordre"); info.setdevice(paymentdevice.mail.to()); info.setsubject(subject); info.setvalidationmode(0); info.setvalidity(utilwstests.getnewdate(90)); info.setsendmail(true); return info; } @Lyra Network - 5/11

2.2. PaymentOfferEntity Ce type permet de décrire les paramètres pour une modification d un ordre de paiement par mail. Il doit être instancié avec au minimum les champs obligatoires valorisés par le système client. Cet objet sera passé en paramètre à la méthode de modification d un ordre. La différence avec l objet de type PaymentOfferInfo, c est qu il contient l identifiant de l ordre et non pas une liste d adresse email mais l adresse email du destinataire de l ordre (un ordre correspond à un destinataire). Nom du champ Type Description shopid long Identifiant de la boutique offerid long Identifiant de l ordre sendmail Boolean Renvoie l email au destinataire si égal à true. reference Correspond à l order id de la transaction, ou référence de la commande, optionnel recipient Adresse email du destinataire de l ordre. subject Objet de l email envoyé (Obligatoire) message Corps de l email envoyé (Obligatoire) ctxmode Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") (Obligatoire) device En version 1.0 ne peut être que "MAIL" Il s agit de la valeur par défaut amount long Montant de la transaction en plus petite unité monétaire currency int Devise (Code monnaie ISO 4217, Euro : 978) validity Date Date de validité de l ordre : ne peut être antérieure à la date courante et de peut dépasser 90 jours à venir validationmode int 0 = Automatique, 1 = Manuelle (obligatoire) locale La locale qui utilisée par la page de paiement lorsque l utilisateur destinataire de l ordre procède à la transaction. Doit être choisie parmi les locales supportées par la plateforme : de,en,es,fr,it,ja,nl,pt,zh 2.3. PaymentOfferResponse Il s agit de l objet réponse renvoyé par le serveur lors d une requête de création ou modification d un ordre. Si l opération est un succès, l objet contient la liste des identifiants des ordres créés ou modifiés, sinon il contient un code erreur. Nom du champ Type Description offerentities List Liste des ordres créés ou modifiées. Liste contenant des objets de type PaymentOfferEntity. (Cf 2.2) reponsecode Code réponse renvoyé par le serveur returnmessage Message renvoyé par le serveur @Lyra Network - 6/11

2.4. Description des codes réponse responsecode Description OK Action réalisée avec succès NOT_ALLOWED Action non autorisé NOT_AUTHORIZED Modification de l ordre spécifié interdite 1 OFFER_NOT_FOUND L identifiant de l ordre n existe pas BAD_SIGNATURE Mauvaise signature RECIPIENTS La liste des destinataires ne peut-être nulle ou vide et ne doit pas dépasser le nombre de 100 adresses de courriel RECIPIENT L adresse de courriel spécifiée est invalide SUBJECT L objet du message ne peut être nul MESSAGE Le corps du mail ne peut être nul CTX_MODE Le mode de connexion ne peut-être que "TEST" ou "PRODUCTION" DEVICE En version 1.0 ne peut être valorisé que par "MAIL" VALIDITY_DATE Paramètre validity invalide AMOUNT Paramètre amount invalide VALIDATION_MODE Paramètre validationmode invalide SYSTEM_FAILURE Erreur serveur 1 Vraisemblablement un ordre qui a déjà été finalisé. Est considéré comme finalisé tout ordre de paiement associé à une transaction, sauf une transaction refusée. @Lyra Network - 7/11

3. Description des méthodes 3.1. Create Cette fonction permet de créer les ordres de paiement. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire info PaymentOfferInfo cf 2.1 wssignature Signature (cf ci-dessous) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, reference, amount, currency, locale, message, recipients, subject, validationmode, validity Ces paramètres sont obligatoires même si null Cette fonction retourne une réponse du type PaymentOfferResponse (cf. Erreur! Source du renvoi introuvable.) 3.2. Update Cette fonction permet de modifier les ordres de paiement. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire entity PaymentOfferEntity cf 2.1 wssignature Signature (cf ci-dessous) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, offerid, reference, ctxmode, amount, currency, locale, message, recipient, subject, validationmode, validity Ces paramètres sont obligatoires même si null Cette fonction retourne une réponse du type PaymentOfferResponse (cf. 2.3 ) @Lyra Network - 8/11

4. Signature Un certificat est nécessaire pour dialoguer avec la plateforme de paiement. Il est mis à disposition de toutes les personnes habilitées à la consultation des certificats dans votre outil de gestion de caisse à l emplacement suivant : Paramètres / Boutique / Certificat. Il existe deux certificats différents : un pour la plateforme de test et un pour la plateforme de production. La signature sera générée comme suit : Création d'une chaîne de caractère représentant la concaténation des paramètres, séparés par le caractère "+". Ajout à cette chaîne d'un "certificat" numérique (de test ou de production selon le contexte). Hachage de la chaîne résultante avec l'algorithme SHA1. La plateforme de paiement effectuera obligatoirement la vérification de la signature. Il est de la responsabilité du commerçant de vérifier à son tour la signature transmise en retour. L'ordre des champs doit être respecté tel que : 1. Mode création : shopid, reference, ctxmode, amount, currency, locale, message, recipients, subject, validationmode, validity, sendmail 2. Mode modification : shopid, offerid, reference, ctxmode, amount, currency, locale, message, recipient, subject, validationmode, validity, sendmail Les champs de type date doivent être formatés de la manière suivante : YYYYMMDD soit pour le 1 er Février 2011 : 20110201. Les champs de type numérique ne doivent pas avoir de 0 à gauche du digit le plus significatif. Les champs de type bool prennent les valeurs suivantes : - 1 pour vrai (true) - 0 pour faux (false) Les champs de type non renseignés seront vides. Exemple : Pour un appel Cancel si les paramètres de la requête sont les suivants : shopid = 12345678 transmissiondate = 7 Mars 2010 transactionid = 654321 sequencenb = 1 ctxmode = TEST comment = non renseigné Si la valeur du certificat de test est 1122334455667788, alors la chaîne à utiliser pour le hachage à l aide de l algorithme SHA1 est la suivante : 12345678+20100307+654321+1+TEST++1122334455667788 @Lyra Network - 9/11

Ce qui donne après hachage (signature) : 88ff8fc1897ac4edf34c5e2327be5adde76e17d6 En mode TEST, en cas de mauvais calcul de signature, le code erreur renvoyé est «BAD_SIGNATURE» et, la chaine de caractère utilisée pour la signature côté serveur est alors renvoyée dans le champ extendedcode. 5. L url serveur Lors du traitement du fichier, si aucune anomalie n est détectée, un appel serveur à serveur via l URL serveur de la boutique est généré après chaque paiement. Cette réponse contient tous les paramètres de réponse décrits dans le paragraphe 3.1 du guide d implémentation du formulaire de paiement V2. Parmi les paramètres de réponse, la variable vads_payment_src sera valorisée à TK (source de paiement par token) et la variable vads_token_id valorisé par l identifiant public de l ordre de paiement. De cette façon, vous serez en mesure d identifier la provenance de l appel et d appliquer le traitement adéquat. @Lyra Network - 10/11

6. Annexes 6.1. Les variables utilisateurs Quatre variables utilisateur sont disponibles. Elles permettent d enrichir le contenu de l objet et du corps de l email avec les valeurs suivantes : Attribut de l ordre Date de création Date de validité Montant Référence Url de paiement Variable %creation_date% %end_date% %amount% %reference% %url% En mode création, la variable %creation_date% est valorisée par la date du jour. En mode modification, cette variable est valorisée par la date de création enregistrée au moment de la création. Elle n est donc pas modifiable. La variable %amount% intègre dynamiquement la devise, et est calculée en fonction de la locale. Par exemple pour un ordre créé avec la locale "fr" (France), la devise euro et un montant de 13,25 la variable sera résolue de la manière suivante : "3,25 EUR" Si on remplace la locale "fr" par "en" (Angleterre) la résolution aura la forme suivante : "EUR13.25" Exemple : - Amount = 10025 - Validity = 12/06/2011 - Reference = AZ - Subject = Ordre %reference% du %start_date% au %end_date% de %amount% Si la locale est "fr", l objet de l email envoyé aura l affichage suivant : "Ordre AZ du [date du jour] au 12/06/2011 de 100,25 EUR" La variable %url% permet de placer l url de paiement dans le texte du corps de message. Si la variable n est pas utilisée, l url de paiement est automatiquement insérée à la fin du message. Ces variables sont disponibles et donc résolues dans l objet de l email et le corps du message. Aucune de ces variables n est obligatoire. @Lyra Network - 11/11