Définition des Webservices V4

Transcription

1 Définition des Webservices V4 Payzen Version 1.4 Description des webservices v4 1/56

2 Historique du document Version Auteur Date Commentaires 1.4 Lyra-Network 06/12/ Lyra-Network 01/08/ Lyra-Network 10/07/2013 Ajout de la méthode create 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 du code d erreur 27 Montant non autorisé. Détails ajoutés sur le code erreur 9 Erreur technique. Ajout de précision sur les champs validationmode, et sequencenb Ajout de précision sur le champ présentationdate dans le cas d une carte MAESTRO Ajout des méthodes cancel, force, refund, duplicate, getinfo et validate. 1.1b Lyra-Network 05/07/2013 Précisions apportées sur l utilisation du champ paymentsource. 1.1a Lyra-Network 20/06/2013 Mise à jour de la liste des codes retour autorisation 1.1 Lyra-Network 14/05/2013 Passage du wsdl en version 4.3 Ajout du service modify Modification du type transactioninfo : ajout du champ transactionstatuslabel Modification du type transactionpaymentgeneralinfo : ajout du champ effectivecreationdate Modification du type transactioncardinfo : ajout des champs cardproductcode et cardbankcode 1.0c Lyra-Network 21/03/2013 Ajout du chapitre Notions de timeout Ajout d exemple de cinématiques de paiement avec gestion des timeout 1.0b Lyra-Network 13/03/2013 Ajout des numéros de cartes de test en annexe. 1.0a Lyra-Network 21/01/2013 Passage du wsdl en version 4.1 Mise à jour du calcul de signature de l objet createcustomerinfo. Ajout des codes renvoyés pour le champ authresult Mise à jour des valeurs pour le champ localcontrol Ajout de l errorcode 26 Précision apportées sur le champ cvv 1.0 Lyra-Network 18/06/2012 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. Description des webservices v4 2/56

3 1. Présentation Notions de timeout Description des codes d erreurs Description des types createpaymentinfo createpaymentgeneralinfo createcardinfo createsubpaymentinfo createcustomerinfo createshippinginfo createextrainfo custstatus deliveryspeed deliverytype extinfo createwiththreedsresponse verespareqinfo transactioninfo transactionpaymentgeneralinfo transactioncardinfo transactionthreedsinfo transactionauthorizationdsinfo transactionmarkinfo transactionwarrantydetailsnfo localcontrol transactioncaptureinfo transactioncustomerinfo transactionshippinginfo transactionextrainfo paymentcreationinfo threedsresult standardresponse Signature Statut d une transaction Description des méthodes Maintien de la session HTTP entre chaque requête Création d un paiement avec authentification 3D-Secure : Cinématique du paiement : Détails de la méthode createwiththreeds : Redirection vers l ACS : Récupération de la réponse de l ACS : Analyse de l authentification 3DS et finalisation du paiement (finalyzewiththreeds) Modification d une transaction (modify) Création d un paiement avec 3D-Secure intégrateur ou sans 3D-Secure (create) Annulation d une transaction (cancel) Forçage d une transaction (force) Remboursement d une transaction (refund) Duplication d une transaction (duplicate) Recherche des détails d une transaction (getinfo) Validation d une transaction (validate) Annexes Cartes de test Exemple d implémentation en PHP : calcul de signature (méthode create) Exemples de cinématique de paiement avec gestion des cas d échec Description des webservices v4 3/56

4 1. PRESENTATION Ce document présente les webservices qui permettent de créer des transactions (avec ou sans authentification 3D-Secure) et d automatiser les opérations réalisables depuis le back office. 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 chiffré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. (cf. chapitre Signature). 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. 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. Description des webservices v4 4/56

5 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 en annexes. Description des webservices v4 5/56

6 3. DESCRIPTION DES CODES D ERREURS TransactionInfo : Error Error Type Code Code Type 0 Action réalisée avec succès 62 Paramètre orderinfo2 invalide 1 Action non autorisée. 63 Paramètre orderinfo3 invalide 2 Transaction non trouvée 64 Paramètre paymentsource invalide 3 Transaction pas dans le bon état 65 Paramètre cardnumber invalide 4 Transaction existe déjà 66 Paramètre contractnumber invalide 5 Mauvaise signature 67 Paramètre customerid invalide 6 Mauvaise date 68 Paramètre customertitle invalide 10 Mauvais montant 69 Paramètre customername invalide 11 Mauvaise devise 70 Paramètre customerphone invalide 12 Type de carte inconnu 71 Paramètre customermail invalide 13 Paramètre date d expiration invalide 72 Paramètre customeraddress invalide 14 Paramètre cvv invalide 73 Paramètre customerzipcode invalide 15 Contrat inconnu 74 Paramètre customercity invalide 16 Paramètre Numéro de carte invalide 75 Paramètre customercountry invalide 17 Identifiant non trouvé 76 Paramètre customerlanguage invalide 18 Identifiant non valide (Résilié, ) 77 Paramètre customerip invalide 19 Subscription non trouvée 78 Paramètre customersendmail invalide 20 Subscription non valide 79 Paramètre customermobilephone invalide 21 Identifiant déjà existant 80 Paramètre subpaiementtype invalide 22 Création d identifiant refusé 81 Paramètre subreference invalide 27 Montant non autorisé 82 Paramètre initialamount invalide 40 Plage non trouvée 83 Paramètre occinitialamount invalide 50 Paramètre siteid invalide 84 Paramètre effectdate invalide 51 Paramètre transmissiondate invalide 85 Paramètre state invalide 52 Paramètre transactionid invalide 90 Paramètre enrolled invalide 53 Paramètre ctxmode invalide 91 Paramètre authstatus invalide 54 Paramètre comment invalide 92 Paramètre eci invalide 55 Paramètre AutoNb invalide 93 Paramètre xid invalide 56 Paramètre AutoDate invalide 94 Paramètre cavv invalide 57 Paramètre capturedate invalide 95 Paramètre cavvalgo invalide 58 Paramètre newtransactionid invalide 96 Paramètre brand invalide 59 Paramètre validationmode invalide 98 Paramètre requestid invalide 60 Paramètre orderid invalide 99 Autre erreur 61 Paramètre orderinfo1 invalide verespareqinfo : Error Error Description Code Code Description 0 Action réalisée avec succès 9 Erreur technique 1 Action non autorisée 10 Mauvais paramètres 2 Mauvaise signature 11 Format de date incorrect 3 Aucune brand localisée 12 3D Secure désactivé 4 Erreur lors de la détermination de la plage de la 13 Identifiant non trouvé carte 5 Aucun contrat adéquat trouvé 14 PAN non trouvé 6 Spécification du contrat ambigüe, plusieurs sont 98 Erreur de traitement sur l ACS disponibles 7 Marchand non enrôlé 99 Erreur inconnue 8 Signature de l ACS invalide Description des webservices v4 6/56

