Plateforme PAYZEN. Définition de Web-services

Transcription

1 Plateforme PAYZEN Définition de Web-services Ordre de paiement Version 1.1

2 Rédaction, Vérification, Approbation Rédaction Vérification Approbation Nom Date/Visa Nom Date/Visa Nom Date/Visa Lyra-Network 06/03/2013 Lyra-Network 06/03/2013 Lyra-Network 06/03/2013 Historique du document Version Auteur Date Commentaires 1.1 Lyra-Network 06/03/2013 Refonte de la documentation 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.

3 SOMMAIRE 1. Présentation Description des types : PaymentOfferInfo : PaymentOfferEntity : PaymentOfferResponse : Description des codes réponse Description des methodes : Note Importante : Create : Update Signature : Mode de calcul : Exemple pour la méthode create L url serveur Annexes : Les variables utilisateurs ASSISTANCE TECHNIQUE... 12

4 1. PRESENTATION 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 : 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 . 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 Recouvrement Recouvrement-003 Il est possible de désactiver l envoi d 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 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 renvoyé de mail.

5 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 Obligatoire Description shopid Long n8 Identifiant de la boutique reference String Correspond à l order id de la transaction, ou référence de an24 la commande. recipients Array[1- Liste des adresses s : un ordre est créé par 100] destinataire (min 1, max 100). subject String an255 Objet de l envoyé message String an2000 Corps de l envoyé sendmail boolean Envoie l au destinataire si égal à true ctxmode String Contexte de sollicitation de la plateforme de paiement. Deux valeurs possibles : TEST ou PRODUCTION device String En version 1.0 ne peut être que «MAIL» amount long Montant de la transaction en plus petite unité monétaire. Soit pour la devise Euro un montant de 10,50 euros correspond à amount=1050. 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 Cette date devra être exprimée au format w3c. exemple : T23:00:00+00:00 validationmode int 0 = Automatique, 1 = Manuel Automatique : Le paiement sera remis en banque de manière automatique. Manuel : Pour être remis en banque le marchand devra effectuée une action sur l outil de gestion SYSTEMPAY locale String Ce paramètre définit la langue affichée sur la page de paiement lorsque l utilisateur destinataire de l ordre procède à la transaction. Valeur possibles : de,en,es,fr,it,ja,nl,pt,zh

6 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.tostring()); info.setsubject(subject); info.setvalidationmode(0); info.setvalidity(utilwstests.getnewdate(90)); info.setsendmail(true); return info; } 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 mais l adresse du destinataire de l ordre (un ordre correspond à un destinataire). Nom du champ Type Obligatoire Description shopid Long n8 Identifiant de la boutique offerid Long an32 Identifiant de l ordre paymenturl Url de paiement de l ordre sendmail boolean Envoie l au destinataire si égal à true reference String Correspond à l order id de la transaction, ou référence de an24 la commande. recipients Array[1- Liste des adresses s : un ordre a été créé par 100] destinataire (min 1, max 100). subject String an255 Objet de l envoyé message String an2000 Corps de l envoyé ctxmode String Contexte de sollicitation de la plateforme de paiement. Deux valeurs possibles : TEST ou PRODUCTION device String En version 1.0 ne peut être que «MAIL» amount long Montant de la transaction en plus petite unité monétaire. Soit pour la devise Euro un montant de 10,50 euros correspond à amount=1050. 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 Cette date devra être exprimée au format w3c. exemple : T23:00:00+00:00

7 Nom du champ Type Obligatoire Description validationmode int 0 = Automatique, 1 = Manuel Automatique : Le paiement sera remis en banque de manière automatique. Manuel : Pour être remis en banque le marchand devra effectuée une action sur l outil de gestion SYSTEMPAY locale String Ce paramètre définit la langue affichée sur la page de paiement lorsque l utilisateur destinataire de l ordre procède à la transaction. Valeur possibles : 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éées ou modifiées sinon contient un code erreur. Nom du champ Type Description offerentities list[1-100] Liste des ordres créés ou modifiées. Liste contenant des objets de type PaymentOfferEntity. reponsecode String Code réponse renvoyé par le serveur. returnmessage String Description en anglais du champ reponsecode. extendedcode String Renvoyé en mode TEST si erreur de signature Décrit la chaine sans le certificat servant au calcul de la signature avant le hachage SHA1. 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 La modification d un ordre est possible dans les 2 cas suivants : - Aucun paiement associé à cet ordre. - Un ou plusieurs paiements refusés associé à cet ordre.

