Définition des Webservices Standards Systempay 1.27.8 Version 2.7c
Historique du document Version Auteur Date Commentaires 2.7c Lyra-Network 06/12/2013 Modification du champ threedsresult. Précision apportée quant à l utilisation de ce champ dans le cas d une carte non enrôlée. Ajout de précision sur les champs validationmode, présentationdate et sequencenb Ajout du code d erreur 27 Montant non autorisé. Ajout d exemple en C# 2.7b Lyra-Network 10/07/2013 Précision sur le champ transmissiondate pour l ensemble des méthodes 2.7a Lyra-Network 20/06/2013 Mise à jour de la liste des codes retour autorisation 2.7 Lyra-Network 14/05/2013 2.6f Lyra-Network 21/03/2013 2.6e Lyra-Network 21/01/2013 2.6d Lyra-Network 10/01/2013 Suppression de la remarque sur le champ transmissiondate sur toutes les méthodes SAUF pour la méthode create. Précision sur les valeurs du champ transaction Status Ajout des champs «adresses de livraison» dans le type createpaiementinfo Ajout du chapitre Notions de timeout Ajout d exemple de cinématiques de paiement avec gestion des timeout Ajout de l errorcode 26. Nouveau comportement lors du remboursement d une carte expirée Correction de l encodage dans l exemple JAVA Ajout des codes renvoyés dans le champ authresult. Précision apportées pour le champ cvv localcontrol : Ajout de nouvelles valeurs Précision apportée concernant l erreurcode 15. create : Précisions apportées sur la valorisation de paymentmethod 2.6c Lyra-Network 14/12/2012 Duplicate : Précisions sur les statuts autorisés 2.6b Lyra-Network 26/10/2012 Maintien de la session HTTP lors de l enchainement de plusieurs requêtes 2.6a Lyra-Network 17/10/2012 Ajout des caractéristiques du champ transactionid 2.6 Lyra-Network 24/04/2012 2.51 Lyra-Network 06/04/2012 Précisions sur dates d expiration 2.5 Lyra-Network 20/10/2011 2.4 Lyra-Network 31/12/2010 Ajout modifyandvalidate Ajout d un exemple de la méthode create Précisions sur les champs du transactioninfo et createpaiementinfo Précision sur la valeur du champ transmissiondate 2.3 Lyra-Network 29/11/2010 Ajout champs pour paiement 3DS Ajout champ impayés 2.2 Lyra-Network 03/09/2010 Ajout description champ date Précisions apportées pour la prise en compte des champs de type date en UTC lors du calcul de signature. Précisions apportées sur les codes d erreur 2.1 Lyra-Network 31/03/2010 Modification valorisation champ PaymentMethod 2.0 Lyra-Network 31/03/2010 Ajout champs Infos + contrat. 1.1 Lyra-Network 05/03/2010 Version avec signature. 1.0 Lyra-Network 04/09/2009 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... 1 2. Notions de timeout... 1 3. Description des codes d erreurs... 3 4. Description des types... 5 4.1. Date... 5 4.2. standardresponse... 5 4.3. localcontrol... 7 4.4. transactioninfo... 8 4.5. createpaiementinfo... 12 4.6. threedsresult... 15 5. Description des méthodes... 16 5.1. Création d un paiement (create)... 16 5.2. Annulation d une transaction (cancel)... 18 5.3. Validation d une transaction (validate)... 19 5.4. Forçage d une transaction (force)... 20 5.5. Modification d une transaction (modify)... 21 5.6. Remboursement d une transaction (refund)... 22 5.7. Duplication d une transaction (duplicate)... 23 5.8. Recherche des détails d une transaction (getinfo)... 24 5.9. Modification et validation d une transaction (modifyandvalidate)... 25 6. Signature... 26 7. Maintien de la session HTTP entre 2 requêtes... 27 7.1. Exemple d application... 27 7.2. Exemple d implémentation en PHP... 29 8. Exemples de cinématique de paiement avec gestion des cas d échec.. 30 8.1. Livraison différée de marchandise... 30 8.2. Vente de biens immatériels type VOD... 31 9. Migration de la v2 à la v3... 32 9.1. Changement de signature pour la méthode create... 32 9.2. Changement de signature pour le retour de transactioninfo... 32 9.3. Note aux utilisateurs PHP... 32 10. Exemple d implémentation JAVA... 33 10.1. Générer les stubs depuis le wsdl... 33 10.2. Exemple de code pour générer la signature... 33 10.3. Exemple de code pour annuler un paiement... 34 10.4. Exemple de code pour créer un paiement... 35 11. Exemple d implémentation en C#... 37 11.1. Exemple de code pour générer la signature... 37 11.2. Calcul de signature : fonction create... 38 12. Annexes... 39 12.1. Listes des cartes de test... 39
1. Présentation Ce document présente les webservices standards qui permettent d automatiser les actions réalisables manuellement depuis l outil de gestion de caisse commerçant. 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/v3?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. Avant de commencer votre implémentation, veuillez-vous assurer que l offre souscrite auprès de Systempay comprend l utilisation des webservices. 2. Notions de timeout Le traitement d une requête webservices s articule autour d un enchainement d événements asynchrones comme l envoi de la requête via le réseau du site marchand, le transport des informations sur le réseau internet, le traitement du paiement par la plateforme, l interrogation des serveurs bancaires, etc. Un incident peut survenir à chaque étape et augmenter le temps du traitement (et donc implicitement le temps d attente pour l acheteur). Une requête peut voir sa réponse retardée pour de multiples raisons comme par exemple : Un temps de réponse long de la part de l émetteur du porteur de la carte, (cas des cartes étrangères, cas de période de forte charge comme les soldes,..) Un temps de réponse long de la part de l acquéreur lors de la transmission et de la réception de la demande d autorisation Un temps de réponse long du côté de votre application suite à une charge importante Un temps de réponse long de la plateforme de paiement. Un problème de peering sur Internet qui peut entrainer des pertes de messages, etc Ce qui veut dire que suivant le timeout que vous positionnez dans votre application, vous pouvez ne pas recevoir de réponse alors que le traitement asynchrone continue à s exécuter côté plateforme de paiement. Vous devez donc gérer les cas de timeout qui mal traités peuvent donner un mauvais résultat à l acheteur. Afin d être le plus réactif possible vis-à-vis de l acheteur, il est conseillé de mettre en place un timeout sur non réponse et d adapter le traitement pour informer l acheteur. @Lyra Network- 1/42
Le marchand veillera à bien configurer la valeur du timeout, car plus ce délai sera court, plus le nombre de requêtes en timeout sur le site marchand augmentera. Le temps moyen de traitement par la plateforme étant inférieur à 5 secondes, un timeout de 20s à 30s est tout à fait acceptable. ATTENTION Un temps de traitement plus long ne doit pas être confondu avec un paiement refusé. Le paiement peut être accepté même si votre requête échoue en timeout. Car la demande de paiement dépend d évènements asynchrones non stoppés par le déclenchement du timeout. Le marchand devra donc mettre en place un traitement particulier pour les requêtes en timeout. Si vous n avez pas récupéré la réponse à votre requête WS à la fin de votre timeout, il ne faut pas forcément informer l utilisateur que son paiement a été refusé. Car il risque de tenter un nouveau paiement alors qu entre-temps son paiement a réellement abouti après la fin de votre timeout (traitement asynchrone). Vous devez plutôt suivant vos contraintes: Soit l informer que son règlement est en cours et revenir vers lui une fois que vous connaissez le statut final de votre paiement. Car le risque est que l acheteur tente de multiples paiements. Soit le notifier du refus parce que vous savez que vous ne validerez pas son paiement Deux cinématiques sont données à titre d exemple au chapitre 8. @Lyra Network- 2/ 42
3. Description des codes d erreurs Les codes d erreurs en gras sont détaillés sur la page suivante. Code Description Code Description d erreur d erreur 0 Action réalisée avec succès 61 Paramètre orderinfo1 invalide 1 Action non autorisée 62 Paramètre orderinfo2 invalide 2 Transaction non trouvée 63 Paramètre orderinfo3 invalide 3 Transaction pas dans le bon état 64 Paramètre PaymentMethod invalide 4 Transaction existe déjà 65 Paramètre CardNumber invalide 5 Mauvaise signature 66 Paramètre ContractNumber invalide 6 Mauvaise date 67 Paramètre customerid invalide 10 Mauvais montant 68 Paramètre customertitle invalide 11 Mauvaise devise 69 Paramètre customername invalide 12 Type de carte inconnu 70 Paramètre customerphone invalide 13 Paramètre date d expiration invalide 71 Paramètre customermail invalide 14 Paramètre cvv invalide 72 Paramètre customeraddress invalide 15 Contrat inconnu 73 Paramètre customerzipcode invalide 16 Paramètre Numéro de carte invalide 74 Paramètre customercity invalide 17 Identifiant non trouvé 75 Paramètre customercountry invalide 18 Identifiant non valide (Résilié, ) 76 Paramètre customerlanguage invalide 19 Subscription non trouvée 77 Paramètre customerip invalide 20 Subscription non valide 78 Paramètre customersendmail invalide 21 Identifiant déjà existant 79 Paramètre customermobilephone invalide 22 Création d identifiant refusé 80 Paramètre subpaiementtype invalide 23 Identifiant purgé 81 Paramètre subreference invalide 26 Pas de changement 82 Paramètre initialamount invalide 27 Montant non autorisé 83 Paramètre occinitialamount invalide 40 Plage non trouvée 84 Paramètre effectdate invalide 50 Paramètre shopid invalide 85 Paramètre state invalide 51 Paramètre transmissiondate invalide 90 Paramètre enrolled invalide 52 Paramètre transactionid invalide 91 Paramètre authstatus invalide 53 Paramètre ctxmode invalide 92 Paramètre eci invalide 54 Paramètre comment invalide 93 Paramètre xid invalide 55 Paramètre AutoNb invalide 94 Paramètre cavv invalide 56 Paramètre AutoDate invalide 95 Paramètre cavvalgo invalide 57 Paramètre presentationdate invalide 96 Paramètre brand invalide 58 Paramètre newtransactionid invalide 98 Paramètre requestid invalide 59 Paramètre validationmode invalide 99 Autre erreur 60 Paramètre orderid invalide @Lyra Network- 3/ 42
Précisions sur les codes d erreurs ErrorCode 0 : Indique que l action demandée a été réalisée avec succès, traduisant ainsi que le format de la requête est correct. Remarque : Dans le cas d une création de paiement (méthode create) ce code d erreur ne doit pas être confondu avec le champ transactionstatus qui est le seul à donner le résultat du paiement. Ainsi on pourra avoir un errorcode à 0 et un transactionstatus à 8, correspondant à la création d une transaction dont la demande d autorisation a été refusée. ErrorCode 1 : Indique que vous n avez pas souscrit une offre Systempay permettant d utiliser les webservices. ErrorCode 15 : Indique un défaut au niveau du contrat commerçant. Plusieurs cas possibles : La valeur transmise dans la requête ne correspond à aucun contrat enregistré sur la boutique (shopid), Il n y a pas de contrat enregistré sur la boutique, Le contrat spécifié est clôturé, Aucun contrat ne correspond au type de contrat nécessaire pour effectuer le paiement. C est le cas si vous ne possédez pas de contrat VAD (ERT 20) et que paymentmethod est valorisé à MOTO, CC ou OTHER dans votre requête. ErrorCode 27 : Indique que le montant de votre requête de création ou de remboursement de paiement n est pas conforme aux montants minimum/ maximum définis sur votre contrat commerçant. Vous pouvez vous rapprocher du service client pour connaitre les détails de votre contrat. @Lyra Network- 4/ 42
4. Description des types En dehors des types simples (int, string, date, ), les webservices utilisent des types plus complexes (code retour, description de la transaction, ) qui sont décrits dans ce chapitre. 4.1. Date Les champs date doivent suivre les recommandations W3C (http://www.w3.org/tr/note-datetime). Par exemple pour une date d expiration en décembre 2012, le format correct devrait-être 2012-12- 31T00:00:00+00:00. Attention : Lors du calcul de signature, le format des champs de type date est YYYYmmDD. (cf. chapitre 6) 4.2. standardresponse Ce type permet de décrire la réponse de la plupart des webservices. Nom du champ Type Description errorcode int Code d erreur (cf.3) extendederrorcode String Précision sur le code d erreur transactionstatus int Statut de la transaction timestamp long Timestamp permettant la génération de signature unique signature String Signature de la transaction (cf. 6) La signature permet de valider l intégrité de la réponse, le calcul de cette signature se fait en prenant les paramètres dans l ordre suivant : errorcode, extendederrorcode, transactionstatus, timestamp Les différentes valeurs des codes d erreurs et codes d erreurs étendus seront précisées pour chacun des webservices. @Lyra Network- 5/ 42
Les différents statuts de la transaction (transactionstatus) peuvent être : Valeur 0 Initial (en traitement) Réservé à un usage spécifique Description 1 2 3 4 5 6 7 8 9 11 12 13 A valider : Cas d un paiement créé en validation manuelle et pour lequel l autorisation a été acceptée. A forcer Contacter l émetteur Ce statut apparaît occasionnellement lorsqu un client a dépassé le plafond des paiements autorisés pour sa carte. Le paiement est considéré comme refusé. A valider et autoriser Cas d un paiement créé en validation manuelle, dont la date de présentation est supérieure à 6 jours et pour laquelle une prise d empreinte a été réalisée avec succès. En attente de remise : Cas d un paiement accepté, validé, et dont la date de présentation est inférieure à 6 jours. En attente d autorisation : Cas d un paiement différé, dont la date de présentation est supérieure à 6 jours, et pour lequel une prise d empreinte a été réalisée avec succès. Remisée : Cas d une transaction acceptée et remise en banque. Expiré : Cas d un paiement créé en validation manuelle et pour lequel l autorisation a été acceptée mais dont la date de présentation a été atteinte. Refusé : Cas d un paiement refusé quel que soit le motif (demande d autorisation, contrôles locaux etc...) Annulé : Cas d un paiement annulé par le marchand depuis le BO ou via une requête cancel En cours de remise Réservé à un usage spécifique En cours d autorisation Réservé à un usage spécifique En échec Réservé à un usage spécifique @Lyra Network- 6/ 42
4.3. localcontrol Ce type permet de décrire un contrôle local (nom du contrôle et résultat). Nom du champ Type Description name String Nom du contrôle result Bool Résultat du contrôle Les différentes valeurs possibles pour name sont : Valeur Description "CARD" Carte située dans une liste grise "COUNTRY" Pays inclus dans la liste grise de la boutique ou absent de la liste blanche "IPADDR" Adresse IP située dans une liste grise "AMOUNT" Encours atteint "BIN" Le code BIN appartient à la liste grise du commerçant " ECB" Détection d une e-carte bleue "CARD_COMMERCIAL_NATIONAL" Détection d une carte commerciale nationale "CARD_COMMERCIAL_FOREIGN" Détection d une carte commerciale étrangère "CAS" Détection d une carte à autorisation systématique "COUNTRY_CONSISTENCY" Aucun pays ne correspond (pays IP, pays carte, pays client) "NON_GUARANTEED_PAYMENT" Détection d un paiement sans garantie "IPADDR_COUNTRY" Le pays de l adresse IP appartient à la liste grise Cette liste est susceptible de s allonger, veuillez bien en tenir compte dans votre implémentation. Les différentes valeurs possibles pour result sont : Valeur Description "0" Indique que le contrôle est correct "1" Indique que le contrôle est en erreur @Lyra Network- 7/ 42
4.4. transactioninfo Ce type permet de décrire une transaction. Nom du champ Type Description Réponse générale errorcode Int Code d erreur (cf.3) extendederrorcode String Précision sur le code d erreur transactionstatus Int Statut de la transaction (cf. 4.2 pour le détail) Détail transaction shopid String Identifiant de la boutique paymentmethod String Source du paiement : - "E_COMMERCE" : e-commerce - "MAIL_OR_TELEPHONE" : mail ou téléphone - "CALL_CENTER" : centre d appel - "OTHER" : autres contractnumber String N de contrat commerçant orderid String Référence de la commande orderinfo String Description libre de la commande orderinfo2 String Description libre de la commande orderinfo3 String Description libre de la commande transmissiondate Date Date et heure de la transaction transactionid String Identifiant de transaction sequencenb Int Numéro de séquence de la transaction amount Long Montant actuel de la transaction en plus petite unité monétaire initialamount Long Montant initial (avant modification éventuelle) en plus petite unité monétaire devise Int Devise (Code monnaie ISO 4217, Euro : 978) cvamount Long Montant en contre-valeur en plus petite unité monétaire cvdevise Int Devise en contre-valeur (Code monnaie ISO 4217, Euro : 978) presentationdate Date Date de remise demandée type Int 0 = DEBIT, 1 = CREDIT multiplepaiement Int Paiement en plusieurs fois (Non = 0, Oui = 1) ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") Détails carte cardnumber String Numéro de carte cardnetwork String Réseau de carte cardtype String Type de carte cardcountry Int Pays d émission de la carte (Code numérique ISO 3166-1 ex : France=250) cardexpirationdate Date Date expiration de la carte Détails porteur customerid String Code client customertitle String Civilité customername String Nom client customerphone String Téléphone client customermail String Mail client customeraddress String Adresse client customerzipcode String Code postal client customercity String Ville client customercountry String Pays client customerlanguage String Langue client composée du code langue (ISO 639-1) et du code pays (ISO-3166) séparés par le caractère «_». Exemple : fr_fr customerip String Adresse IP @Lyra Network- 8/ 42
Détails Authentification 3D-Secure transactioncondition String " COND_3D_SUCCESS", "COND_3D_FAILURE", "COND_3D_ERROR", "COND_3D_NOTENROLLED", "COND_3D_ATTEMPT", "COND_SSL" (voir detail ci-dessous) vadsenrolled String Enrôlement porteur 3DS vadsstatus String Authentification porteur vadseci String Indicateur de commerce électronique vadsxid String Identifiant transaction 3DS vadscavv String Informations relatives au traitement du cryptogramme de commerce électronique vadscavvalgorithm String Méthode de calcul du cryptogramme de commerce électronique vadssignaturevalid String Signature de l authentification directoryserver String Réseau dont le Directory Server a été contacté Détails de l autorisation authmode String Empreinte ou non "MARK" : avec empreinte "FULL" : sans empreinte markamount Long Montant de l empreinte en plus petite unité monétaire markdevise Int Devise de l empreinte (Code monnaie ISO 4217, Euro : 978) markdate Date Date de l empreinte marknb String Numéro d auto de l empreinte markresult Int Résultat de l empreinte markcvv2_cvc2 String Information relative au traitement du cryptogramme visuel de l empreinte authamount Long Montant de l autorisation en plus petite unité monétaire authdevise Int Devise de l autorisation (Code monnaie ISO 4217, Euro : 978) authdate Date Date de l autorisation authnb String Numéro de l autorisation authresult Int Résultat de l autorisation authcvv2_cvc2 String Information relative au traitement du cryptogramme visuel de l autorisation Détails Garantie & Contrôles locaux warrantlyresult String Garantie de paiement localcontrol Array Tableau des résultats des différents contrôles locaux (cf. 4.3) <LocalControl> Détails Remise (renseignés uniquement si la transaction a été remisée) capturedate Date Date et heure de remise capturenumber Int Numéro de remise rapprochementstatut Int Statut de rapprochement bancaire de la transaction. refundamount Long Montant ayant déjà fait l objet d un remboursement en plus petite unité monétaire refunddevise Int Devise du montant ayant déjà fait l objet d un remboursement (Code monnaie ISO 4217, Euro : 978) litige Bool Litige timestamp long Timestamp permettant la génération de signature unique signature String Signature de la transaction (cf. 5) @Lyra Network- 9/ 42
Liste des valeurs possibles pour le champ authresult et markresult. Valeur Description 00 transaction approuvée ou traitée avec succès 02 contacter l émetteur de carte 03 accepteur invalide 04 conserver la carte 05 ne pas honorer 07 conserver la carte, conditions spéciales 08 approuver après identification 12 transaction invalide 13 montant invalide 14 numéro de porteur invalide 15 Emetteur de carte inconnu 17 Annulation client 19 Répéter la transaction ultérieurement 20 Réponse erronée (erreur dans le domaine serveur) 24 Mise à jour de fichier non supportée 25 Impossible de localiser l enregistrement dans le fichier 26 Enregistrement dupliqué, ancien enregistrement remplacé 27 Erreur en «edit» sur champ de lise à jour fichier 28 Accès interdit au fichier 29 Mise à jour impossible 30 erreur de format 31 identifiant de l organisme acquéreur inconnu 33 date de validité de la carte dépassée 34 suspicion de fraude 38 Date de validité de la carte dépassée 41 carte perdue 43 carte volée 51 provision insuffisante ou crédit dépassé 54 date de validité de la carte dépassée 55 Code confidentiel erroné 56 carte absente du fichier 57 transaction non permise à ce porteur 58 transaction interdite au terminal 59 suspicion de fraude 60 l accepteur de carte doit contacter l acquéreur 61 montant de retrait hors limite 63 règles de sécurité non respectées 68 réponse non parvenue ou reçue trop tard 75 Nombre d essais code confidentiel dépassé 76 Porteur déjà en opposition, ancien enregistrement conservé 90 arrêt momentané du système 91 émetteur de cartes inaccessible 94 transaction dupliquée 96 mauvais fonctionnement du système 97 échéance de la temporisation de surveillance globale 98 serveur indisponible routage réseau demandé à nouveau 99 incident domaine initiateur @Lyra Network- 10/ 42
Détails transactioncondition: Valeur "COND_3D_SUCCESS" " COND_3D_FAILURE" " COND_3D_ERROR" " COND_3D_NOTENROLLED" " COND_3D_ATTEMPT" "COND_SSL" Description Le commerçant et le porteur de la carte sont inscrits au programme 3-D Secure et le porteur s est authentifié correctement. Le commerçant et le porteur de la carte sont inscrits au programme 3-D Secure mais l acheteur n a pas réussi à s authentifier (mauvais mot de passe) Le commerçant participe au programme 3-D Secure mais le serveur Systempay a rencontré un problème technique durant le processus d authentification (lors de la vérification de l inscription de la carte au programme 3D ou de l authentification du porteur). Le commerçant participe au programme 3-D Secure mais la carte du porteur n est pas enrôlée. Le commerçant et le porteur de la carte sont inscrits au programme 3-D Secure mais l acheteur n a pas eu à s authentifier (le serveur de contrôle d accès de la banque qui a émis la carte n implémente que la génération d une preuve de tentative d authentification). Le commerçant n est pas enrôlé à 3D-Secure ou le canal de vente n est pas couvert par cette garantie. La signature permet de valider l intégrité de la réponse, le calcul de cette signature se fait en prenant les paramètres dans l ordre suivant : errorcode, extendederrorcode, transactionstatus, shopid, paymentmethod, contractnumber, orderid, orderinfo, orderinfo2, orderinfo3, transmissiondate, transactionid, sequencenb, amount, initialamount, devise, cvamount, cvdevise, presentationdate, type, multiplepaiement, ctxmode, cardnumber, cardnetwork, cardtype, cardcountry, cardexpirationdate, customerid, customertitle, customername, customerphone, customermail, customeraddress, customerzipcode, customercity, customercountry, customerlanguage, customerip, transactioncondition, vadsenrolled, vadsstatus, vadseci, vadsxid, vadscavvalgorithm, vadscavv, vadssignaturevalid, directoryserver, authmode, markamount, markdevise, markdate, marknb, markresult, markcvv2_cvc2, authamount, authdevise, authdate, authnb, authresult, authcvv2_cvc2, warrantlyresult, capturedate, capturenumber, rapprochementstatut, refoundamount, refunddevise, litige, timestamp @Lyra Network- 11/ 42
4.5. createpaiementinfo Ce type permet de décrire les paramètres pour une création de transaction. Nom du champ Type Description Obligatoire Détail transaction shopid String Identifiant de la boutique transmissiondate Date Date et heure de transmission de la transaction au format W3C, dans le fuseau UTC. Cette valeur devra être sauvegardée par le marchand car elle permettra de valoriser le champ transmissiondate utilisé dans les autres méthodes (remboursement, annulation, recherche, validation, etc.) transactionid String longueur 6 Identifiant de transaction. La longueur est 6 impérativement et le format numérique est obligatoire. L identifiant doit être unique sur une même journée. paymentmethod String Source du paiement : - "EC" : e-commerce - "MOTO" : mail ou téléphone - "CC" : centre d appel - "OTHER" : autres Remarque : La valeur EC impose qu un contrat E-commerce VADS (ERT 24) soit associé à votre boutique. Toutes les autres valeurs nécessitent un contrat VAD (ERT 20). Dans le cas contraire, la requête sera rejetée avec un code d erreur 15 (cf.3) orderid String Référence de la commande orderinfo String Description libre de la commande orderinfo2 String Description libre de la commande orderinfo3 String Description libre de la commande amount Long Montant de la transaction en plus petite unité monétaire devise int Devise (Code monnaie ISO 4217, Euro : 978) presentationdate Date Ce champ permet de définir la date de remise de la transaction, exprimée au format W3C (Ex : 2012-06-08T08:16:43+00:00 Si ce champ n est pas envoyé, la date de remise sera calculée par la plateforme de paiement en fonction de la valeur du paramètre «délai de capture» configuré dans le back office (Menu Paramétrage / boutiques / Configuration). Si le nombre de jours entre la date de remise demandée et la date actuelle est supérieur à 7 jours, une autorisation d 1 euro sera réalisée le jour de la transaction. Ceci afin de vérifier la validité de la carte. L autorisation pour le montant total sera effectuée entre 7 jours et 0 jour avant la date de remise, en fonction du paramétrage de votre boutique (Avec ou Sans autorisations anticipées). Si vous souhaitez être notifié du résultat de cette demande d autorisation, vous devez configurer la règle de notification «URL serveur sur autorisation @Lyra Network- 12/ 42
par Batch» dans l outil de gestion de caisse (Paramétrage/Règles de notifications/) Remarque : Si la carte de crédit utilisée pour le paiement est de type MAESTRO, la règle précédente, basée sur un délai de 7 jours, ne s applique pas. La demande d autorisation est valable 30 jours pour ces cartes. validationmode int Mode de validation des paiements : 0 = Automatique, 1 = Manuelle Détail carte cardnumber String Numéro de carte cardnetwork String Réseau de carte ("AMEX", "CB", "MASTERCARD", "VISA", "MAESTRO", "E-CARTEBLEUE") cardexpirationdate Date Date expiration de la carte. Etant donné que seuls l année et le mois sont pris en compte, il est conseillé de positionner la valeur au dernier jour du mois à 00:00:00 UTC. cvv String Cryptogramme visuel. Ce champ est obligatoire lorsque la carte dispose d un cryptogramme visuel et que l internaute l a saisi. Remarque : Certaines cartes ne possédant pas de CVV, le champ cvv est optionnel dans la méthode create. contractnumber String Numéro de contrat commerçant. Si ce champ est valorisé, merci de faire attention à fournir le bon numéro de contrat en fonction du réseau (par exemple, le contrat CB ne peut pas être utilisé pour les transactions AMEX) Paramètres avancés threedsresult ThreeDsResult Cf. 4.6 subpaymenttype Integer subreference String Ne pas renseigner subpaymentnumber Integer Détail porteur customerid String Code client customertitle String Civilité customername String Nom client customerphone String Téléphone client customermail String Mail client customeraddress String Adresse client customerzipcode String Code postal client customercity String Ville client customercountry String Pays client customerlanguage String Langue client (Code ISO 639-1, sur 2 caractères) customerip String Adresse IP customersendemail bool Envoi e-mail client souhaité. Adresse de livraison shippingcity String Ville shippingcountry String Pays shippingdeliverycompanyname String Nom du transporteur shippingname String Nom client shippingphone String Téléphone client shippingspeed deliveryspeed Type de livraison : STANDARD ou EXPRESS shippingstate String Etat/Région @Lyra Network- 13/ 42
shippingstatus custstatus Type de client : PRIVATE ou COMPANY shippingstreetnumber String Numéro de rue shippingstreet String Adresse shippingstreet2 String Deuxième ligne d adresse shippingdistrict String Quartier Type de livraison : RECLAIM_IN_SHOP RELAY_POINT shippingtype deliverytype RECLAIM_IN_STATION PACKAGE_DELIVERY_COMPANY ETICKET shippingzipcode String Code postal Divers ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") comment String Commentaire «libre» A noter qu en.net, le framework créé des champs de type booléen pour certains les champs facultatifs (voir liste ci-après). Ils permettent d indiquer si le champ facultatif est utilisé ou non : presentationdatespecified validationmodespecified subpaymenttypespecified subpaymentnumberspecified customersendemailspecified @Lyra Network- 14/ 42
4.6. threedsresult Ce type permet de décrire les paramètres de retour 3DS. Nom du champ Type Description Obligatoire brand String Brand de la carte ("VISA" ou "MASTERCARD") enrolled String Statut enrôlement porteur : "Y" : Enrôlé "N" : Non enrôlé "U" : Inconnu authstatus String Statut authentification : "Y" : Authentifié 3DS "N" : Erreur Authentification "U" : Authentification impossible "A" : Essai d authentification eci String ECI xid String XID cavv String CAVV cavvalgorithm String Algorithme CAVV : "0" : HMAC "1" : CVV "2" : CVV_ATN "3" : Mastercard SPA Remarque : Ce champ est facultatif lors de la création d une transaction (méthode create). Il devient obligatoire lorsque le marchand a réalisé le processus 3D-Secure, quelle que soit l issue de l authentification. Cas des cartes non enrôlées (enrolled = "N"): Le marchand devra obligatoirement fournir les champs suivants : brand, enrolled. Les autres champs (authstatus, eci, xid, cavv, et cavvalgorithm) ne devront pas être envoyés. Cas des cartes enrôlées (enrolled = "Y"): Le marchand devra obligatoirement fournir tous les champs: brand, enrolled, authstatus, xid. Dans le cas où l internaute s est correctement authentifié (authstatus= "Y" ou "A") Les champs eci, cavv et cavvalgorithm deviennent obligatoires. Dans le cas où l internaute ne s est pas authentifié (authstatus= "N" ou "U"), les champs eci, cavv et cavvalgorithm ne doivent pas être envoyés Cas des cartes dont le statut d enrôlement est inconnu (enrolled = "U"): Le marchand devra obligatoirement fournir les champs suivants : brand, enrolled. Les autres champs (authstatus, eci, xid, cavv, et cavvalgorithm) ne devront pas être envoyés. @Lyra Network- 15/ 42
5. Description des méthodes 5.1. Création d un paiement (create) La fonction create permet : les paiements «manuels» (de type VAD ERT 20), issus des différents canaux ; les paiements «automatiques» pour lesquels l acquisition des données cartes est réalisée par le commerçant lui-même. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire createinfo createpaiementinfo Cf.4.5 wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, paymentmethod, orderid, orderinfo, orderinfo2, orderinfo3, amount, devise, presentationdate, validationmode, cardnumber, cardnetwork, cardexpirationdate, cvv, contractnumber, threedsresult, subpaymenttype, subreference, subpaymentnumber, customerid, customertitle, customername, customerphone, customermail, customeraddress, customerzipcode, customercity, customercountry, customerlanguage, customerip, customersendemail, ctxmode, comment Note : si le paramètre threedsresult est non renseigné, la valeur prise en compte dans le calcul de signature est vide (comme tous les champs non renseignés), par contre si il est renseigné il est calculé de la sorte : brand+enrolled+authstatus+eci+xid+cavv+cavvalgorithm soit par exemple : VISA+Y+Y++XidXidXidXidXidXidXidXidXidX+CavvCavvCavvCavvCavvCavvCavv+2 Cette fonction retourne une réponse du type transactioninfo (cf.4.4). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. Remarque : Le champ transmissiondate représente la date et l heure de l appel de la méthode. Si la valeur de ce champ est trop éloignée de l heure réelle, la requête sera refusée (errorcode 6). Le champ extendederrorcode prendra alors la valeur du champ erroné @Lyra Network- 16/ 42
Ci-dessous un exemple de fichier xml généré lors de l appel de la méthode create le 24/04/2012 à 09h33 (heure de Paris): <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ns1="http://v3.ws.vads.lyra.com/"> <SOAP-ENV:Body> <ns1:create> <createinfo> <shopid>48337286</shopid> <transmissiondate>2012-04-24t07:33:18+00:00</transmissiondate> <transactionid>073318</transactionid> <paymentmethod>ec</paymentmethod> <orderid>orderid</orderid> <amount>3000</amount> <devise>978</devise> <cardnumber>4970100000000003</cardnumber> <cardnetwork>cb</cardnetwork> <cardexpirationdate>2012-12-30t23:00:00+00:00</cardexpirationdate> <cvv>123</cvv> <ctxmode>test</ctxmode> </createinfo> <wssignature>79b39d396539d78dfa799c6d8794aa3a8851f0cb</wssignature> </ns1:create> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Et le calcul de signature correspondant : 48337286+20120424+073318+EC+orderId++++3000+978+++4970100000000003+CB+20121230+123+++++ +++++++++++++TEST++certificat @Lyra Network- 17/ 42
5.2. Annulation d une transaction (cancel) La fonction cancel permet d annuler définitivement une transaction, non encore remisée, disposant d un des statuts suivants : A valider A valider et autoriser En attente En attente d auto En attente de remise Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction à annuler au format W3C transactionid String Identifiant de la transaction à annuler sequencenb Int Numéro de séquence de la transaction à annuler. Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, comment Cette fonction retourne une réponse du type standardresponse (cf. 4.24.2). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. @Lyra Network- 18/ 42
5.3. Validation d une transaction (validate) La fonction validate permet d autoriser la remise en banque d une transaction à la date de présentation demandée dans le paiement original. Les transactions pouvant faire l objet d une validation possèdent l un des statuts suivants : A valider A valider et autoriser Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction à valider au format W3C transactionid String Identifiant de la transaction à valider sequencenb Int Numéro de séquence de la transaction à valider. Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, comment Cette fonction retourne une réponse du type standardresponse (cf.4.2). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST», il prend alors comme valeur la chaine qui a été utilisée pour le calcul de signature. @Lyra Network- 19/ 42
5.4. Forçage d une transaction (force) La fonction force permet aux commerçants de transmettre le n d autorisation d une transaction suite à appel phonie. Seules les transactions de statut «à forcer» peuvent bénéficier de cette fonction. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction à forcer au format W3C transactionid String Identifiant de la transaction à forcer Int Numéro de séquence de la transaction à forcer. sequencenb Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") autorisationnb String Numéro d autorisation autorisationdate Date Date et heure de la demande d autorisation au format W3C comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, autorisationnb, autorisationdate, comment. Cette fonction retourne une réponse du type standardresponse (cf.4.2). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST», il prend alors comme valeur la chaine qui a été utilisée pour le calcul de signature. @Lyra Network- 20/ 42
5.5. Modification d une transaction (modify) La fonction modify permet de modifier le montant d une transaction (à la baisse) ou d en modifier la date de remise souhaitée. Les transactions pouvant faire l objet d une modification possèdent l un des statuts suivant : A valider A valider et autoriser En attente En attente d auto En attente de remise Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction initiale au format W3C transactionid String Identifiant de la transaction à modifier Int Numéro de séquence de la transaction à modifier. sequencenb Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") amount Long Montant demandé en plus petite unité monétaire devise Int Devise (Code monnaie ISO 4217, Euro : 978) remisedate Date Date de remise demandée au format W3C comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, amount, devise, remisedate, comment. Cette fonction retourne une réponse du type standardresponse (cf.4.2). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST», il prend alors comme valeur la chaine qui a été utilisée pour le calcul de signature. Si aucune information n est modifiée, la requête sera rejetée avec un code erreur 26 : aucun changement. @Lyra Network- 21/ 42
5.6. Remboursement d une transaction (refund) La fonction refund permet de rembourser le porteur. Les transactions pouvant faire l objet d un remboursement possèdent le statut suivant : Remisé Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction à rembourser au format W3C transactionid String Identifiant de la transaction à rembourser Int Numéro de séquence de la transaction à rembourser. sequencenb Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") newtransactionid String Identifiant de la transaction créée amount Long Montant à rembourser en plus petite unité monétaire devise Int Devise (Code monnaie ISO 4217, Euro : 978) presentationdate Date Date de remise demandée au format W3C validationmode int Mode de validation de la transaction de crédit: 0 = Automatique, 1 = Manuelle comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, newtransactionid, amount, devise, presentationdate, validationmode, comment Cette fonction retourne une réponse du type transactioninfo (cf4.4). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. Remarque importante Si la carte est expirée lors de la demande de remboursement, la requête ne sera plus rejetée en errorcode 13. Une transaction refusée pour motif carte expirée sera créée. La réponse contiendra les valeurs suivantes : errorcode : 0 transactionstatus : 8 @Lyra Network- 22/ 42
5.7. Duplication d une transaction (duplicate) La fonction duplicate permet de créer une nouvelle transaction ayant exactement les mêmes caractéristiques que la transaction qui a servi de base à la duplication. Les transactions pouvant faire l objet d un remboursement possèdent le statut suivant : Remisé Expiré Annulé Refusé Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction initiale au format W3C transactionid String Identifiant de la transaction à dupliquer Int Numéro de séquence de la transaction à dupliquer. sequencenb Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") orderid String Référence de la commande orderinfo String Description libre de la commande orderinfo2 String Description libre de la commande orderinfo3 String Description libre de la commande amount Long Montant en plus petite unité monétaire devise Int Devise (Code monnaie ISO 4217, Euro : 978) newtransactionid String Identifiant de la transaction créée presentationdate Date Date de remise demandée au format W3C validationmode int 0 = Automatique, 1 = Manuelle comment String Commentaire «libre» wssignature String Signature (cf.6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, orderid, orderinfo, orderinfo2, orderinfo3, amount, devise, newtransactionid, presentationdate, validationmode, comment Cette fonction retourne une réponse du type transactioninfo (cf.4.4). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. @Lyra Network- 23/ 42
5.8. Recherche des détails d une transaction (getinfo) La fonction getinfo permet d interroger une transaction pour en connaître ses différents attributs. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date ET heure de la transaction au format W3C transactionid String Identifiant de la transaction à rechercher Int Numéro de séquence de la transaction à sequencenb rechercher. Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode Cette fonction retourne une réponse du type transactioninfo (cf.4.4). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. @Lyra Network- 24/ 42
5.9. Modification et validation d une transaction (modifyandvalidate) La fonction modifyandvalidate permet de modifier le montant d une transaction (à la baisse) ou d en modifier la date de remise souhaitée et de valider la transaction si besoin. Les transactions pouvant faire l objet d une modification possèdent l un des statuts suivant : A valider A valider et autoriser En attente En attente d auto En attente de remise Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire shopid String Identifiant de la boutique transmissiondate Date Date et heure de la transaction au format W3C transactionid String Identifiant de transaction à modifier/valider Int Numéro de séquence de la transaction à modifier sequencenb et/ou à valider. Vaut "1" pour un paiement unitaire. Prend la valeur du numéro d échéance dans le cas d un paiement en plusieurs fois. ctxmode String Contexte de sollicitation de la plateforme de paiement ("TEST", "PRODUCTION") amount Long Montant demandé en plus petite unité monétaire devise Int Devise (Code monnaie ISO 4217, Euro : 978) remisedate Date Date remise demandée comment String Commentaire «libre» wssignature String Signature (cf. 6) Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant : shopid, transmissiondate, transactionid, sequencenb, ctxmode, amount, devise, remisedate, comment Cette fonction retourne une réponse du type standardresponse (cf.4.2). NB : le code d erreur étendu (extendederrorcode) est renseigné uniquement lorsque l errorcode est 5 (Mauvaise signature) et que le champ ctxmode est «TEST». Il prend alors comme valeur la chaine qui a été utilisé pour le calcul de signature. Si aucune information n est modifiée, la requête sera rejetée avec un code erreur 26 : aucun changement. @Lyra Network- 25/ 42
6. 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é. Les champs de type date doivent être formatés de la manière suivante : YYYYMMDD en UTC soit pour le 1 er Février 2009 : 20090201. ATTENTION aux heures, par exemple le 23/02/2010 00:30:00 heure française (GMT+1 ou GMT+2) donne 20100222! 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. 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 Ce qui donne après hachage (signature) : 88ff8fc1897ac4edf34c5e2327be5adde76e17d6 En mode TEST, en cas de mauvais calcul de signature, le code erreur de la fonction renvoie 5, la chaine de caractère utilisée pour la signature côté serveur est alors renvoyée dans le champ extendederrorcode. @Lyra Network- 26/ 42
7. Maintien de la session HTTP entre 2 requêtes Important : L architecture de la plateforme de paiement reposant sur un ensemble de serveurs avec répartition de charge, il est nécessaire que chaque requête concernant un même paiement dans un laps de temps très court, soit réalisée avec la même session HTTP afin d assurer la continuité du processus. Pour cela, à chaque requête, une session est créée coté serveur. L ID de la session est renvoyé dans l entête HTTP de la réponse. Il devra être retourné dans les requêtes suivantes afin que la requête soit traitée par le même serveur, évitant ainsi à votre requête d être rejetée car la transaction ne serait pas encore disponible sur les autres serveurs. 7.1. Exemple d application Vous souhaitez créer un paiement à remettre dans 30 jours en mode de validation manuelle. Une fois le paiement accepté vous décidez de changer la date de remise pour le lendemain et de valider la transaction. Vous appelez le web service de création de paiement (create). La plateforme vérifie la présence d un ID de session dans l en-tête HTTP de votre requête. Comme rien n a été précisé, une nouvelle session et un nouvel ID son créés. Systempay procède ensuite au traitement de votre requête et envoie sa réponse en indiquant dans l en-tête HTTP l identifiant de session attribué ainsi que le nom du serveur ayant traité la requête: Exemple d entête de requête : POST /vads-ws/v3 HTTP/1.1 Host: paiement.systempay.fr Connection: Keep-Alive User-Agent: PHP-SOAP/5.2.10 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Content-Length: 482 Exemple d entête de réponse : HTTP/1.1 200 OK Date: Thu, 25 Oct 2012 09:48:06 GMT Server: Apache Set-Cookie: JSESSIONID=00A19F16AD158A3C4862EBB84896E9FE.sirisvad2; Path=/vads-ws; Secure; HttpOnly Access-Control-Allow-Origin: * Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked Content-Type: text/xml;charset=utf-8 Dans les en-têtes HTTP de la réponse, vous récupérez le cookie JSESSIONID : Vous initialisez le cookie JSESSIONID de votre en-tête HTTP. Vous appelez le web service de modification et de validation du paiement (modifyandvalidate). @Lyra Network- 27/ 42
Exemple d entête de requête : POST /vads-ws/v3 HTTP/1.1 Host: paiement.systempay.fr Connection: Keep-Alive User-Agent: PHP-SOAP/5.2.10 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Content-Length: 482 Cookie: JSESSIONID=00A19F16AD158A3C4862EBB84896E9FE.sirisvad2; La plateforme vérifie la présence d un ID de session dans l en-tête HTTP de votre requête. La requête est ensuite envoyée au serveur ayant généré la session. Si la session existe, elle est réutilisée, sinon une nouvelle session et un nouvel identifiant seront créés. Systempay procède au traitement de la requête et envoie sa réponse. Remarque : L ID de session sera renvoyé dans l en-tête HTTP de la réponse uniquement dans le cas où une nouvelle session a été créée. Il est donc conseillé de tester systématiquement la présence du cookie dans l en-tête HTTP de la réponse et d utiliser l ID de session présent avec d enchainer un autre appel (getinfo par exemple). Exemple d en-tête HTTP de réponse utilisant la même session: HTTP/1.1 200 OK Date: Thu, 25 Oct 2012 09:48:07 GMT Server: Apache Secure; HttpOnly Access-Control-Allow-Origin: * Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked Content-Type: text/xml;charset=utf-8 (Pas d information sur l identifiant de session) Exemple d en-tête HTTP de réponse avec une nouvelle session: HTTP/1.1 200 OK Date: Thu, 25 Oct 2012 09:48:06 GMT Server: Apache Set-Cookie: JSESSIONID=F6D2CCC8B075077843724ADDDE887EE2.sirisvad2; Path=/vads-ws; Secure; HttpOnly Access-Control-Allow-Origin: * Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked Content-Type: text/xml;charset=utf-8 (Présence du Set-Cookie précisant l identifiant de la nouvelle session) @Lyra Network- 28/ 42
7.2. Exemple d implémentation en PHP Pour récupérer l en-tête HTTP de la réponse vous devez utiliser la fonction getlastresponseheaders() /* La méthode ci-dessous permet de récupérer l entête HTTP de la réponse */ /* $client étant une instance du client SOAP utilisé pour appeler les WS */ $header = $client-> getlastresponseheaders(); Pour récupérer ensuite l identifiant de session vous pouvez utiliser le code suivant : /* Dans la chaîne de caractère obtenue, nous recherchons la présence de l ID de la session HTTP, stockée dans l élément "JSESSIONID" : */ if(preg_match("#jsessionid=([a-za-z0-9\.]+)#",$header, $matches)){ $JSESSIONID = $matches[1];; Pour initialiser le cookie vous devez utiliser la fonction setcookie() $cookie= $JSESSIONID; $client-> setcookie('jsessionid', $cookie); @Lyra Network- 29/ 42
8. Exemples de cinématique de paiement avec gestion des cas d échec 8.1. Livraison différée de marchandise Demande de paiement (Appel ws create) Analyse de la réponse Paiement accepté (transactionstatus = 1 : «A valider»): Enregistrement du résultat en BDD Affichage du message de succès pour l acheteur. Paiement refusé (transactionstatus = 8 : «Refusé»): Enregistrement du résultat en BDD Affichage du message d échec pour l acheteur. Proposer de repasser la commande ou le paiement. Absence de réponse (cas du timeout) Mettre à jour la commande dans un statut «timeout» Afficher un message de traitement du paiement en cours (pour cause de ralentissement) indiquant que le site marchand reviendra rapidement vers l acheteur positivement ou négativement lorsque le paiement sera finalisé. Si le site marchand décide de considérer ce paiement comme accepté, il faudra toutefois assumer que l acheteur peut ensuite recevoir un email lui indiquant que finalement le paiement a été refusé. Préparation de la commande et validation du paiement (Appel ws validate) Analyse de la réponse Validation acceptée (errorcode= 0 et transactionstatus= 4) Déclencher l expédition du colis. Absence de réponse (cas du timeout) Mette à jour la commande dans un statut timeout Mettre le colis en attente Exécution d un batch en différé sur l ensemble des commandes dans l état «timeout» : Appel ws getinfo si transactionstatus = 1 «A valider» : mettre à jour le résultat en BDD, déclencher de la préparation de la commande si transactionstatus = 4 «En attente de remise» : mettre à jour le résultat en BDD, déclencher l expédition du colis si transactionstatus = 8 «Refusée» Contacter le client par mail (ou téléphone) pour l avertir du refus de paiement. Le batch pourra idéalement être programmé toutes les 10 ou 15 min. @Lyra Network- 30/ 42
8.2. Vente de biens immatériels type VOD Demande de paiement (Appel ws create) Analyse de la réponse Paiement accepté (transactionstatus = 1 : «A valider») : Enregistrement de la commande dans un statut «A valider» Affichage du message de succès pour l acheteur. Paiement refusé (transactionstatus = 8 : «Refusé»): Enregistrement du résultat Affichage du message d échec pour l acheteur. Proposer de repasser la commande ou le paiement. Absence de réponse (cas du timeout) : Mettre à jour la commande dans un statut «refusé» Afficher un message de refus Proposer de repasser la commande ou le paiement En différé, exécuter un batch sur l ensemble des commandes dans l état «A valider» qui va procéder à la validation du paiement et au changement de la date de remise à J : Appel ws getinfo : Analyse de la réponse Si transactionstatus = 1 : «A valider» : Appel ws ModifyAndValidate Réponse valide (errorcode 0) : - mettre à jour la commande dans l état «Payée» Absence de réponse (cas du timeout) - laisser la commande dans l état «A valider» Si transactionstatus = 4 : «En attente de remise» : Mise à jour de l état de la commande. Absence de réponse Laisser le statut «A valider». Remarque : L état 7 (transaction expirée) ne devrait pas arriver. Il voudrait dire que vous n avez pas eu le temps de faire la validation du paiement avant le batch de remise en banque. Pour éviter cette situation, il est recommandé de travailler en validation manuelle avec une date de capture au moins à J+1). @Lyra Network- 31/ 42
9. Migration de la v2 à la v3 9.1. Changement de signature pour la méthode create Suite à l ajout de paramètres optionnels, voici les champs (en rouge) à ajouter dans le calcul de signature : shopid, transmissiondate, transactionid, paymentmethod, orderid, orderinfo, orderinfo2, orderinfo3, amount, devise, presentationdate, validationmode, cardnumber, cardnetwork, cardexpirationdate, cvv, contractnumber, threedsresult, subpaymenttype, subreference, subpaymentnumber, customerid, customertitle, customername, customerphone, customermail, customeraddress, customerzipcode, customercity, customercountry, customerlanguage, customerip, customersendemail, ctxmode, comment Note : Dans le cadre de la migration, le paramètre threedsresult est sans doute non renseigné, la valeur prise en compte dans le calcul de signature est vide (comme tous les champs non renseignés), par contre si il est renseigné il sera calculé de la sorte : brand+enrolled+authstatus+eci+xid+cavv+cavvalgorithm soit par exemple : VISA+Y+Y++XidXidXidXidXidXidXidXidXidX+CavvCavvCavvCavvCavvCavvCavv+2 9.2. Changement de signature pour le retour de transactioninfo Suite à l ajout d un nouveau paramètre dans le type TransactionInfo, voici le champ (en rouge) à ajouter dans le calcul de signature : errorcode, extendederrorcode, transactionstatus, shopid, paymentmethod, contractnumber, orderid, orderinfo, orderinfo2, orderinfo3, transmissiondate, transactionid, sequencenb, amount, initialamount, devise, cvamount, cvdevise, presentationdate, type, multiplepaiement, ctxmode, cardnumber, cardnetwork, cardtype, cardcountry, cardexpirationdate, customerid, customertitle, customername, customerphone, customermail, customeraddress, customerzipcode, customercity, customercountry, customerlanguage, customerip, transactioncondition, vadsenrolled, vadsstatus, vadseci, vadsxid, vadscavvalgorithm, vadscavv, vadssignaturevalid, directoryserver, authmode, markamount, markdevise, markdate, marknb, markresult, markcvv2_cvc2, authamount, authdevise, authdate, authnb, authresult, authcvv2_cvc2, warrantlyresult, capturedate, capturenumber, rapprochementstatut, refoundamount, refunddevise, litige, timestamp 9.3. Note aux utilisateurs PHP Les paramètres de retour ne sont plus ambigus et ne sont plus retournés en double dans un tableau, il faut modifier votre code d interprétation du retour en accédant directement aux champs et non plus en passant par un tableau intermédiaire. @Lyra Network- 32/ 42
10. Exemple d implémentation JAVA Cet exemple utilise les webservices client de Jboss. 10.1. Générer les stubs depuis le wsdl Afin d utiliser les Webservices, il faut générer le code qui va communiquer avec les webservices : wsconsume.bat -k -p com.lyra.vads.ws.stubs https://paiement.systempay.fr/vads-ws/v3?wsdl 10.2. Exemple de code pour générer la signature Voici un exemple de classe pour générer la signature. import java.security.messagedigest; import java.text.simpledateformat; import java.util.date; public class Signature { static public final String SEPARATOR = "+"; static final String key = "1122334455667788"; public static String createsignature(object... params) { StringBuilder builder = new StringBuilder(); for (int i = 0; i < params.length; i++) { if (i!= 0) { builder.append(separator); if (params[i]!= null) { if (params[i] instanceof Date params[i] instanceof XMLGregorianCalendar) { Date date = null; if (params[i] instanceof XMLGregorianCalendar) { XMLGregorianCalendar xmldate = (XMLGregorianCalendar) params[i]; date = xmldate.togregoriancalendar().gettime(); else { date = (Date) params[i]; SimpleDateFormat mydateformat = new SimpleDateFormat("yyyyMMdd"); mydateformat.settimezone(timezone.gettimezone("utc")); builder.append(mydateformat.format(date)); else if (params[i] instanceof Boolean) { if ((Boolean) params[i]) { builder.append(1); else { builder.append(0); else { builder.append(params[i]); String tosign = builder.tostring() + SEPARATOR + key; return encode(tosign); public static String encode(string src) { try { MessageDigest md; md = MessageDigest.getInstance("SHA-1"); byte bytes[] = src.getbytes("utf-8"); @Lyra Network- 33/ 42
md.update(bytes, 0, bytes.length); byte[] sha1hash = md.digest(); return converttohex(sha1hash); catch (Exception e) { throw new RuntimeException(e); private static String converttohex(byte[] sha1hash) { StringBuilder builder = new StringBuilder(); for (int i = 0; i < sha1hash.length; i++) { byte c = sha1hash[i]; addhex(builder, (c >> 4) & 0xf); addhex(builder, c & 0xf); return builder.tostring(); private static void addhex(stringbuilder builder, int c) { if (c < 10) builder.append((char) (c + '0')); else builder.append((char) (c + 'a' - 10)); 10.3. Exemple de code pour annuler un paiement Remplacer XXXXXXXX par votre numéro commerçant et 123456 par votre numéro de transaction unique par jour. public static void main(string[] args) throws Exception { URL wsdlurl = new URL( "https://paiement.systempay.fr/vads-ws/v3?wsdl"); QName qname = new QName("http://v3.ws.vads.lyra.com/", "StandardWS"); Service service = Service.create(wsdlURL, qname); StandardWs port = service.getport(standardws.class); GregorianCalendar gcalendar = new GregorianCalendar(); gcalendar.settime(new Date()); XMLGregorianCalendar xmlcalendar = DatatypeFactory.newInstance().newXMLGregorianCalendar(gCalendar); String signature = createsignature("xxxxxxxx", xmlcalendar, "123456", 1, "TEST", "Cancel comment"); StandardResponse response = port.cancel("xxxxxxxx", xmlcalendar, "123456", 1, "TEST", "Cancel comment", signature); System.out.println("WS Cancel Result : " + response.geterrorcode() + " / " + response.getextendederrorcode() + " / " + response.gettransactionstatus()); @Lyra Network- 34/ 42
10.4. Exemple de code pour créer un paiement Remplacer XXXXXXXX par votre numéro commerçant et 123456 par votre numéro de transaction unique par jour. public static void main(string[] args) throws Exception { URL wsdlurl = new URL( "https://paiement.systempay.fr/vads-ws/v3?wsdl"); QName qname = new QName("http://v3.ws.vads.lyra.com/", "StandardWS"); Service service = Service.create(wsdlURL, qname); StandardWs port = service.getport(standardws.class); GregorianCalendar gcalendar = new GregorianCalendar(); gcalendar.settime(new Date()); XMLGregorianCalendar xmlcalendar = DatatypeFactory.newInstance().newXMLGregorianCalendar(gCalendar); XMLGregorianCalendar expdate = DatatypeFactory.newInstance().newXMLGregorianCalendar(2010, 12, 31, 0, 0, 0, 0, 0); CreatePaiementInfo mypayment = new CreatePaiementInfo(); // Numero commercant mypayment.setshopid("xxxxxxxx"); // Date de transmission mypayment.settransmissiondate(xmlcalendar); // Numero de transaction mypayment.settransactionid("123456"); // VPC mypayment.setpaymentmethod("ec"); // Id de la commande... mypayment.setorderid("macommande"); // Info sur la commande => Facultatif! mypayment.setorderinfo("info commande"); // Montant en centimes mypayment.setamount(3000); // Devise => 978 Euros mypayment.setdevise(978); // Date de la remise mypayment.setpresentationdate(xmlcalendar); // Validation automatique mypayment.setvalidationmode(0); // Numero de la carte bleue mypayment.setcardnumber("4970100000000000"); // Reseau de la carte mypayment.setcardnetwork("cb"); // Date expiratiration carte mypayment.setcardexpirationdate(expdate); // CVV mypayment.setcvv("000"); // Mode de connexion... mypayment.setctxmode("test"); // Un commentaire eventuel mypayment.setcomment("creation Par WebService"); String signature = Signature.createSignature(myPayment.getShopId(), mypayment.gettransmissiondate(),mypayment.gettransactionid(), mypayment.getpaymentmethod(), mypayment.getorderid(), mypayment.getorderinfo(), mypayment.getorderinfo2(), mypayment.getorderinfo3(), mypayment.getamount(), mypayment.getdevise(),mypayment.getpresentationdate(), mypayment.getvalidationmode(), mypayment.getcardnumber(), mypayment.getcardnetwork(), mypayment.getcardexpirationdate(), mypayment.getcvv(), mypayment.getcontractnumber(), null, mypayment.getsubpaymenttype(), mypayment.getsubreference(), mypayment.getsubpaymentnumber(), mypayment.getcustomerid(), mypayment.getcustomertitle(), mypayment.getcustomername(), mypayment.getcustomerphone(), mypayment.getcustomermail(), mypayment.getcustomeraddress(), mypayment.getcustomerzipcode(), mypayment.getcustomercity(), mypayment.getcustomercountry(), @Lyra Network- 35/ 42
mypayment.getcustomerlanguage(), mypayment.getcustomerip(), mypayment.iscustomersendemail(), mypayment.getctxmode(), mypayment.getcomment()); TransactionInfo resptransactioninfo = port.create(mypayment, signature); System.out.println("WS Result : " + resptransactioninfo.geterrorcode() + " / " + resptransactioninfo.getextendederrorcode() + " / " + resptransactioninfo.gettransactionstatus()); @Lyra Network- 36/ 42
11. Exemple d implémentation en C# 11.1. Exemple de code pour générer la signature private static string CalculateSHA1(string text, System.Text.Encoding enc) { byte[] buffer = enc.getbytes(text); System.Security.Cryptography.SHA1CryptoServiceProvider cryptotransformsha1 = new System.Security.Cryptography.SHA1CryptoServiceProvider(); string hash = BitConverter.ToString( cryptotransformsha1.computehash(buffer)).replace("-", ""); return hash; public static string buildsignature(string key, params object[] list) { const Char SEPARATOR = '+'; System.Text.StringBuilder builder = new System.Text.StringBuilder(); for (int i = 0; i < list.length; i++) { if (i!= 0) { builder.append(separator); if (list[i]!= null) { if (list[i] is DateTime) { DateTime date = (DateTime)list[i]; builder.append(date.tostring("yyyymmdd")); else if (list[i] is Boolean) { if ((Boolean)list[i]) { builder.append(1); else { builder.append(0); else { builder.append(list[i]); String tosign = builder.tostring() + SEPARATOR + key; return CalculateSHA1(toSign, System.Text.Encoding.UTF8); @Lyra Network- 37/ 42
11.2. Calcul de signature : fonction create public static string buildsignaturecreate(string key, fr.systempay.paiement.v3.createpaiementinfo create) { return buildsignature(key, create.shopid, create.transmissiondate, create.transactionid, create.paymentmethod, create.orderid, create.orderinfo, create.orderinfo2, create.orderinfo3, create.amount, create.devise, create.presentationdatespecified?(object)create.presentationdate : null, create.validationmodespecified?(object)create.validationmode:null, create.cardnumber, create.cardnetwork, create.cardexpirationdate, create.cvv, create.contractnumber, create.threedsresult, create.subpaymenttypespecified? (Object)create.subPaymentType : null, create.subreference, create.subpaymentnumberspecified?(object)create.subpaymentnumber : null, create.customerid, create.customertitle, create.customername, create.customerphone, create.customermail, create.customeraddress, create.customerzipcode, create.customercity, create.customercountry, create.customerlanguage, create.customerip, create.customersendemailspecified?(object)create.customersendemail : null, create.ctxmode, create.comment ); A noter que cet exemple tient compte de la présence des booléens (en gras) créés par le framework.net @Lyra Network- 38/ 42
12. Annexes 12.1. Listes des cartes de test Ci-dessous la liste des numéros de carte à utiliser en mode TEST : Numéro de carte (CB MasterCard Maestro) Résultat du test 4970100000000000-5970100300000000 - 5000550000000000 Paiement accepté avec authentification 3-D Secure 4970100000000009 5970100300000009-5000550000000009 Paiement avec authentification 3-D Secure interactive 4970100000000003-5970100300000003 - 5000550000000003 Paiement accepté, commerçant non enrôlé 3-D Secure 4970100000000001-5970100300000001 - 5000550000000001 Paiement accepté, internaute non enrôlé 3-D Secure 4970100000000002-5970100300000002 - 5000550000000002 Paiement refusé, transaction à forcer, contacter l'émetteur de carte 4970100000000007-5970100300023006 - 50005500 00023006 Paiement accepté, garantie de paiement = NO 4970100000000097-5970100300000097 - 5000550000000097 4970100000000098-5970100300000098 - 5000550000000098 4970100000000099-5970100300000099 - 5000550000000099 Paiement refusé pour cause d'authentification 3-D Secure échouée, l'internaute n'est pas parvenu à s'authentifier Paiement refusé (autorisation refusée pour cause de plafond dépassé) Paiement refusé, autorisation refusée suite à erreur dans le cryptogramme visuel saisi La date d expiration et le cryptogramme sont à votre libre choix (Ex: date mars 2020 et cryptogramme = 123). Toutes les transactions réalisées en mode TEST sont visibles par les personnes habilitées sur le back office, dans le menu Gestion/ Transactions de TEST». Les résultats des tests ci-dessus sont conditionnés par l état d enrôlement de votre contrat. Tant que vous ne recevez pas le mail vous informant de l activation de la garantie 3D- Secure, les paiements de tests seront réalisés sans 3DS. @Lyra Network- 39/ 42