7 Précisions sur les codes d erreurs TransactionInfo 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éthodes create ou createwiththreeds), 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 Payzen 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. verespareqinfo ErrorCode 9 : Ce code erreur correspond à une erreur technique qui peut avoir plusieurs causes. La plus fréquente étant l envoi d un mauvais numéro de contrat commerçant (createcardinfo.contractnumber) dans la requête. Description des webservices v4 7/56

8 4. DESCRIPTION DES TYPES 4.1 createpaymentinfo Ce champ décrit les paramètres nécessaires à la création d une transaction ainsi qu à la vérification de l enrôlement de la carte. Nom du champ Type Description Obligatoire paymentgeneralinfo createpaymentgeneralinfo Cf. 4.2 cardinfo createcardinfo Cf. 4.3 subpaymentinfo createsubpaymentinfo Cf. 4.4 customerinfo createcustomerinfo Cf. 4.5 shippinginfo createshippinginfo Cf. 4.6 extrainfo createextrainfo Cf. 4.7 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 : paymentgeneralinfo, cardinfo, subpaymentinfo, customerinfo, shippinginfo, extrainfo Description des webservices v4 8/56

9 4.2 createpaymentgeneralinfo Ce champ décrit les paramètres relatifs à la transaction. Nom du champ Type Description Obligatoire siteid string Identifiant de la boutique Date et heure UTC de la transaction exprimée au format W3C (Ex: T08:16:43+00:00). transmissiondate datetime Représente la date et l heure de la requête. Si la valeur de ce champ est trop éloignée de l heure actuelle, la requête sera rejetée (errorcode 6) Identifiant de la transaction sur 6 chiffres. Cet identifiant doit être transactionid string unique sur une même journée. (de 00:00:00UTC à 23:59:59UTC). Source du paiement: - EC: Commerce Électronique - MOTO : commande par mail ou téléphone - CC : Centre d appel - OTHER : autre canal de vente paymentsource string ATTENTION : Seule la valeur EC permet de créer une transaction avec 3D-S. Les autres valeurs sont ne doivent être utilisées que pour de la vente à distance, pour laquelle le 3D- Secure n est pas applicable. orderid string Référence de la commande. orderinfo string orderinfo2 string Description libre de la commande. orderinfo3 string amount long Montant de la transaction exprimé dans la plus petite unité monétaire (en centimes pour Euro) currency int Code de la devise suivant la norme ISO 4217, (978 pour EURO) Ce champ permet de définir la date de remise de la transaction, exprimée au format W3C (Ex: T08:16:43+00:00 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). presentationdate datetime 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 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 createpaymentgeneralinfo.siteid, createpaymentgeneralinfo.transactionid, createpaymentgeneralinfo.paymentsource, createpaymentgeneralinfo.orderid, createpaymentgeneralinfo.orderinfo, createpaymentgeneralinfo.orderinfo2, createpaymentgeneralinfo.orderinfo3, createpaymentgeneralinfo.amount, createpaymentgeneralinfo.currency, createpaymentgeneralinfo.validationmode Description des webservices v4 9/56

10 4.3 createcardinfo Ce type décrit les détails de la carte de crédit : Nom du champ Type Description Obligatoire cardnumber string Numéro de carte cardnetwork string Réseau de la carte ("AMEX","CB","MASTERCARD", "VISA","MAESTRO", "E-CARTEBLEUE","JCB") expirymonth int Mois d expiration de la carte, entre 1 et 12 expiryyear int Année d expiration de la carte sur 4 digits ex : 2012 cvv string Cryptogramme visuel à 3 chiffres (ou 4 pour Amex : 4DBC) Ce champ est obligatoire lorsque la carte dispose d un code cryptogramme visuel. Si le CVV n est pas transmis, la banque émettrice refusera le paiement. Remarque : Le champ cvv est optionnel dans la méthode createwiththreeds car certaines cartes ne possèdent pas de cvv. cardident string Identifiant du compte acheteur (paiement par identifiant) Ce champ ne doit pas être envoyé à vide (errorcode 17) Ce champ ne doit pas être valorisé si le champ cardnumber l est déjà (errorcode 22) cardbirthday datetime Date de naissance du porteur contractnumber string Numéro de contrat commerçant. Si ce champ est renseigné, veillez à utiliser le bon contrat en fonction du réseau de la carte. Par exemple, le contrat CB ne peut être utilisé pour une transaction AMEX. paymentoptioncode string Réservé à un usage spécifique. Ne pas renseigner createcardinfo.cardnumber, createcardinfo.cardnetwork, createcardinfo.expirymonth, createcardinfo.expiryyear, createcardinfo.cvv, createcardinfo.cardbirthday, createcardinfo.cardident, createcardinfo.contractnumber, createcardinfo.paymentoptioncode Description des webservices v4 10/56

11 4.4 createsubpaymentinfo Ce type est réservé à un usage futur. Il ne doit pas être valorisé : Nom du champ Type Description Obligatoire subpaymenttype int subreference string Ne pas renseigner subpaymentnumber int createsubpaymentinfo.subpaymenttype, createsubpaymentinfo.subreference, createsubpaymentinfo.subpaymentnumber 4.5 createcustomerinfo Ce type décrit les détails concernant le porteur de la carte. Nom du champ Type Description Obligatoire customerid string Référence client customertitle string Civilité customerstatus custstatus Cf. 4.8 customername string Nom du client customerphone string Numéro de téléphone customer string Adresse de courrier électronique customeraddressnumber string Numéro de rue customeraddress string Adresse customerdistrict string Quartier customerzip string Code postal customercity string Ville customercountry string Pays language string Langue du client (norme ISO sur 2 caractères). customerip string Adresse IP du lient customersend boolean Envoi d un de confirmation de paiement à l internaute. 0= Non ; 1=Oui. customercellphone string Téléphone mobile du client extinfo Array extinfo Paramètres génériques exprimés sous la forme nom, valeur. Cf createcustomerinfo.customerid, createcustomerinfo.customertitle, createcustomerinfo.customerstatus, createcustomerinfo.customername, createcustomerinfo.customerphone, createcustomerinfo.customer , createcustomerinfo.customeraddressnumber, createcustomerinfo.customeraddress, createcustomerinfo.customerdistrict createcustomerinfo.customerzip, createcustomerinfo.customercity, createcustomerinfo.customercountry, createcustomerinfo.language, createcustomerinfo.customerip, createcustomerinfo.customersend , createcustomerinfo.customercellphone, createcustomerinfo.extinfo Description des webservices v4 11/56