8 3. DESCRIPTION DES METHODES 3.1: Note Importante Si le champ sendmail est valorisé à true alors le client ou les clients recevront un mail contenant une URL de paiement unique pour chaque client. Si le champ sendmail est valorisé à false alors le client ou les clients ne recevront pas de mail contenant une URL de paiement unique pour chaque client. A charge du marchant de récupérer les URL de paiements afin de les faire parvenir au client final dans le canal de son choix. 3.2: Create Cette fonction permet de créer les ordres de paiement. Entrée : La fonction create prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire info PaymentOfferInfo Se référer au chapitre 2.1 wssignature String Se référer au chapitre 4 SIGNATURE Exemple xml généré : <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:ns1=" <ns1:create> <info> <shopid> </shopid> <ctxmode>test</ctxmode> <subject>bonjour veuillez trouver ci joint un lien de paiement</subject> <message>bonjour veuillez trouver ci joint un lien de paiement</message> <device>mail</device> <reférence>cmd123</reference> <validity> t23:00:00+00:00</validity> <amount>1000</amount> <validationmode>0</validationmode> <currency>978</currency> <locale>fr</locale> <sendmail>true</sendmail> <recipients>test@test.fr</recipients> <recipients>test1@test.fr</recipients> </info> <signature>1ee15221a1b9c062e01ba4a790e f72fb</signature> </ns1:create> </SOAP-ENV:Body></SOAP-ENV:Envelope>

9 Signature : Se référer au chapitre 4 SIGNATURE Réponse : Cette fonction retourne une réponse du type PaymentOfferResponse. Se référer au chapitre : 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 Se référer au chapitre 2.1 wssignature String Se référer au chapitre 4 SIGNATURE Signature : Se référer au chapitre 4 SIGNATURE Réponse : Cette fonction retourne une réponse du type PaymentOfferResponse. Se référer au chapitre SIGNATURE 4.1: Mode de calcul 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. Attention le certificat à utiliser est différent en fonction du mode utilisé : TEST ou 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.

10 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 Champs de type date : Les champs de type date dans le calcul de la signature doivent être formatés de la manière suivante : YYYYMMDD soit pour le T23:00:00+00:00: Champs recipients La chaine pour ce champ devra être encadrée par [] Chaque adresse mail devra être séparée d une virgule et d un espace. Soit pour 2 mails la chaîne pour ce champ sera : [ 1, 2] Remarque : Un champ de type string optionnel non envoyé devra être toutefois pris en compte et seront considéré comme vide 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 String non renseignés seront vides.

11 4.2: Exemple pour la méthode create Champs envoyés : <info> <shopid> </shopid> <ctxmode>test</ctxmode> <subject>paiement de votre facture</subject> <message>bonjour veuillez trouver ci joint un lien de paiement</message> <device>mail</device> <validity> t23:00:00+00:00</validity> <amount>1000</amount> <validationmode>0</validationmode> <currency>978</currency> <locale>fr</locale> <sendmail>false</sendmail> <recipients>test@test.fr</recipients> <recipients>test1@test.fr</recipients> </info> Dans cet exemple le champ optionnel reference n est pas envoyé Chaîne obtenue avant hachage : TEST fr+Bonjour veuillez trouver ci joint un lien de paiement+[test@test.fr, test1@test.fr]+bonjour veuillez trouver ci joint un lien de paiement correspond au certificat disponible dans le Backoffice de la solution de paiement. Signature après algorithme SHA1 pour la chaîne ci-dessus : 1ee15221a1b9c062e01ba4a790e f72fb 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 Lorsque l URL associé a un ordre de paiement fait l objet d un paiement alors l url serveur est appelée si elle renseignée dans le back office de la solution de paiement. Cet appel contient tous les paramètres de réponse lié au paiement. Ces paramètres sont décrits dans le guide d implémentation du formulaire de paiement V2 disponible sur le site documentaire. 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.

12 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 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 : «13,25 EUR» Si on remplace la locale «fr» par «en» (Angleterre) la résolution aura la forme suivante : «EUR13.25» Exemple : - Amount = Validity = 12/06/ Reference = AZ - Subject = Ordre %reference% du %start_date% au %end_date% de %amount% Si la locale est «fr», l objet de l 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 et le corps du message. Aucune de ces variables n est obligatoire. 7. ASSISTANCE TECHNIQUE Pour tout problème d accès à le back office Payzen, il convient d utiliser les liens «compte bloqué» ou «mot de passe oublié» disponible sur la page de connexion de le back office Payzen. Pour toute question technique, vous pouvez nous contacter par téléphone au Accessible les jours ouvrés du lundi au vendredi de 09h00 à 18h00 (heure légale française). (Tarification de ce numéro: Coût d un appel local depuis un poste fixe)