Définition des Webservices V4

Transcription

Définition des Webservices V4
Payzen 1.27.8
Version 1.4
Payzen –
Description des webservices v4
1/56
Historique du document
Version
Auteur
Date
Commentaires
1.4
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 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
1.3
Lyra-Network
01/08/2013
Ajout des méthodes cancel, force, refund, duplicate, getInfo et
validate.
1.2
Lyra-Network
10/07/2013
Ajout de la méthode create
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.
Payzen –
2/56
1. Présentation .............................................................................................................................. 4
2. Notions de timeout ................................................................................................................... 4
3. Description des codes d’erreurs .............................................................................................. 6
4. Description des types ............................................................................................................... 8
4.1 createPaymentInfo .................................................................................................................................... 8
4.2 createPaymentGeneralInfo ..................................................................................................................... 9
4.3 createCardInfo ......................................................................................................................................... 10
4.4 createSubPaymentInfo ........................................................................................................................... 11
4.5 createCustomerInfo ................................................................................................................................ 11
4.6 createShippingInfo .................................................................................................................................. 12
4.7 createExtraInfo ......................................................................................................................................... 12
4.8 custStatus ................................................................................................................................................... 13
4.9 deliverySpeed ........................................................................................................................................... 13
4.10 deliveryType ............................................................................................................................................ 13
4.11 extInfo ....................................................................................................................................................... 13
4.12 createWithThreeDSResponse ............................................................................................................... 14
4.13 veResPAReqInfo ..................................................................................................................................... 14
4.14 transactionInfo ........................................................................................................................................ 15
4.15 transactionPaymentGeneralInfo ........................................................................................................ 16
4.16 transactionCardInfo .............................................................................................................................. 17
4.17 transactionThreeDSInfo ......................................................................................................................... 18
4.18 transactionAuthorizationDSInfo ........................................................................................................... 19
4.19 transactionMarkInfo ............................................................................................................................... 21
4.20 transactionWarrantyDetailsnfo ............................................................................................................ 21
4.21 localControl ............................................................................................................................................. 22
4.22 transactionCaptureInfo ........................................................................................................................ 23
4.23 transactionCustomerInfo ...................................................................................................................... 23
4.24 transactionShippingInfo ........................................................................................................................ 24
4.25 transactionExtraInfo ............................................................................................................................... 24
4.26 paymentCreationInfo............................................................................................................................ 25
4.27 threeDsResult ........................................................................................................................................... 25
4.28 standardResponse ................................................................................................................................. 26
5. Signature ................................................................................................................................. 27
6. Statut d’une transaction ......................................................................................................... 28
7. Description des méthodes ..................................................................................................... 29
7.1 Maintien de la session HTTP entre chaque requête .......................................................................... 29
7.2 Création d’un paiement avec authentification 3D-Secure ............................................................ 30
7.2.1: Cinématique du paiement ................................................................................................................ 30
7.2.2: Détails de la méthode createWithThreeDS .................................................................................... 31
7.2.3: Redirection vers l’ACS ......................................................................................................................... 34
7.2.4: Récupération de la réponse de l’ACS ............................................................................................. 36
7.2.5: Analyse de l’authentification 3DS et finalisation du paiement (finalyzeWithThreeDS) .......... 37
7.3 Modification d’une transaction (modify) ............................................................................................ 38
7.4 Création d’un paiement avec 3D-Secure intégrateur ou sans 3D-Secure (create) .................. 41
7.5 Annulation d’une transaction (cancel) ............................................................................................... 45
7.6 Forçage d’une transaction (force)....................................................................................................... 46
7.7 Remboursement d’une transaction (refund) ..................................................................................... 47
7.8 Duplication d’une transaction (duplicate) ......................................................................................... 48
7.9 Recherche des détails d’une transaction (getInfo) .......................................................................... 49
7.10 Validation d’une transaction (validate) ............................................................................................ 50
8. Annexes................................................................................................................................... 51
8.1 Cartes de test ............................................................................................................................................ 51
8.2 Exemple d’implémentation en PHP : calcul de signature (méthode create) ............................. 52
8.3 Exemples de cinématique de paiement avec gestion des cas d’échec ................................... 55
Payzen –
3/56
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
https://secure.payzen.eu/vads-ws/v4.3?wsdl
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.
_____________________
__________________________________________________
Payzen –
4/56
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.
Payzen –
5/56
3. DESCRIPTION DES CODES D’ERREURS
TransactionInfo :
Error
Code
Type
Error
Code
0
1
2
3
4
5
6
10
11
12
13
14
15
16
17
18
19
20
21
22
27
40
50
51
52
53
54
55
56
57
58
59
60
61
Action réalisée avec succès
Action non autorisée.
Transaction non trouvée
Transaction pas dans le bon état
Transaction existe déjà
Mauvaise signature
Mauvaise date
Mauvais montant
Mauvaise devise
Type de carte inconnu
Paramètre ‘date d’expiration’ invalide
Paramètre ‘cvv’ invalide
Contrat inconnu
Paramètre ‘Numéro de carte’ invalide
Identifiant non trouvé
Identifiant non valide (Résilié, …)
Subscription non trouvée
Subscription non valide
Identifiant déjà existant
Création d’identifiant refusé
Montant non autorisé
Plage non trouvée
Paramètre ‘siteId’ invalide
Paramètre ‘transmissionDate’ invalide
Paramètre ‘transactionId’ invalide
Paramètre ‘ctxMode’ invalide
Paramètre ‘comment’ invalide
Paramètre ‘AutoNb’ invalide
Paramètre ‘AutoDate’ invalide
Paramètre ‘captureDate’ invalide
Paramètre ‘newTransactionId’ invalide
Paramètre ‘validationMode’ invalide
Paramètre ‘orderId’ invalide
Paramètre ‘orderInfo1’ invalide
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
90
91
92
93
94
95
96
98
99
Type
Paramètre ‘paymentSource’ invalide
Paramètre ‘cardNumber’ invalide
Paramètre ‘contractNumber’ invalide
Paramètre ‘customerId’ invalide
Paramètre ‘customerTitle’ invalide
Paramètre ‘customerName’ invalide
Paramètre ‘customerPhone’ invalide
Paramètre ‘customerMail’ invalide
Paramètre ‘customerAddress’ invalide
Paramètre ‘customerZipCode’ invalide
Paramètre ‘customerCity’ invalide
Paramètre ‘customerCountry’ invalide
Paramètre ‘customerLanguage’ invalide
Paramètre ‘customerIp’ invalide
Paramètre ‘customerSendMail’ invalide
Paramètre ‘customerMobilePhone’ invalide
Paramètre ‘subPaiementType’ invalide
Paramètre ‘subReference’ invalide
Paramètre ‘initialAmount’ invalide
Paramètre ‘occInitialAMount’ invalide
Paramètre ‘effectDate’ invalide
Paramètre ‘state’ invalide
Paramètre ‘enrolled’ invalide
Paramètre ‘authStatus’ invalide
Paramètre ‘eci’ invalide
Paramètre ‘xid’ invalide
Paramètre ‘cavv’ invalide
Paramètre ‘cavvAlgo’ invalide
Paramètre ‘brand’ invalide
Paramètre ‘requestId’ invalide
Autre erreur
veResPAReqInfo :
Error
Code
0
1
2
3
4
5
6
7
8
Description
Action réalisée avec succès
Action non autorisée
Mauvaise signature
Aucune brand localisée
Erreur lors de la détermination de la plage de la
carte
Aucun contrat adéquat trouvé
Spécification du contrat ambigüe, plusieurs sont
disponibles
Marchand non enrôlé
Signature de l’ACS invalide
Error
Code
Description
9
10
11
12
13
Erreur technique
Mauvais paramètres
Format de date incorrect
3D Secure désactivé
Identifiant non trouvé
14
98
PAN non trouvé
Erreur de traitement sur l’ACS
99
Erreur inconnue
Payzen –
6/56
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.
Payzen –
7/56
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
paymentGeneralInfo
cardInfo
subPaymentInfo
customerInfo
shippingInfo
extraInfo
Type
createPaymentGeneralInfo
createCardInfo
createSubPaymentInfo
createCustomerInfo
createShippingInfo
createExtraInfo
Description
Cf. 4.2
Cf. 4.3
Cf. 4.4
Cf. 4.5
Cf. 4.6
Cf. 4.7
Obligatoire
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
Payzen –
8/56
4.2 createPaymentGeneralInfo
Ce champ décrit les paramètres relatifs à la transaction.
Nom du champ
Type
siteId
string
transmissionDate
transactionId
dateTime
string
Description
Obligatoire
Identifiant de la boutique
Date et heure UTC de la transaction exprimée au format W3C (Ex :
2012-06-08T08:16:43+00:00).
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
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
orderInfo
orderInfo2
orderInfo3
string
string
string
string
amount
long
currency
int
presentationDate
dateTime
Référence de la commande.
Description libre de la commande.
Montant de la transaction exprimé dans la plus petite unité monétaire
(en centimes pour Euro)
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 : 2012-06-08T08: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).
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
Le calcul de la signature se fait en prenant les paramètres dans l’ordre suivant :
createPaymentGeneralInfo.siteId, createPaymentGeneralInfo.transactionId,
createPaymentGeneralInfo.paymentSource, createPaymentGeneralInfo.orderId,
createPaymentGeneralInfo.orderInfo, createPaymentGeneralInfo.orderInfo2,
createPaymentGeneralInfo.orderInfo3, createPaymentGeneralInfo.amount,
createPaymentGeneralInfo.currency, createPaymentGeneralInfo.validationMode
Payzen –
9/56
4.3 createCardInfo
Ce type décrit les détails de la carte de crédit :
Type
Description
cardNumber
Nom du champ
string
cardNetwork
string
expiryMonth
int
expiryYear
int
Numéro de carte
Réseau de la carte ("AMEX", "CB", "MASTERCARD",
"VISA", "MAESTRO", "E-CARTEBLEUE", "JCB")
Mois d’expiration de la carte, entre 1 et 12
Année d’expiration de la carte sur 4 digits ex :
2012
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.
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)
Date de naissance du porteur
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.
Réservé à un usage spécifique.
Ne pas renseigner
cvv
string
cardIdent
string
cardBirthDay
dateTime
contractNumber
string
paymentOptionCode
string
Obligatoire
createCardInfo.cardNumber, createCardInfo.cardNetwork, createCardInfo.expiryMonth,
createCardInfo.expiryYear, createCardInfo.cvv, createCardInfo.cardBirthDay,
createCardInfo.cardIdent, createCardInfo.contractNumber,
createCardInfo.paymentOptionCode
Payzen –
10/56
4.4 createSubPaymentInfo
Ce type est réservé à un usage futur. Il ne doit pas être valorisé :
Nom du champ
subPaymentType
subReference
subPaymentNumber
Type
Description
int
string
int
Obligatoire
Ne pas renseigner
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
customerId
customerTitle
customerStatus
customerName
customerPhone
customerEmail
customerAddressNumber
customerAddress
customerDistrict
customerZip
customerCity
customerCountry
language
customerIP
Type
Description
string
string
custStatus
string
string
string
string
string
string
string
string
string
string
string
customerSendEmail
boolean
customerCellPhone
string
Array
extInfo
extInfo
Obligatoire
Référence client
Civilité
Cf. 4.8
Nom du client
Numéro de téléphone
Adresse de courrier électronique
Numéro de rue
Adresse
Quartier
Code postal
Ville
Pays
Langue du client (norme ISO 639-1 sur 2
caractères).
Adresse IP du lient
Envoi d’un email de confirmation de paiement à
l’internaute.
0= Non ; 1=Oui.
Téléphone mobile du client
Paramètres génériques exprimés sous la forme
nom, valeur. Cf. 4.11
createCustomerInfo.customerId, createCustomerInfo.customerTitle,
createCustomerInfo.customerStatus, createCustomerInfo.customerName,
createCustomerInfo.customerPhone, createCustomerInfo.customerEmail,
createCustomerInfo.customerAddressNumber, createCustomerInfo.customerAddress,
createCustomerInfo.customerDistrict createCustomerInfo.customerZip,
createCustomerInfo.customerCity, createCustomerInfo.customerCountry,
createCustomerInfo.language, createCustomerInfo.customerIP,
createCustomerInfo.customerSendEmail, createCustomerInfo.customerCellPhone,
createCustomerInfo.extInfo
Payzen –
11/56
4.6 createShippingInfo
Ce type décrit les informations de livraison.
Nom du champ
Type
shippingStatus
shippingName
shippingPhone
shippingStreetNumber
shippingStreet
shippingStreet2
shippingDistrict
shippingZipCode
shippingCity
shippingState
shippingCountry
shippingDeliveryCompanyName
shippingSpeed
shippingType
custStatus
string
string
string
string
string
string
string
string
string
string
string
deliverySpeed
deliveryType
Description
Obligatoire
Cf.4.8
Nom
Numéro de la rue
Adresse de livraison
Deuxième ligne d’adresse de livraison
Quartier
Code postal
Ville de livraison
Etat de livraison
Pays de livraison
Informations sur le transporteur
Mode de livraison (cf.4.9)
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
ctxMode
string
browserUserAgent
browserAccept
string
string
Description
Obligatoire
Contexte de sollicitation de la plateforme de paiement.
("TEST", "PRODUCTION")
Header « User-Agent » du navigateur du client
Header « Accept » du navigateur du client
createExtraInfo.ctxMode, createExtraInfo.browserUserAgent, createExtraInfo.browserAccept
Payzen –
12/56
4.8 custStatus
Ce type décrit le type de client. Les valeurs possibles sont définies ci-dessous :
Valeur
Description
PRIVATE
COMPANY
Particulier
Entreprise
4.9 deliverySpeed
Ce type décrit le mode de livraison. Les valeurs possibles sont définies ci-dessous :
Valeur
Description
STANDARD
EXPRESS
Livraison Standard
Livraison Express
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
RELAY_POINT
RECLAIM_IN_STATION
PACKAGE_DELIVERY_COMPANY
ETICKET
Retrait de la marchandise en magasin
Utilisation d'un réseau de points-retrait tiers :
(type Kiala, Alveol, etc.)
Retrait dans un aéroport, une gare ou une agence de voyage
Transporteur (La poste, Colissimo, UPS, DHL…)
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
key
value
Valeur
string
string
Description
Nom de la donnée
Valeur de la donnée
extInfo.key, extInfo.value
Payzen –
13/56
4.12 createWithThreeDSResponse
Ce type décrit la réponse envoyée lors d’un appel à la méthode createWithThreeDS.
Nom du champ
errorCode
Type
Description
int
Code d’erreur cf. 3
Détail de l’erreur si le champ errorCode est
différent de 0
Timestamp permettant la génération de signature
unique
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 ».
Cf. 4.13
Ce champ ne sera renvoyé que si la carte est
enrôlée. Dans ce cas, le champ transactionInfo ne
sera pas envoyé.
Descriptif de la transaction. Cf. 4.14
Ne sera pas envoyé si la carte est enrôlée.
extendedErrorCode
string
timestamp
long
signature
string
veResPAReqInfo
transactionInfo
veResPAReqInfo
transactionInfo
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).
4.13 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
errorDetail
signature
timestamp
threeDSAcctId
threeDSAcsUrl
threeDSBrand
threeDSEncodedPareq
int
string
string
long
String
String
String
String
threeDSEnrolled
String
threeDSRequestId
String
Code d’erreur cf. 3
Détail de l’erreur si le champ errorCode est différent de 0
Signature de la Réponse (cf. ci-dessous)
Timestamp permettant la génération de signature unique
certificat renvoyé par le Directory Server
Url de l’ACS à contacter
Réseau de carte
message PAReq encodé, prêt à envoyer à l’ACS
Statut d’enrôlement du porteur :
•
« Y » : Enrôlé
numéro de requête, à rappeler dans l’appel
finalizeWithThreeDS
errorCode, errorDetail, timestamp, threeDSAcctId , threeDSAcsUrl, threeDSBrand,
threeDSEncodedPareq, threeDSEnrolled threeDSRequestId
Payzen –
14/56
4.14 transactionInfo
Ce type décrit une transaction :
Nom du champ
errorCode
extendedErrorCode
transactionStatus
timestamp
signature
paymentGeneralInfo
cardInfo
threeDSInfo
authorizationInfo
markInfo
warrantyDetailsInfo
captureInfo
customerInfo
shippingInfo
extraInfo
paymentOptionInfo
boletoInfo
Type
Description
int
Code d’erreur (cf.3)
Détail de l’erreur si le champ errorCode est
différent de 0
Code du statut de la transaction (cf. 6)
Timestamp permettant la génération de
signature unique
Signature de la transaction
Libellé su statut de la transaction (cf.6)
Cf. 4.15
Cf. 4.16
Cf. 4.17
Cf. 4.18
Cf. 4.19
Cf. 4.20
Cf. 4.22
Cf. 4.23
Cf. 4.24
Cf. 4.25
Réservé à un usage spécifique
Réserve à un usage spécifique
string
int
long
string
String
transactionPaymentGeneralInfo
transactionCardInfo
transactionThreeDSInfo
transactionAuthorizationInfo
transactionMarkInfo
transactionWarrantyDetailsInfo
transactionCaptureInfo
transactionCustomerInfo
transactionShippingInfo
transactionExtraInfo
transactionPaymentOptionInfo
transactionBoletoExtraInfo
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
Payzen –
15/56
4.15 transactionPaymentGeneralInfo
Ce type décrit les informations générales d’une transaction :
Type
Description
siteId
Nom du champ
string
paymentSource
string
Source du paiement :
- "E_COMMERCE" : e-Commerce
- "MAIL_OR_TELEPHONE" : mail ou téléphone
- "CALL_CENTER" : centre d’appel
- "OTHER" : autres
Référence de la commande
Description libre de la commande
Date et heure de la transaction
Identifiant de transaction
Numéro de séquence de la transaction
Montant actuel de la transaction en plus petite unité monétaire
Montant initial (avant modification éventuelle) en plus petite
unité monétaire
Code de la devise (Code monnaie ISO 4217, Euro : 978)
Montant en contre-valeur en plus petite unité monétaire
Devise en contre-valeur (Code monnaie ISO 4217, Euro : 978)
Date de remise demandée
0 = DEBIT, 1 = CREDIT
Paiement en plusieurs fois (Non = 0, Oui = 1)
Date réelle d’enregistrement de la transaction
orderId
orderInfo
orderInfo2
orderInfo3
transmissionDate
transactionId
sequenceNumber
amount
initialAmount
currency
effectiveAmount
effectiveCurrency
presentationDate
type
multiplePayment
effectiveCreationDate
string
string
string
string
dateTime
string
int
string
string
int
string
int
dateTime
int
int
dateTime
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,
Payzen –
16/56
4.16 transactionCardInfo
Ce type décrit le détail de la carte:
Nom du champ
Type
Description
cardNumber
cardNetwork
cardBrand
string
string
string
cardCountry
long
cardProductCode
cardBankCode
expiryMonth
expiryYear
contractNumber
string
string
int
int
string
Numéro de carte masqué
Réseau de la carte
Brand de la carte
Code Pays du pays d’émission de la carte (Code numérique ISO 3166-1
ex : France=250)
Code produit de la carte
Code banque de la banque émettrice
Mois d’expiration entre 1 et 12
Année d’expiration sur 4 chiffres
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
Payzen –
17/56
4.17 transactionThreeDSInfo
Ce champ décrit les détails de l’authentification 3D-Secure :
Nom du champ
threeDSTransactionCondition
Type
string
threeDSEnrolled
string
threeDSStatus
string
threeDSEci
threeDSXid
string
string
threeDSCavvAlgorithm
string
threeDSCavv
threeDSSignValid
threeDSBrand
string
string
string
Description
"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é
•
"N" : Non enrôlé
•
"U" : Inconnu
Statut authentification du porteur:
•
"Y" : Authentifié 3DS
•
"N" : Erreur Authentification
•
"U" : Authentification impossible
•
"A" : Essai d’authentification
Indicateur de commerce Electronique
Numéro de transaction 3DS
Algorithme de vérification de l’authentification du porteur
(CAVV) :
"0" : HMAC
"1" : CVV
"2" : CVV_ATN
"3" : Mastercard SPA
Certificat de l’ACS
Signature de l’authentification 3DS
Brand de la carte ("VISA" ou "MASTERCARD")
Détails threeDSTransactionCondition:
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.
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.
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
Payzen –
18/56
4.18 transactionAuthorizationDSInfo
Ce type décrit le détail de la demande d’autorisation :
Nom du champ
authMode
Type
string
Description
"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
authAmount
string
Montant de l’autorisation dans la plus petite unité monétaire (en
centimes pour Euro) dans le cas où authMode vaut FULL
authCurrency
string
Code de la monnaie utilisée lors de la demande d’autorisation
(suivant la norme ISO 4217) dans le cas où authMode vaut FULL.
authDate
string
Date et heure de la demande d’autorisation dans le cas où
authMode vaut FULL.
authNumber
string
Numéro de la demande d’autorisation dans le cas où authMode
vaut FULL
int
Résultat de la demande d’autorisation dans le cas où authMode
vaut FULL
authResult
authCVV2_CVC2
string
Information relative au traitement du cryptogramme visuel de
l’autorisation
transactionAuthorizationInfo.authMode, transactionAuthorizationInfo.authAmount,
transactionAuthorizationInfo.authCurrency, transactionAuthorizationInfo.authNumber,
transactionAuthorizationInfo.authResult, transactionAuthorizationInfo.authCVV2_CVC2
Payzen –
19/56
Liste des valeurs possibles pour les champs authResult et markResult.
Valeur
00
02
03
04
05
07
08
12
13
14
15
17
19
20
24
25
26
27
28
29
30
31
33
34
38
41
43
51
54
55
56
57
58
59
60
61
63
68
75
76
90
91
94
96
97
98
99
Description
transaction approuvée ou traitée avec succès
contacter l’émetteur de carte
accepteur invalide
conserver la carte
ne pas honorer
conserver la carte, conditions spéciales
approuver après identification
transaction invalide
montant invalide
numéro de porteur invalide
Emetteur de carte inconnu
Annulation client
Répéter la transaction ultérieurement
Réponse erronée (erreur dans le domaine serveur)
Mise à jour de fichier non supportée
Impossible de localiser l’enregistrement dans le fichier
Enregistrement dupliqué, ancien enregistrement remplacé
Erreur en « edit » sur champ de lise à jour fichier
Accès interdit au fichier
Mise à jour impossible
erreur de format
identifiant de l’organisme acquéreur inconnu
date de validité de la carte dépassée
suspicion de fraude
Date de validité de la carte dépassée
carte perdue
carte volée
provision insuffisante ou crédit dépassé
date de validité de la carte dépassée
Code confidentiel erroné
carte absente du fichier
transaction non permise à ce porteur
transaction interdite au terminal
suspicion de fraude
l’accepteur de carte doit contacter l’acquéreur
montant de retrait hors limite
règles de sécurité non respectées
réponse non parvenue ou reçue trop tard
Nombre d’essais code confidentiel dépassé
Porteur déjà en opposition, ancien enregistrement conservé
arrêt momentané du système
émetteur de cartes inaccessible
transaction dupliquée
mauvais fonctionnement du système
échéance de la temporisation de surveillance globale
serveur indisponible routage réseau demandé à nouveau
incident domaine initiateur
Payzen –
20/56
4.19 transactionMarkInfo
Ce type décrit le détail de la demande d’empreinte :
Nom du champ
Type
markAmount
long
markCurrency
int
markDate
markNb
markResult
markCVV2_CVC2
dateTime
string
int
string
Description
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.
Code de la monnaie utilisée pour vérifier la validité de la
carte (suivant la norme ISO 4217).
Sa valeur est 100.
Date et heure de la demande d’autorisation réalisée dans le
cas où transactionAuthorizationInfo.authmode vaut MARK
Numéro d’autorisation de la demande d’autorisation dans
le cas où transactionAuthorizationInfo.authmode vaut MARK
Résultat de la demande d’autorisation réalisée l dans le cas
où transactionAuthorizationInfo.authmode vaut MARK
Information relative au traitement du cryptogramme visuel.
transactionMarkInfo.markAmount, transactionMarkInfo.markCurrency,
transactionMarkInfo.markNb, transactionMarkInfo.markResult,
transactionMarkInfo.markCVV2_CVC2
4.20 transactionWarrantyDetailsnfo
Ce type décrit le détail de la garantie du paiement et des contrôles locaux :
Nom du champ
paymentError
warrantlyResult
localControl
litige
Type
int
string
Array
localControl
boolean
Description
Complément d’information en cas d’erreur technique.
Garantie de paiement (YES / NO)
Tableau des résultats des différents contrôles locaux
Litige
transactionWarrantyDetailsInfo.paymentError, transactionWarrantyDetailsInfo.warrantlyResult,
transactionWarrantyDetailsInfo.localControl, transactionWarrantyDetailsInfo.litige
Payzen –
21/56
4.21 localControl
Ce type décrit un contrôle local (nom du contrôle et résultat).
Nom du champ
Type
name
result
string
boolean
Description
Nom du contrôle
Résultat du contrôle
localControl.name, localControl.result
Les différentes valeurs possibles pour ‘name’ sont :
Valeur
Description
Carte située dans une liste grise
"CARD"
"AMOUNT"
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
"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
"COUNTRY"
"IPADDR"
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
Payzen –
22/56
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
captureDate
captureNumber
rapprochementStatut
Type
dateTime
int
int
refundAmount
long
refundCurrency
int
Description
Date et heure de remise
Numéro de remise
Statut de rapprochement bancaire de la transaction.
Montant ayant déjà fait l’objet d’un remboursement en
plus petite unité monétaire
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
customerId
customerTitle
customerStatus
customerName
customerPhone
customerEmail
customerAddressNumber
customerAddress
customerDistrict
customerZip
customerCity
customerCountry
language
customerIP
customerCellPhone
extInfo
Type
string
string
custStatus
string
string
string
string
string
string
string
string
string
string
string
string
Array
extInfo
Description
Référence client
Civilité
Cf.4.8
Nom du client
Adresse de courrier électronique
Numéro de la rue
Numéro de rue
Quartier
Code postal
Ville
Pays
Langue du client (norme ISO 639-1 sur 2 caractères).
Adresse IP du lient
Téléphone mobile du client
Cf. 4.11
transactionCustomerInfo.customerId, transactionCustomerInfo.customerTitle,
transactionCustomerInfo.customerStatus, transactionCustomerInfo.customerName,
transactionCustomerInfo.customerPhone, transactionCustomerInfo.customerEmail,
transactionCustomerInfo.customerAddressNumber,
transactionCustomerInfo.customerAddress, transactionCustomerInfo.customerDistrict,
transactionCustomerInfo.customerZip, transactionCustomerInfo.customerCity,
transactionCustomerInfo.customerCountry, transactionCustomerInfo.language,
transactionCustomerInfo.customerIP, transactionCustomerInfo.customerCellPhone,
transactionCustomerInfo.extInfo
Payzen –
23/56
4.24 transactionShippingInfo
Ce type décrit les informations de livraison :
Nom du champ
Type
shippingCity
shippingCountry
shippingDeliveryCompanyName
shippingName
shippingPhone
shippingSpeed
shippingState
shippingStatus
shippingStreetNumber
shippingStreet
shippingStreet2
shippingDistrict
shippingType
shippingZipCode
string
string
string
string
string
deliverySpeed
string
custStatus
string
string
string
string
deliveryType
string
Description
Ville de livraison
Pays de livraison
Informations sur le transporteur
Nom
Mode de livraison (cf.4.9)
Etat de livraison
Cf. 4.8
Numéro de la rue
Adresse de livraison
Deuxième ligne d’adresse de livraison
Quartier
Méthode de livraison (cf.4.10)
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
ctxMode
Type
string
Description
Contexte de sollicitation de la plateforme de paiement.
transactionExtraInfo.ctxMode
Payzen –
24/56
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
paymentGeneralInfo
cardInfo
threeDsResult
subPaymentInfo
customerInfo
shippingInfo
extraInfo
Type
Description
createPaymentGeneralInfo
createCardInfo
threeDsResult
createSubPaymentInfo
createCustomerInfo
createShippingInfo
createExtraInfo
Cf. 4.2
Cf. 4.3
Cf. 4.27
Cf. 4.4
Cf. 4.5
Cf. 4.6
Cf. 4.7
Obligatoire
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
threeDSBrand
string
threeDSEnrolled
string
threeDSStatus
string
threeDSEci
threeDSXid
threeDSCavv
string
string
string
threeDSCavvAlgorithm
string
Description
Obligatoire
Brand de la carte ("VISA" ou "MASTERCARD")
Statut enrôlement porteur :
"Y" : Enrôlé
"N" : Non enrôlé
"U" : Inconnu
Statut authentification du porteur:
"Y" : Authentifié 3DS
"N" : Erreur Authentification
"U" : Authentification impossible
"A" : Essai d’authentification
Indicateur de commerce Electronique
Numéro de transaction 3DS
Certificat de l’ACS
Algorithme de vérification de l’authentification du
porteur (CAVV) :
"0" : HMAC
"1" : CVV
"2" : CVV_ATN
"3" : Mastercard SPA
threeDsResult.threeDSBrand, threeDsResult.threeDSEnrolled, threeDsResult.threeDSStatus,
threeDsResult.threeDSEci, threeDsResult.threeDSXid, threeDsResult.threeDSCavv,
threeDsResult.threeDSCavvAlgorithm
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.
Payzen –
25/56
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.
4.28 standardResponse
Ce type permet de décrire la réponse des méthodes cancel, force et validate.
Nom du champ
errorCode
extendedErrorCode
transactionStatus
timestamp
signature
Type
int
String
int
long
String
Description
Code d’erreur (cf. 3)
Précision sur le code d’erreur
Statut de la transaction (cf. 6)
Timestamp permettant la génération de signature unique
Signature de la transaction (cf.5)
errorCode, extendedErrorCode, transactionStatus, timestamp
Payzen –
26/56
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.
______________________________________________________________________________________________
Payzen –
27/56
6. STATUT D’UNE TRANSACTION
Les différents statuts de la transaction (transactionStatus) peuvent être :
Valeur
"0"
"1"
"2"
"3"
"4"
"5"
"6"
"7"
"8"
"9"
transactionStatus
Initial (en traitement)
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
"INITIAL"
"AUTHORISED_TO_VALIDATE"
" REFUSED "
"WAITING_AUTHORISATION_TO_VALIDATE"
"AUTHORISED"
"WAITING_AUTHORISATION"
"CAPTURED"
"EXPIRED"
" REFUSED "
"CANCELLED"
"11"
En cours de remise
"AUTHORISED"
"12"
En cours d’autorisation
"WAITING_AUTHORISATION"
"13"
En échec
"CAPTURE_FAILED"
Payzen –
28/56
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.
Payzen –
29/56
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)
Payzen –
30/56
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
createInfo
wsSignature
Type
createPaymentInfo
String
Description
Obligatoire
Cf. 4.1
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. 4.12
Payzen –
31/56
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=http://schemas.xmlsoap.org/soap/envelope/
xmlns:ns1="http://v4.ws.vads.lyra.com/">
<SOAP-ENV:Body>
<ns1:createWithThreeDS>
<createInfo>
<paymentGeneralInfo>
<siteId>91335531</siteId>
<transmissionDate>2012-06-12T08:43:28+00:00</transmissionDate>
<transactionId>084328</transactionId>
<paymentSource>EC</paymentSource>
<orderId>CMD-TEST</orderId>
<amount>3000</amount>
<currency>978</currency>
</paymentGeneralInfo>
<cardInfo>
<cardNumber>4970100000000000</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>98d5a4796386625a63fc0068a867b2ef57607254</wsSignature>
</ns1:createWithThreeDS>
</SOAP-ENV:Body></SOAP-ENV:Envelope>
Payzen –
32/56
Exemple de fichier XML généré en réponse à l’appel createWithThreeDS (carte enrôlée) :
<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
<env:Header></env:Header>
<env:Body>
<ns1:createWithThreeDSResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'>
<return>
<errorCode>0</errorCode>
<timestamp>1339592387720</timestamp>
<signature>3045335d5a19152a297bace106f3ed241994ef6f</signature>
<veResPAReqInfo>
<signature>4d0073dc0e4ec3ffba03a1971f42761d98a34c9c</signature>
<threeDSAcctId>fa1e2b46604f412eb01bbd27cb28</threeDSAcctId>
<threeDSAcsUrl>https://secure.payzen.eu/vads-mpi/acs.a
</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>
Payzen –
33/56
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
PaReq
String
TermUrl
String
MD
String
Description
Obligatoire
Message codé, retourné par l’appel de la méthode
sendVEReqAndBuildPaReqTx
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
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="https://secure.payzen.eu/vadspayment/acs.silent_authenticate.a;jsessionid=B420BF68835F6563FB6E4B289ABB9080.bdxvad
3" >
...
</form>
EN MODE PRODUCTION VOUS NE DEVEZ EN AUCUN CAS TRANSMETTRE UN
IDENTIFIANT DE SESSION A L’ACS
______________________________________________________________________________________________
Payzen –
34/56
Exemple de page de redirection
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" 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>
Payzen –
35/56
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>
Payzen –
36/56
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
threeDSrequestId
pares
wsSignature
Type
String
String
String
Description
Obligatoire
numéro de requête obtenu dans la réponse
createWithThreeDSResponse.
Message PaRes encodé, reçu de l’ACS
Signature (cf. ci-dessous)
threeDSrequestId, pares
Cette fonction retourne une réponse du type transactionInfo cf. 4.14. Le champ
transactionInfo.transactionThreeDSInfo contient le résultat de la demande d’authentification 3DSecure.
________________________________________________________________________________________________
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 :
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<ns1:finalizeWithThreeDS>
<requestId>_e23491ca-4d20-4b70-8bea-4b658c071784</requestId>
<pares>eJzNWdmSo0iyfecrymoe1VUsYhFjyhw==</pares>
<wsSignature>6974b7cc7e3495e53e5e0ff6d83a3e5317957309</wsSignature>
</ns1:finalizeWithThreeDS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Payzen –
37/56
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
En attente d’auto
En attente de remise
Nom du champ
Type
siteId
String
transmissionDate
Date
transactionId
String
sequenceNumber
Int
ctxMode
String
amount
currency
Long
Int
presentationDate
Date
validate
comment
wsSignature
bool
String
String
Description
Obligatoire
Date et heure de création de la transaction à
modifier, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à modifier
Numéro de séquence de la transaction à modifier.
Vaut "1" pour un paiement unitaire.
Prend la valeur du numéro d’échéance dans le cas
d’un paiement en plusieurs fois.
Contexte de sollicitation de la plateforme de
paiement ("TEST", "PRODUCTION")
Montant demandé en plus petite unité monétaire
Devise (Code monnaie ISO 4217, Euro : 978)
Date remise demandée, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Validation de la transaction : 0 -> non ; 1 -> oui
Commentaire « libre »
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.
__________________________________________________________________________________________
Payzen –
38/56
Exemple de fichier XML généré lors de l’appel modify :
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<ns1:modify>
<sequenceNumber>1</sequenceNumber>
<captureDate>2013-05-16T08:09:22+00:00</captureDate>
<validationMode>true</validationMode>
<comment></comment>
<wsSignature>532bfc85fac7b4af69323e9026806b5392019c62</wsSignature>
</ns1:modify>
</SOAP-ENV:Body>
Calcul de signature associé :
70258842+965805+1+TEST+15800+978+1++certificat
Exemple de fichier XML généré en réponse à l’appel modify:
<env:Header></env:Header>
<env:Body>
<ns1:modifyResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'>
<return>
<transactionStatus>4</transactionStatus>
<signature>fab6756f305cd7f78863c569492f2251ba69186a</signature>
<transactionStatusLabel>AUTHORISED</transactionStatusLabel>
<paymentSource>OTHER</paymentSource>
<initialAmount>15800</initialAmount>
<presentationDate>2013-05-16T10:09:22+02:00</presentationDate>
<type>0</type>
<multiplePayment>0</multiplePayment>
<effectiveCreationDate>2013-05-16T10:08:43+02:00</effectiveCreationDate>
<cardInfo>
<cardNumber>497010XXXXXX0000</cardNumber>
Payzen –
39/56
<cardBrand>CB</cardBrand>
<cardCountry>250</cardCountry>
<contractNumber>1111112</contractNumber>
</cardInfo>
<threeDSInfo>
<threeDSTransactionCondition>COND_SSL</threeDSTransactionCondition>
</threeDSInfo>
<authorizationInfo>
<authMode>FULL</authMode>
<authAmount>15800</authAmount>
<authCurrency>978</authCurrency>
<authDate>2013-05-16T10: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>78.245.84.102</customerIP>
</customerInfo>
<shippingInfo/>
<extraInfo>
</extraInfo>
</return>
</ns1:modifyResponse>
</env:Body>
</env:Envelope>
Calcul de signature de la réponse:
0++4+1368691764166+70258842+OTHER+++++965805+1+15800+15800+978+++0+0+497010XXXXXX00
00+CB+CB+250+5+2014+1111112+++COND_SSL+++++++++FULL+15800+978+315637+0++++++++NO+
CARD+0++0+0+0+978+++++++++++++fr_FR+78.245.84.102+++++++++++++++++TEST+AUTHORISED
+certificat
Payzen –
40/56
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
Nom du champ
createInfo
wsSignature
Type
paymentCreationInfo
String
Description
Obligatoire
Cf. 4.26
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.
__________________________________________________________________________________________
Payzen –
41/56
Exemple de fichier XML généré lors de l’appel create sans Infos 3D-S :
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<ns1:create>
<createInfo>
<paymentSource>EC</paymentSource>
<validationMode>0</validationMode>
<cardInfo>
<cardNumber>4970100000000000</cardNumber>
<cvv>123</cvv>
</cardInfo>
<customerInfo>
<customerEmail>[email protected]</customerEmail>
<customerSendEmail>true</customerSendEmail>
</customerInfo>
<extraInfo>
</extraInfo>
</createInfo>
<wsSignature>0a288b4f237d6a76d429047cd28b4cc255e09423</wsSignature>
</ns1:create>
</SOAP-ENV:Body>
Calcul de signature associé :
70258842+432617+EC+CMD-TEST++++1200+978+0+****************+CB+11+2020+123++++++++++++
[email protected]++++++++127.0.0.1+1++++TEST+++certificat
Payzen –
42/56
Exemple de fichier xml généré en réponse à l’appel create :
<env:Header>
</env:Header>
<env:Body>
<ns1:createResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'>
<return>
<transactionStatus>4</transactionStatus>
<signature>c8c5dc5c368860184af00dbf4e8d84d50dc38f5c</signature>
<transactionStatusLabel>AUTHORISED</transactionStatusLabel>
<paymentSource>E_COMMERCE</paymentSource>
<initialAmount>1200</initialAmount>
<type>0</type>
<multiplePayment>0</multiplePayment>
<cardInfo>
<cardNumber>497010XXXXXX0000</cardNumber>
<cardBrand>CB</cardBrand>
<cardCountry>250</cardCountry>
<cardProductCode>F</cardProductCode>
<contractNumber>1111112</contractNumber>
</cardInfo>
<threeDSInfo>
<threeDSTransactionCondition>COND_SSL</threeDSTransactionCondition>
</threeDSInfo>
<authorizationInfo>
<authMode>FULL</authMode>
<authAmount>1200</authAmount>
<authCurrency>978</authCurrency>
<authDate>2013-07-19T12:01:02.583+02:00</authDate>
<authNumber>264782</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>
Payzen –
43/56
<refundAmount>0</refundAmount>
<refundCurrency>978</refundCurrency>
</captureInfo>
<customerInfo>
<customerEmail>[email protected]</customerEmail>
<language>fr_FR</language>
</customerInfo>
<shippingInfo/>
<extraInfo>
</extraInfo>
</return>
</ns1:createResponse>
</env:Body>
</env:Envelope>
Calcul de signature de la réponse:
0++4+1374228062583+70258842+E_COMMERCE+CMD-TEST++++432617+1+1200+1200+978+++0+0+
497010XXXXXX0000+CB+CB+250+11+2020+1111112++F+COND_SSL+++++++++FULL+1200+978+
[email protected]+++++++fr_FR+127.0.0.
1+++++++++++++++++TEST+AUTHORISED+certificate
Payzen –
44/56
7.5 Annulation d’une transaction (cancel)
Cette fonction 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
Nom du champ
siteId
Type
String
Date
transmissionDate
transactionId
String
Int
sequenceNumber
ctxMode
String
wsSignature
String
Description
Obligatoire
annuler, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à annuler
Numéro de séquence de la transaction à annuler.
d’un paiement en plusieurs fois
Signature (cf.5)
siteId, transactionId, sequenceNumber, ctxMode, comment
Cette fonction retourne une réponse du type standardResponse (cf.4.28).
Payzen –
45/56
7.6 Forçage d’une transaction (force)
Cette fonction 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.
Nom du champ
siteId
Type
String
Date
transmissionDate
transactionId
String
Int
sequenceNumber
ctxMode
String
authNumber
string
authDate
Date
comment
wsSignature
String
String
Description
Obligatoire
forcer, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à forcer
Numéro de séquence de la transaction à forcer.
Numéro d’autorisation
Date et heure de la demande d’autorisation
exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Signature (cf.5)
siteId, transactionId, sequenceNumber, ctxMode, authNumber, comment.
Payzen –
46/56
7.7 Remboursement d’une transaction (refund)
Cette fonction permet de rembourser le porteur.
Les transactions pouvant faire l’objet d’un remboursement possède le statut suivant :
•
Remisé
Nom du champ
Type
siteId
String
transmissionDate
Date
transactionId
String
sequenceNumber
Int
ctxMode
String
newTransactionId
amount
currency
String
Long
Int
presentationDate
Date
validationMode
comment
wsSignature
int
String
String
Description
Obligatoire
Date et heure de création de la transaction à rembourser,
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à rembourser
Numéro de séquence de la transaction à rembourser.
Prend la valeur du numéro d’échéance dans le cas d’un
paiement en plusieurs fois.
Contexte de sollicitation de la plateforme de paiement
Identifiant de la transaction créée
Montant à rembourser en plus petite unité monétaire
Date de remise demandée, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
0 = Automatique, 1 = Manuelle
Signature (cf. 5)
siteId, transactionId, sequenceNumber, ctxMode, newTransactionId, amount, currency,
validationMode, comment
Cette fonction retourne une réponse du type transactionInfo (cf.4.14).
Remarque importante
Si la carte est expirée lors de la demande de remboursement, une transaction refusée pour motif
carte expirée sera créée. La réponse contiendra les valeurs suivantes :
errorCode : 0
transactionStatus : 8
Payzen –
47/56
7.8 Duplication d’une transaction (duplicate)
Cette fonction 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ède le statut suivant :
•
Remisé
•
Expiré
•
Annulé
•
Refusé
Nom du champ
Type
siteId
String
transmissionDate
Date
transactionId
String
sequenceNumber
Int
ctxMode
String
orderId
orderInfo
orderInfo2
orderInfo3
amount
currency
newTransactionId
String
String
String
String
Long
Int
String
presentationDate
Date
validationMode
comment
wsSignature
int
String
String
Description
Obligatoire
Date et heure de création de la transaction à dupliquer,
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à dupliquer
Numéro de séquence de la transaction à dupliquer.
Référence de la commande
Montant en plus petite unité monétaire
Identifiant de la transaction crée
Date de remise demandée, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
0 = Automatique, 1 = Manuelle
Signature (cf. 5)
siteId, transactionId, sequenceNumber, ctxMode, orderId, orderInfo, orderInfo2, orderInfo3,
amount, currency, newTransactionId, validationMode, comment
Cette fonction retourne une réponse du type transactionInfo (cf.4.14).
Payzen –
48/56
7.9 Recherche des détails d’une transaction (getInfo)
Cette fonction permet d’interroger une transaction pour en connaître ses différents attributs.
Nom du champ
Type
siteId
String
transmissionDate
Date
transactionId
String
sequenceNumber
Int
ctxMode
String
wsSignature
String
Description
Obligatoire
rechercher, exprimée au format W3C
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à rechercher
Numéro de séquence de la transaction à
rechercher.
Signature (cf.5)
siteId, transactionId, sequenceNumber, ctxMode
Cette fonction retourne une réponse du type transactionInfo (cf. 4.14).
Payzen –
49/56
7.10 Validation d’une transaction (validate)
Cette fonction 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
Nom du champ
Type
siteId
String
transmissionDate
Date
transactionId
String
sequenceNumber
Int
ctxMode
String
comment
wsSignature
String
String
Description
Obligatoire
Date et heure de création de la transaction à valider,
(Ex : 2012-06-08T08:16:43+00:00).
Identifiant de la transaction à valider
Numéro de séquence de la transaction à valider.
Signature (cf. 5)
siteId, transactionId, sequenceNumber, ctxMode, comment
Payzen –
50/56
8. ANNEXES
8.1 Cartes de test
Ci-dessous la liste des numéros de carte à utiliser en mode TEST :
Numéro de carte
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.
__________________________________________________________________________________________
Payzen –
51/56
8.2 Exemple d’implémentation en PHP : calcul de signature (méthode create)
$hashSign='';
$hashSign=
/**
paymentCreationInfo.paymentGeneralInfo
*/
getSignatureValue($createInfo->paymentGeneralInfo->siteId).
getSignatureValue($createInfo->paymentGeneralInfo->transactionId).
getSignatureValue($createInfo->paymentGeneralInfo->paymentSource).
getSignatureValue($createInfo->paymentGeneralInfo->orderId).
getSignatureValue($createInfo->paymentGeneralInfo->orderInfo).
getSignatureValue($createInfo->paymentGeneralInfo->orderInfo2).
getSignatureValue($createInfo->paymentGeneralInfo->orderInfo3).
getSignatureValue($createInfo->paymentGeneralInfo->amount).
getSignatureValue($createInfo->paymentGeneralInfo->currency).
getSignatureValue($createInfo->paymentGeneralInfo->validationMode).
/**
paymentCreationInfo.cardInfo
*/
getSignatureValue($createInfo->cardInfo->cardNumber).
getSignatureValue($createInfo->cardInfo->cardNetwork).
getSignatureValue($createInfo->cardInfo->expiryMonth).
getSignatureValue($createInfo->cardInfo->expiryYear).
getSignatureValue($createInfo->cardInfo->cvv).
getSignatureValue($createInfo->cardInfo->cardIdent).
getSignatureValue($createInfo->cardInfo->cardBirthDay).
getSignatureValue($createInfo->cardInfo->contractNumber).
getSignatureValue($createInfo->cardInfo->paymentOptionCode);
/**
paymentCreationInfo.threeDsResult
*/
if (!is_null($createInfo->threeDsResult)){
$hashSign .=
getSignatureValue($createInfo->threeDsResult->threeDSBrand).
getSignatureValue($createInfo->threeDsResult->threeDSEnrolled).
getSignatureValue($createInfo->threeDsResult->threeDSStatus).
getSignatureValue($createInfo->threeDsResult->threeDSEci).
getSignatureValue($createInfo->threeDsResult->threeDSXid).
getSignatureValue($createInfo->threeDsResult->threeDSCavv).
getSignatureValue($createInfo->threeDsResult->threeDSCavvAlgorithm);
}
else{
$hashSign .= "+";
}
/**
paymentCreationInfo.subPaymentInfo
*/
if (!is_null($createInfo->subPaymentInfo)){
$hashSign .=
getSignatureValue($createInfo->subPaymentInfo->subPaymentType).
getSignatureValue($createInfo->subPaymentInfo->subReference).
getSignatureValue($createInfo->subPaymentInfo->subPaymentNumber);
}
else{
$hashSign .= "+";
}
/**
paymentCreationInfo.customerInfo
*/
if (!is_null($createInfo->customerInfo)){
Payzen –
52/56
$hashSign .=
getSignatureValue($createInfo->customerInfo->customerId).
getSignatureValue($createInfo->customerInfo->customerTitle).
getSignatureValue($createInfo->customerInfo->customerStatus).
getSignatureValue($createInfo->customerInfo->customerName).
getSignatureValue($createInfo->customerInfo->customerPhone).
getSignatureValue($createInfo->customerInfo->customerEmail).
getSignatureValue($createInfo->customerInfo->customerAddressNumber).
getSignatureValue($createInfo->customerInfo->customerAddress).
getSignatureValue($createInfo->customerInfo->customerDistrict).
getSignatureValue($createInfo->customerInfo->customerZip).
getSignatureValue($createInfo->customerInfo->customerCity).
getSignatureValue($createInfo->customerInfo->customerCountry).
getSignatureValue($createInfo->customerInfo->language).
getSignatureValue($createInfo->customerInfo->customerIP).
getSignatureValue($createInfo->customerInfo->customerSendEmail).
getSignatureValue($createInfo->customerInfo->customerCellPhone).
getSignatureValue($createInfo->customerInfo->extInfo);
}
else{
$hashSign .= "+";
}
/**
paymentCreationInfo.shippingInfo
*/
if (!is_null($createInfo->shippingInfo)){
$hashSign .=
getSignatureValue($createInfo->shippingInfo->shippingCity).
getSignatureValue($createInfo->shippingInfo->shippingCountry).
getSignatureValue($createInfo->shippingInfo->shippingDeliveryCompanyName).
getSignatureValue($createInfo->shippingInfo->shippingName).
getSignatureValue($createInfo->shippingInfo->shippingPhone).
getSignatureValue($createInfo->shippingInfo->shippingSpeed).
getSignatureValue($createInfo->shippingInfo->shippingState).
getSignatureValue($createInfo->shippingInfo->shippingStatus).
getSignatureValue($createInfo->shippingInfo->shippingStreetNumber).
getSignatureValue($createInfo->shippingInfo->shippingStreet).
getSignatureValue($createInfo->shippingInfo->shippingStreet2).
getSignatureValue($createInfo->shippingInfo->shippingDistrict).
getSignatureValue($createInfo->shippingInfo->shippingType).
getSignatureValue($createInfo->shippingInfo->shippingZipCode);
}
else{
$hashSign .= "+";
}
/**
paymentCreationInfo.extraInfo
*/
$hashSign .=
getSignatureValue($createInfo->extraInfo->ctxMode).
getSignatureValue($createInfo->extraInfo->browserUserAgent).
getSignatureValue($createInfo->extraInfo->browserAccept);
/**
Ajout du Certificat en fin de chaine
*/
$hashSign .= $key;
Payzen –
53/56
Contenu de la fonction getSignatureValue :
function getSignatureValue($value){
$signatureValue='';
/**
* boolean
*/
if (is_bool($value)){
$signatureValue = ($value ? '1':'0').'+';
}
/**
* extInfo
*/
elseif(get_class($value)=='extInfo'){
$signatureValue.= $value->key.'+'.$value->value.'+';
}
/**
* array
*/
elseif(is_array($value)){
foreach($value as $name=>$val)
{
if(is_object($val)) {
$signatureValue .= getSignatureValue($val);
}
}
}
else {
$signatureValue .= $value . '+';
}
return $signatureValue;
}
Payzen –
54/56
8.3 Exemples de cinématique de paiement avec gestion des cas d’échec
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)
Validation acceptée (errorCode= 0 et transactionStatus= 4)
Déclencher l’expédition du colis.
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.
Payzen –
55/56
Vente de biens immatériels type VOD
Demande de paiement (Appel ws create)
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 :
Si transactionStatus = 1 : « A valider » :
Appel ws ModifyAndValidate
Réponse valide (errorCode 0) :
- mettre à jour la commande dans l’état « Payée »
- 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).
Payzen –
56/56

Définition des Webservices V4

Transcription

Documents pareils

String line collection rose Parfumé

Codification des critères de recherche (I.U.T Clermont 1)

+ Interface + main (String[]): void retourne le texte de la question +

Version imprimable

String ouvert Josephine String ouvert en Lycra rouge framboise et

Lire et écrire un enregistrement dans un fichier texte

Togo Micro Micro string réalisé dans un très beau tulle

Systèmes Distribués – TD5 CORBA: une application simple

la capote de la mort