12 4.6 createshippinginfo Ce type décrit les informations de livraison. Nom du champ Type Description Obligatoire shippingstatus custstatus Cf.4.8 shippingname string Nom shippingphone string Numéro de téléphone shippingstreetnumber string Numéro de la rue shippingstreet string Adresse de livraison shippingstreet2 string Deuxième ligne d adresse de livraison shippingdistrict string Quartier shippingzipcode string Code postal shippingcity string Ville de livraison shippingstate string Etat de livraison shippingcountry string Pays de livraison shippingdeliverycompanyname string Informations sur le transporteur shippingspeed deliveryspeed Mode de livraison (cf.4.9) shippingtype deliverytype Méthode de livraison (cf.4.10) createshippinginfo.shippingcity, createshippinginfo.shippingcountry, createshippinginfo.shippingdeliverycompanyname, createshippinginfo.shippingname, createshippinginfo.shippingphone, createshippinginfo.shippingspeed, createshippinginfo.shippingstate, createshippinginfo.shippingstatus, createshippinginfo.shippingstreetnumber, createshippinginfo.shippingstreet, createshippinginfo.shippingstreet2, createshippinginfo.shippingdistrict, createshippinginfo.shippingtype, createshippinginfo.shippingzipcode 4.7 createextrainfo Nom du champ Type Description Obligatoire ctxmode string Contexte de sollicitation de la plateforme de paiement. ("TEST","PRODUCTION") browseruseragent string Header «User-Agent» du navigateur du client browseraccept string Header «Accept» du navigateur du client createextrainfo.ctxmode, createextrainfo.browseruseragent, createextrainfo.browseraccept Description des webservices v4 12/56

13 4.8 custstatus Ce type décrit le type de client. Les valeurs possibles sont définies ci-dessous : PRIVATE COMPANY Valeur Particulier Entreprise Description 4.9 deliveryspeed Ce type décrit le mode de livraison. Les valeurs possibles sont définies ci-dessous : STANDARD EXPRESS Valeur Livraison Standard Livraison Express Description 4.10 deliverytype Ce type décrit la méthode de livraison. Les valeurs possibles sont définies ci-dessous : Valeur Description RECLAIM_IN_SHOP Retrait de la marchandise en magasin RELAY_POINT Utilisation d'un réseau de points-retrait tiers : (type Kiala, Alveol, etc.) RECLAIM_IN_STATION Retrait dans un aéroport, une gare ou une agence de voyage PACKAGE_DELIVERY_COMPANY Transporteur (La poste, Colissimo, UPS, DHL ) ETICKET Emission d un billet électronique, téléchargements 4.11 extinfo Ce type décrit un champ supplémentaire qui sera persisté dans la transaction et sera retourné dans la réponse Nom du champ Valeur Description key string Nom de la donnée value string Valeur de la donnée extinfo.key, extinfo.value Description des webservices v4 13/56

14 4.12 createwiththreedsresponse Ce type décrit la réponse envoyée lors d un appel à la méthode createwiththreeds. Nom du champ Type Description errorcode int Code d erreur cf. 3 extendederrorcode string Détail de l erreur si le champ errorcode est différent de 0 timestamp long Timestamp permettant la génération de signature unique signature string Signature de la Réponse (cf. ci-dessous) Contient le résultat de la demande d enrôlement ainsi que le message PAReq codé dans le cas où le champ threedsenrolled est valorisé à «Y». verespareqinfo verespareqinfo Cf Ce champ ne sera renvoyé que si la carte est enrôlée. Dans ce cas, le champ transactioninfo ne sera pas envoyé. transactioninfo Descriptif de la transaction. Cf transactioninfo Ne sera pas envoyé si la carte est enrôlée. errorcode, extendederrorcode, timestamp, verespareqinfo, transactioninfo Le code d erreur de la réponse correspondra au code d erreur retourné : soit lors de la création du paiement (transactioninfo) soit le lors de la demande de vérification d enrôlement (verespareqinfo) verespareqinfo Ce type décrit le résultat de la demande d enrôlement ainsi que le message encodé qui sera transmis par le navigateur client à l ACS. Nom du champ Type Description errorcode int Code d erreur cf. 3 errordetail string Détail de l erreur si le champ errorcode est différent de 0 signature string Signature de la Réponse (cf. ci-dessous) timestamp long Timestamp permettant la génération de signature unique threedsacctid String certificat renvoyé par le Directory Server threedsacsurl String Url de l ACS à contacter threedsbrand String Réseau de carte threedsencodedpareq String message PAReq encodé, prêt à envoyer à l ACS threedsenrolled String Statut d enrôlement du porteur : «Y»: Enrôlé threedsrequestid String numéro de requête, à rappeler dans l appel finalizewiththreeds errorcode, errordetail, timestamp, threedsacctid, threedsacsurl, threedsbrand, threedsencodedpareq, threedsenrolled threedsrequestid Description des webservices v4 14/56

15 4.14 transactioninfo Ce type décrit une transaction : Nom du champ Type Description errorcode int Code d erreur (cf.3) extendederrorcode string Détail de l erreur si le champ errorcode est différent de 0 transactionstatus int Code du statut de la transaction (cf. 6) timestamp long Timestamp permettant la génération de signature unique signature string Signature de la transaction transactionstatuslabel String Libellé su statut de la transaction (cf.6) paymentgeneralinfo transactionpaymentgeneralinfo Cf cardinfo transactioncardinfo Cf threedsinfo transactionthreedsinfo Cf authorizationinfo transactionauthorizationinfo Cf markinfo transactionmarkinfo Cf warrantydetailsinfo transactionwarrantydetailsinfo Cf captureinfo transactioncaptureinfo Cf customerinfo transactioncustomerinfo Cf shippinginfo transactionshippinginfo Cf extrainfo transactionextrainfo Cf paymentoptioninfo transactionpaymentoptioninfo Réservé à un usage spécifique boletoinfo transactionboletoextrainfo Réserve à un usage spécifique Le calcul de la signature se fait en prenant les paramètres dans l ordre suivant: transactioninfo.errorcode, transactioninfo.extendederrorcode, transactioninfo.transactionstatus, transactioninfo.timestamp, transactioninfo.paymentgeneralinfo, transactioninfo.cardinfo, transactioninfo.threedsinfo, transactioninfo.authorizationinfo, transactioninfo.markinfo, transactioninfo.warrantydetailsinfo, transactioninfo.captureinfo, transactioninfo.customerinfo, transactioninfo.shippinginfo, transactioninfo.extrainfo, transactioninfo.transactionstatuslabel Description des webservices v4 15/56

16 4.15 transactionpaymentgeneralinfo Ce type décrit les informations générales d une transaction : Nom du champ Type Description siteid string Identifiant de la boutique paymentsource string Source du paiement : - "E_COMMERCE": e-commerce - "MAIL_OR_TELEPHONE" : mail ou téléphone - "CALL_CENTER": centre d appel - "OTHER": autres 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 datetime Date et heure de la transaction transactionid string Identifiant de transaction sequencenumber int Numéro de séquence de la transaction amount string Montant actuel de la transaction en plus petite unité monétaire initialamount string Montant initial (avant modification éventuelle) en plus petite unité monétaire currency int Code de la devise (Code monnaie ISO 4217, Euro : 978) effectiveamount string Montant en contre-valeur en plus petite unité monétaire effectivecurrency int Devise en contre-valeur (Code monnaie ISO 4217, Euro : 978) presentationdate datetime Date de remise demandée type int 0 = DEBIT, 1 = CREDIT multiplepayment int Paiement en plusieurs fois (Non = 0, Oui = 1) effectivecreationdate datetime Date réelle d enregistrement de la transaction transactionpaymentgeneralinfo.siteid, transactionpaymentgeneralinfo.paymentsource, transactionpaymentgeneralinfo.orderid, transactionpaymentgeneralinfo.orderinfo, transactionpaymentgeneralinfo.orderinfo2, transactionpaymentgeneralinfo.orderinfo3, transactionpaymentgeneralinfo.transactionid, transactionpaymentgeneralinfo.sequencenumber, transactionpaymentgeneralinfo.amount, transactionpaymentgeneralinfo.initialamount, transactionpaymentgeneralinfo.currency, transactionpaymentgeneralinfo.effectiveamount, transactionpaymentgeneralinfo.effectivecurrency, transactionpaymentgeneralinfo.type, transactionpaymentgeneralinfo.multiplepayment, Description des webservices v4 16/56

17 4.16 transactioncardinfo Ce type décrit le détail de la carte: Nom du champ Type Description cardnumber string Numéro de carte masqué cardnetwork string Réseau de la carte cardbrand string Brand de la carte cardcountry long Code Pays du pays d émission de la carte (Code numérique ISO ex : France=250) cardproductcode string Code produit de la carte cardbankcode string Code banque de la banque émettrice expirymonth int Mois d expiration entre 1 et 12 expiryyear int Année d expiration sur 4 chiffres contractnumber string Numéro du contrat commerçant utilisé transactioncardinfo.cardnumber, transactioncardinfo.cardnetwork, transactioncardinfo.cardbrand, transactioncardinfo.cardcountry, transactioncardinfo.expirymonth, transactioncardinfo.expiryyear, transactioncardinfo.contractnumber, transactioncardinfo.cardbankcode, transactioncardinfo.cardproductcode Description des webservices v4 17/56

18 4.17 transactionthreedsinfo Ce champ décrit les détails de l authentification 3D-Secure : Nom du champ Type Description threedstransactioncondition string threedsenrolled threedsstatus threedseci threedsxid threedscavvalgorithm threedscavv threedssignvalid threedsbrand Détails threedstransactioncondition: "COND_3D_SUCCESS", "COND_3D_FAILURE", "COND_3D_ERROR", "COND_3D_NOTENROLLED", "COND_3D_ATTEMPT", "COND_SSL" Voir détails ci-dessous Statut enrôlement porteur : "Y": Enrôlé string "N": Non enrôlé "U": Inconnu Statut authentification du porteur: "Y": Authentifié 3DS string "N": Erreur Authentification "U": Authentification impossible "A": Essai d authentification string Indicateur de commerce Electronique string Numéro de transaction 3DS Algorithme de vérification de l authentification du porteur (CAVV): "0": HMAC string "1": CVV "2": CVV_ATN "3": Mastercard SPA string Certificat de l ACS string Signature de l authentification 3DS string Brand de la carte ("VISA" ou "MASTERCARD") 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 Payzen 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. transactionthreedsinfo.threedstransactioncondition, transactionthreedsinfo.threedsenrolled, transactionthreedsinfo.threedsstatus, transactionthreedsinfo.threedseci, transactionthreedsinfo.threedsxid, transactionthreedsinfo.threedscavvalgorithm, transactionthreedsinfo.threedscavv, transactionthreedsinfo.threedssignvalid, transactionthreedsinfo.threedsbrand Description des webservices v4 18/56

19 4.18 transactionauthorizationdsinfo Ce type décrit le détail de la demande d autorisation : Nom du champ Type Description authmode authamount authcurrency authdate authnumber authresult authcvv2_cvc2 string string string string string int string "MARK": Une autorisation d un euro a été réalisée afin de vérifier la validité de la carte. Ce cas se présente lorsque la date de remise dépasse la période de validité d une autorisation (7 jours pour VISA/MasterCard/CB/AMEX en France par exemple). "FULL" : autorisation pour le montant total demandé dans la requête Montant de l autorisation dans la plus petite unité monétaire (en centimes pour Euro) dans le cas où authmode vaut FULL Code de la monnaie utilisée lors de la demande d autorisation (suivant la norme ISO 4217) dans le cas où authmode vaut FULL. Date et heure de la demande d autorisation dans le cas où authmode vaut FULL. Numéro de la demande d autorisation dans le cas où authmode vaut FULL Résultat de la demande d autorisation dans le cas où authmode vaut FULL Information relative au traitement du cryptogramme visuel de l autorisation transactionauthorizationinfo.authmode, transactionauthorizationinfo.authamount, transactionauthorizationinfo.authcurrency, transactionauthorizationinfo.authnumber, transactionauthorizationinfo.authresult, transactionauthorizationinfo.authcvv2_cvc2 Description des webservices v4 19/56

20 Liste des valeurs possibles pour les champs 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 Description des webservices v4 20/56

21 4.19 transactionmarkinfo Ce type décrit le détail de la demande d empreinte : Nom du champ Type Description markamount long Montant utilisé pour vérifier la validité de la carte, dans la plus petite unité monétaire (en centimes pour l euro). Sa valeur est 100. markcurrency int Code de la monnaie utilisée pour vérifier la validité de la carte (suivant la norme ISO 4217). Sa valeur est 100. markdate Date et heure de la demande d autorisation réalisée dans le datetime cas où transactionauthorizationinfo.authmode vaut MARK marknb string Numéro d autorisation de la demande d autorisation dans le cas où transactionauthorizationinfo.authmode vaut MARK markresult int Résultat de la demande d autorisation réalisée l dans le cas où transactionauthorizationinfo.authmode vaut MARK markcvv2_cvc2 string Information relative au traitement du cryptogramme visuel. transactionmarkinfo.markamount, transactionmarkinfo.markcurrency, transactionmarkinfo.marknb, transactionmarkinfo.markresult, transactionmarkinfo.markcvv2_cvc transactionwarrantydetailsnfo Ce type décrit le détail de la garantie du paiement et des contrôles locaux : Nom du champ Type Description paymenterror int Complément d information en cas d erreur technique. warrantlyresult string Garantie de paiement (YES/ NO) localcontrol Array Tableau des résultats des différents contrôles locaux localcontrol litige boolean Litige transactionwarrantydetailsinfo.paymenterror, transactionwarrantydetailsinfo.warrantlyresult, transactionwarrantydetailsinfo.localcontrol, transactionwarrantydetailsinfo.litige Description des webservices v4 21/56

22 4.21 localcontrol Ce type décrit un contrôle local (nom du contrôle et résultat). Nom du champ Type Description name string Nom du contrôle result boolean Résultat du contrôle localcontrol.name, localcontrol.result Les différentes valeurs possibles pour name sont : "CARD" "COUNTRY" "IPADDR" "AMOUNT" "BIN" Valeur Description Carte située dans une liste grise Pays inclus dans la liste grise de la boutique ou absent de la liste blanche Adresse IP située dans une liste grise Encours atteint 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" "COUNTRY_CONSISTENCY" Détection d une carte à autorisation systématique 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 Description des webservices v4 22/56

23 4.22 transactioncaptureinfo Ce type décrit le détail de la remise dans le cas où la transaction est remisée. Nom du champ Type Description capturedate datetime 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 refundcurrency int Devise du montant ayant déjà fait l objet d un remboursement (Code monnaie ISO 4217, Euro : 978) transactioncaptureinfo.capturenumber, transactioncaptureinfo.rapprochementstatut, transactioncaptureinfo.refundamount, transactioncaptureinfo.refundcurrency 4.23 transactioncustomerinfo Ce type décrit les détails concernant le porteur de la carte : Nom du champ Type Description customerid string Référence client customertitle string Civilité customerstatus custstatus Cf.4.8 customername string Nom du client customerphone string Numéro de téléphone customer string Adresse de courrier électronique customeraddressnumber string Numéro de la rue customeraddress string Numéro de rue customerdistrict string Quartier customerzip string Code postal customercity string Ville customercountry string Pays language string Langue du client (norme ISO sur 2 caractères). customerip string Adresse IP du lient customercellphone string Téléphone mobile du client extinfo Array extinfo Cf transactioncustomerinfo.customerid, transactioncustomerinfo.customertitle, transactioncustomerinfo.customerstatus, transactioncustomerinfo.customername, transactioncustomerinfo.customerphone, transactioncustomerinfo.customer , transactioncustomerinfo.customeraddressnumber, transactioncustomerinfo.customeraddress, transactioncustomerinfo.customerdistrict, transactioncustomerinfo.customerzip, transactioncustomerinfo.customercity, transactioncustomerinfo.customercountry, transactioncustomerinfo.language, transactioncustomerinfo.customerip, transactioncustomerinfo.customercellphone, transactioncustomerinfo.extinfo Description des webservices v4 23/56

24 4.24 transactionshippinginfo Ce type décrit les informations de livraison : Nom du champ Type Description shippingcity string Ville de livraison shippingcountry string Pays de livraison shippingdeliverycompanyname string Informations sur le transporteur shippingname string Nom shippingphone string Numéro de téléphone shippingspeed deliveryspeed Mode de livraison (cf.4.9) shippingstate string Etat de livraison shippingstatus custstatus Cf. 4.8 shippingstreetnumber string Numéro de la rue shippingstreet string Adresse de livraison shippingstreet2 string Deuxième ligne d adresse de livraison shippingdistrict string Quartier shippingtype deliverytype Méthode de livraison (cf.4.10) shippingzipcode string Code postal transactionshippinginfo.shippingcity, transactionshippinginfo.shippingcountry, transactionshippinginfo.shippingdeliverycompanyname, transactionshippinginfo.shippingname, transactionshippinginfo.shippingphone, transactionshippinginfo.shippingspeed, transactionshippinginfo.shippingstate, transactionshippinginfo.shippingstatus, transactionshippinginfo.shippingstreetnumber, transactionshippinginfo.shippingstreet, transactionshippinginfo.shippingstreet2, transactionshippinginfo.shippingdistrict, transactionshippinginfo.shippingtype, transactionshippinginfo.shippingzipcode 4.25 transactionextrainfo Ce type décrit les informations de livraison : Nom du champ Type Description ctxmode string Contexte de sollicitation de la plateforme de paiement. ("TEST","PRODUCTION") transactionextrainfo.ctxmode Description des webservices v4 24/56

25 4.26 paymentcreationinfo Ce champ décrit les paramètres nécessaires à la création de la transaction ainsi qu à la vérification de l enrôlement de la carte. Nom du champ Type Description Obligatoire paymentgeneralinfo createpaymentgeneralinfo Cf. 4.2 cardinfo createcardinfo Cf. 4.3 threedsresult threedsresult Cf subpaymentinfo createsubpaymentinfo Cf. 4.4 customerinfo createcustomerinfo Cf. 4.5 shippinginfo createshippinginfo Cf. 4.6 extrainfo createextrainfo Cf. 4.7 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 : paymentgeneralinfo, cardinfo, threedsresult, subpaymentinfo, customerinfo, shippinginfo, extrainfo 4.27 threedsresult Ce champ décrit le résultat d une authentification 3D-Secure réalisée par le commerçant. Nom du champ Type Description Obligatoire threedsbrand string Brand de la carte ("VISA" ou "MASTERCARD") Statut enrôlement porteur : "Y": Enrôlé threedsenrolled string "N": Non enrôlé "U": Inconnu Statut authentification du porteur: "Y": Authentifié 3DS threedsstatus string "N": Erreur Authentification "U": Authentification impossible "A": Essai d authentification threedseci string Indicateur de commerce Electronique threedsxid string Numéro de transaction 3DS threedscavv string Certificat de l ACS Algorithme de vérification de l authentification du porteur (CAVV) : "0": HMAC threedscavvalgorithm string "1": CVV "2": CVV_ATN "3": Mastercard SPA Remarque : threedsresult.threedsbrand, threedsresult.threedsenrolled, threedsresult.threedsstatus, threedsresult.threedseci, threedsresult.threedsxid, threedsresult.threedscavv, threedsresult.threedscavvalgorithm 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. Description des webservices v4 25/56

26 Cas des cartes non enrôlées (threedsenrolled = "N"): Le marchand devra obligatoirement fournir les champs suivants : threedsbrand, threedsenrolled. Les autres champs (threedsstatus, threedseci, threedsxid, threedscavv, et threedscavvalgorithm) ne devront pas être envoyés. Cas des cartes enrôlées (threedsenrolled = "Y"): Le marchand devra obligatoirement fournir tous les champs: threedsbrand, threedsenrolled, threedsstatus, threedsxid. Dans le cas où l internaute s est correctement authentifié (threedsstatus = "Y" ou "A") Les champs threedseci, threedscavv et threedscavvalgorithm deviennent obligatoires. Dans le cas où l internaute ne s est pas authentifié (threedsstatus = "N" ou "U"), les champs threedseci, threedscavv et threedscavvalgorithm ne doivent pas être envoyés Cas des cartes dont le statut d enrôlement est inconnu (threedsenrolled = "U"): Le marchand devra obligatoirement fournir les champs suivants : threedsbrand, threedsenrolled. Les autres champs (threedsstatus, threedseci, threedsxid, threedscavv, et threedscavvalgorithm) ne devront pas être envoyés standardresponse Ce type permet de décrire la réponse des méthodes cancel, force et validate. 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 (cf. 6) timestamp long Timestamp permettant la génération de signature unique signature String Signature de la transaction (cf.5) 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 Description des webservices v4 26/56

27 5. 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 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. Afin de simplifier le calcul de signature, les champs de type datetime ne sont pas pris en compte. 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 extendederrorcode. Description des webservices v4 27/56

28 6. STATUT D UNE TRANSACTION Les différents statuts de la transaction (transactionstatus) peuvent être : Valeur transactionstatus transactionstatuslabel "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "11" "12" Initial (en traitement) Réservé à un usage spécifique 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 "INITIAL" "AUTHORISED_TO_VALIDATE" " REFUSED " "WAITING_AUTHORISATION_TO_VALIDATE" "AUTHORISED" "WAITING_AUTHORISATION" "CAPTURED" "EXPIRED" " REFUSED " "CANCELLED" "AUTHORISED" "WAITING_AUTHORISATION" "13" En échec Réservé à un usage spécifique "CAPTURE_FAILED" Description des webservices v4 28/56

29 7. DESCRIPTION DES METHODES 7.1 Maintien de la session HTTP entre chaque requête 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 associée à un même paiement soit réalisée avec la même session HTTP afin d assurer la continuité du processus. Pour cela, à chaque requête createwiththreeds, 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 finalizewiththreeds suivantes. En JAVA Une fois le client WebService créé (port), utiliser la méthode signalée en gras dans le code suivant : Service service = Service.create(wsdlURL, qname); ThreeDSecure port = service.getport(threedsecure.class); ((BindingProvider) port).getrequestcontext().put(bindingprovider.session_maintain_property, true); Cela permet au serveur de ne pas ignorer les infos de session associées à la requête http et de maintenir un cookie avec l ID de session. En PHP Après l appel à la fonction createwiththreeds, la session est créée côté serveur et renvoyée dans les headers HTTP de la réponse. Pour les méthodes suivantes de la même transaction, il faut récupérer ce header et le transmettre en tant que cookie dans la requête HTTP. Voici un exemple de code pour récupérer l id de session et le transmettre : /* La méthode ci-dessous permet de récupérer l entête HTTP de la réponse */ $header = $client-> getlastresponseheaders(); /* 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)){ return "Aucun ID de Session Renvoyé." ; //Cas d erreur technique } $cookie = $matches[1]) ; /*La méthode ci-dessous permet de spécifier un cookie qui sera envoyé dans chaque entête http */ $client-> setcookie ("JSESSIONID", $cookie); Il est donc nécessaire de stocker cet id de session car lors du retour de l ACS, dé corrélé des requêtes createwiththreeds, il faut également l envoyer. Description des webservices v4 29/56

30 7.2 Création d un paiement avec authentification 3D-Secure 7.2.1: Cinématique du paiement L acheteur valide sa commande sur le site marchand. Il saisit ses données cartes sur le site marchand pour procéder au paiement. Le site marchand contacte Payzen (méthode createwiththreeds) Payzen via son MPI interroge les directory VISA ou Mastercard. Si la carte n est pas enrôlée, alors Payzen procède à la demande d autorisation et retourne le résultat du paiement au site marchand (transactioninfo) Si la carte est enrôlée, Payzen renvoie au marchand les informations suivantes (verespareqinfo): - L URL du site internet de la banque du porteur (ACS) vers laquelle le marchand devra rediriger l acheteur. - Le message PAReq encodé - L identifiant de la requête (threedsrequestid) Le site marchand sauvegarde dans le champ MD l identifiant de session contenu dans l entête de la réponse (JSESSIONID) ainsi que l identifiant de la requête (threedsrequestid) contenu dans la réponse verespareqinfo Le site marchand envoie au navigateur de l acheteur une requête http POST avec les informations contenues dans le verespareqinfo ainsi que le champ MD. L acheteur est redirigé vers sur le site de la banque émettrice (ACS) et s authentifie A la fin de l authentification, l acheteur est redirigé vers le site marchand et son navigateur effectue une requête POST à destination du site marchand contenant les champs MD et PARes Le site marchand récupère ces deux champs et les transmet à Payzen pour vérifier l authentification et créer la transaction (finalizewiththreeds) Le MPI de Payzen vérifie les données contenues dans le PARes : l acheteur ne s est pas authentifié, le paiement sera refusé. l acheteur s est authentifié, Payzen procède à la demande d autorisation. Payzen renvoi le résultat du paiement au site marchand (transactioninfo) Description des webservices v4 30/56

31 7.2.2: Détails de la méthode createwiththreeds La méthode createwiththreeds prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire createinfo createpaymentinfo Cf. 4.1 wssignature String Signature (cf. ci-dessous) createpaymentinfo.paymentgeneralinfo, createpaymentinfo.cardinfo, createpaymentinfo.subpaymentinfo, createpaymentinfo.customerinfo, createpaymentinfo.shippinginfo, createpaymentinfo.extrainfo Le champ subpaymentinfo ne doit pas être renseigné. Sa valeur lors du calcul de signature doit donc être vide. Cette fonction retourne une réponse du type createwiththreedsresponse cf Description des webservices v4 31/56

32 Exemple de fichier XML généré lors de l appel de la méthode createwiththreeds : <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env= xmlns:ns1=" <SOAP-ENV:Body> <ns1:createwiththreeds> <createinfo> <paymentgeneralinfo> <siteid> </siteid> <transmissiondate> t08:43:28+00:00</transmissiondate> <transactionid>084328</transactionid> <paymentsource>ec</paymentsource> <orderid>cmd-test</orderid> <amount>3000</amount> <currency>978</currency> </paymentgeneralinfo> <cardinfo> <cardnumber> </cardnumber> <cardnetwork>cb</cardnetwork> <expirymonth>04</expirymonth> <expiryyear>16</expiryyear> <cvv>123</cvv> </cardinfo> <customerinfo> <customername>test Payzen</customerName> <customeraddress>allée du test</customeraddress> <customerzip>31450</customerzip> <customercity>labège</customercity> <customercountry>france</customercountry> <language>fr</language> <extinfo> <key>article</key> <value>iphone12</value> </extinfo> <extinfo> <key>article1</key> <value>iphone12gs</value> </extinfo> </customerinfo> <shippinginfo> <shippingdeliverycompanyname>ups</shippingdeliverycompanyname> <shippingspeed>standard</shippingspeed> <shippingtype>package_delivery_company</shippingtype> </shippinginfo> <extrainfo> <ctxmode>test</ctxmode> </extrainfo> </createinfo> <wssignature>98d5a a63fc0068a867b2ef </wssignature> </ns1:createwiththreeds> </SOAP-ENV:Body></SOAP-ENV:Envelope> Description des webservices v4 32/56

33 Exemple de fichier XML généré en réponse à l appel createwiththreeds (carte enrôlée) : <env:envelope xmlns:env=' <env:header></env:header> <env:body> <ns1:createwiththreedsresponse xmlns:ns1=' <return> <errorcode>0</errorcode> <timestamp> </timestamp> <signature> d5a19152a297bace106f3ed241994ef6f</signature> <verespareqinfo> <errorcode>0</errorcode> <signature>4d0073dc0e4ec3ffba03a1971f42761d98a34c9c</signature> <timestamp> </timestamp> <threedsacctid>fa1e2b46604f412eb01bbd27cb28</threedsacctid> <threedsacsurl> </threedsacsurl> <threedsbrand>visa</threedsbrand> <threedsencodedpareq>ejxvuttu2zam/rxd744a</threedsencodedpareq> <threedsenrolled>y</threedsenrolled> <threedsrequestid>_769d0897-1d6b-464e-8438-dba2b39ac423 </threedsrequestid> </verespareqinfo> </return> </ns1:createwiththreedsresponse> </env:body> </env:envelope> Description des webservices v4 33/56

34 7.2.3: Redirection vers l ACS Après avoir récupéré le contenu du verespareqinfo, il faut rediriger le navigateur du client vers son ACS, en renvoyant une page HTML avec un formulaire POST auto soumis. L'url de l'acs est utilisée comme action du POST, sa valeur est celle retournée dans le champ verespareqinfo.threedsacsurl Il faut également disposer d une url de retour sur le serveur pour récupérer la réponse de l'acs (elle aussi par POST). Ce formulaire doit obligatoirement contenir les champs suivants :: Nom du champ Type Description Obligatoire PaReq String Message codé, retourné par l appel de la méthode sendvereqandbuildpareqtx TermUrl String URL de retour dans laquelle sera analysé le retour de l authentification 3-D Secure Merchant DATA. Il s agit de données qui seront MD String restituées lors de la réponse de l ACS. Par commodité il est conseillé de valoriser ce champ avec l id de session et le requestid afin de reprendre facilement le traitement, par exemple sous la forme suivante : «id_de_session+requestid» Note concernant le mode TEST : Afin de conserver la continuité des transactions en mode test, il sera nécessaire de transmettre l identifiant de la session lors de la redirection vers l ACS. Ceci devra se faire en concaténant : L url de l ACS obtenue dans la réponse verespareqinfo L identifiant de session renvoyé dans l entête http, séparés par «;jsessionid=» La syntaxe à respecter est : ${URL};jsessionid=${session} Exemple : <form name="form" method="post" action=" 3" >... </form> EN MODE PRODUCTION VOUS NE DEVEZ EN AUCUN CAS TRANSMETTRE UN IDENTIFIANT DE SESSION A L ACS Description des webservices v4 34/56

35 Exemple de page de redirection <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xml:lang="fr" lang="fr"> <head> <meta http-equiv="content-type" content="text/html;charset=utf-8"/> <title>---</title> <script type="text/javascript"> <!-- function submitform(){ document.redirectform.submit(); } --> </script> </head> <body onload="settimeout(\'submitform()'.'\',500);"> <span class="message">redirection ACS</span> <br/> <br/> <br/> <form name="redirectform" action="acsurl" method="post"> <input type="hidden" name="pareq" value=" threedsacsurl "/> <input type="hidden" name="termurl" value="url_de_retour"/> <input type="hidden" name="md" value=" threedsrequestid " /> <noscript><input type="submit" name="go" value="click to continue"/></noscript> </form> </body> </html> Description des webservices v4 35/56

36 7.2.4: Récupération de la réponse de l ACS Il est nécessaire de mettre en place une URL de retour de l ACS pour que celui-ci puisse renvoyer les données du PARes au site marchand. Les paramètres renvoyés par l ACS sont les suivants : PaRes : contient le message PARes (Payer Authentication Response) MD : contient le Merchant Data envoyé lors de l appel à l ACS Il convient alors d extraire du champ MD les valeurs de l id de session et du threedsrequestid pour ensuite les utiliser lors de l appel à la méthode finalizewiththreeds. Exemple de page de retour : Dans cet exemple, le champ MD a été composé de l identifiant de la session et de l identifiant de la requête, séparés par le caractère «+» : <?php session_start();?> <html> <head></head> <body> <?php $PaRes = $_POST['PaRes']; List($JSESSIONID, $requestid) = explode («+», $_POST['MD']) ; //Initialisation du client SOAP $client = new soapclient($wsdl,array('trace' =>1)); //Définition du cookie qui sera envoyé avec la requête SOAP $client-> setcookie('jsessionid', $JSESSIONID); Appel de la méthode finalizewiththreeds </body> </html> Description des webservices v4 36/56

37 7.2.5: Analyse de l authentification 3DS et finalisation du paiement (finalyzewiththreeds) Cette fonction permet de soumettre à la plateforme de paiement le message PARes reçu après l authentification 3D-S. Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire threedsrequestid String numéro de requête obtenu dans la réponse createwiththreedsresponse. pares String Message PaRes encodé, reçu de l ACS wssignature String Signature (cf. ci-dessous) threedsrequestid, pares Cette fonction retourne une réponse du type transactioninfo cf Le champ transactioninfo.transactionthreedsinfo contient le résultat de la demande d authentification 3D- Secure. Remarque : Le message PARes peut comporter des caractères de retour à la ligne ( CR, LF ou \r, \n ). Ces caractères sont remplacés par un simple LF par certains framework au moment de l appel au WS. C est le cas notamment en ASP.NET. Afin de ne pas rencontrer des problèmes de calcul de signature, il est conseillé de supprimer les retours à la ligne avant le calcul de signature. Cette suppression n altère pas l intégrité du message PARes. Exemple de fichier XML généré lors de l appel finalizewiththreeds : <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:ns1=" <SOAP-ENV:Body> <ns1:finalizewiththreeds> <requestid>_e23491ca-4d20-4b70-8bea-4b658c071784</requestid> <pares>ejznwdmso0iyfecrymoe1vusyhfjyhw==</pares> <wssignature>6974b7cc7e3495e53e5e0ff6d83a3e </wssignature> </ns1:finalizewiththreeds> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Description des webservices v4 37/56

38 7.3 Modification d une transaction (modify) Cette fonction permet : de modifier le montant d une transaction (à la baisse) de modifier la date de remise souhaitée de valider la transaction Les transactions pouvant faire l objet d une modification possède l un des statuts suivants : A valider A valider et autoriser En attente d auto En attente de remise Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire siteid String Identifiant de la boutique Date et heure de création de la transaction à transmissiondate Date modifier, exprimée au format W3C (Ex: T08:16:43+00:00). transactionid String Identifiant de la transaction à modifier Numéro de séquence de la transaction à modifier. sequencenumber Int 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 currency Int Devise (Code monnaie ISO 4217, Euro : 978) presentationdate Date Date remise demandée, exprimée au format W3C (Ex: T08:16:43+00:00). validate bool Validation de la transaction : 0 -> non ; 1 -> oui comment String Commentaire «libre» wssignature String Signature (cf. 5) Cette fonction retourne une réponse du type transactioninfo cf. Erreur! Source du renvoi introuvable.. siteid, transactionid, sequencenumber, ctxmode, amount, currency, validate, comment Remarque : Le champ amount ne doit pas être envoyé à vide ou à 0. Si vous ne souhaitez pas modifier le montant de la transaction, vous devez valoriser le champ amount avec la valeur initiale. Si aucune information n est modifiée, la requête sera rejetée avec un code erreur 26. Description des webservices v4 38/56

39 Exemple de fichier XML généré lors de l appel modify : <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:ns1=" <SOAP-ENV:Body> <ns1:modify> <siteid> </siteid> <transmissiondate> t08:09:22+00:00</transmissiondate> <transactionid>965805</transactionid> <sequencenumber>1</sequencenumber> <ctxmode>test</ctxmode> <amount>15800</amount> <currency>978</currency> <capturedate> t08:09:22+00:00</capturedate> <validationmode>true</validationmode> <comment></comment> <wssignature>532bfc85fac7b4af69323e b c62</wssignature> </ns1:modify> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Calcul de signature associé : TEST certificat Exemple de fichier XML généré en réponse à l appel modify: <env:envelope xmlns:env=' <env:header></env:header> <env:body> <ns1:modifyresponse xmlns:ns1=' <return> <errorcode>0</errorcode> <transactionstatus>4</transactionstatus> <timestamp> </timestamp> <signature>fab6756f305cd7f78863c569492f2251ba69186a</signature> <transactionstatuslabel>authorised</transactionstatuslabel> <paymentgeneralinfo> <siteid> </siteid> <paymentsource>other</paymentsource> <transmissiondate> t10:08:43+02:00</transmissiondate> <transactionid>965805</transactionid> <sequencenumber>1</sequencenumber> <amount>15800</amount> <initialamount>15800</initialamount> <currency>978</currency> <presentationdate> t10:09:22+02:00</presentationdate> <type>0</type> <multiplepayment>0</multiplepayment> <effectivecreationdate> t10:08:43+02:00</effectivecreationdate> </paymentgeneralinfo> <cardinfo> <cardnumber>497010xxxxxx0000</cardnumber> Description des webservices v4 39/56

40 <cardnetwork>cb</cardnetwork> <cardbrand>cb</cardbrand> <cardcountry>250</cardcountry> <expirymonth>5</expirymonth> <expiryyear>2014</expiryyear> <contractnumber> </contractnumber> </cardinfo> <threedsinfo> <threedstransactioncondition>cond_ssl</threedstransactioncondition> </threedsinfo> <authorizationinfo> <authmode>full</authmode> <authamount>15800</authamount> <authcurrency>978</authcurrency> <authdate> t10:08:43+02:00</authdate> <authnumber>315637</authnumber> <authresult>0</authresult> <authcvv2_cvc2></authcvv2_cvc2> </authorizationinfo> <markinfo/> <warrantydetailsinfo> <warrantyresult>no</warrantyresult> <localcontrol> <name>card</name> <result>false</result> </localcontrol> </warrantydetailsinfo> <captureinfo> <capturenumber>0</capturenumber> <rapprochementstatut>0</rapprochementstatut> <refundamount>0</refundamount> <refundcurrency>978</refundcurrency> </captureinfo> <customerinfo> <language>fr_fr</language> <customerip> </customerip> </customerinfo> <shippinginfo/> <extrainfo> <ctxmode>test</ctxmode> </extrainfo> </return> </ns1:modifyresponse> </env:body> </env:envelope> Calcul de signature de la réponse: OTHER XXXXXX00 00+CB+CB COND_SSL FULL NO+ CARD fr_FR TEST+AUTHORISED +certificat Description des webservices v4 40/56

41 7.4 Création d un paiement avec 3D-Secure intégrateur ou sans 3D-Secure (create) Cette fonction permet de créer: un paiement unique sans 3D-Secure un paiement unique avec 3D-Secure réalisé par le marchand un paiement par identifiant sans 3D-Secure un paiement par identifiant avec 3D-Secure réalisé par le marchand Cette fonction prend en entrée les paramètres suivants : Nom du champ Type Description Obligatoire createinfo paymentcreationinfo Cf wssignature String Signature (cf. 5) Cette fonction retourne une réponse du type transactioninfo cf. Erreur! Source du renvoi introuvable.. paymentcreationinfo.paymentgeneralinfo, paymentcreationinfo.cardinfo, paymentcreationinfo.threedsresult, paymentcreationinfo.subpaymentinfo, paymentcreationinfo.customerinfo, paymentcreationinfo.shippinginfo, paymentcreationinfo.extrainfo Remarques Pour créer des paiements avec 3D-Secure, le champ paymentgeneralinfo.paymentsource doit être obligatoirement valorisé à EC (E-Commerce). Le 3D-S n a de sens qu en mode e-commerce. Dans le cas d un paiement par identifiant avec 3D-S réalisé par le marchand, l envoi du champ cardinfo.cvv est obligatoire. Les champs cardinfo.cardident et cardinfo.cardnumber sont exclusifs et ne doivent pas être renseignés dans une même requête. Le champ cardinfo.cardident ne doit pas être valorisé à vide. Description des webservices v4 41/56