Réussir l`intégration de Payzen Paiement par formulaire

Réussir l’intégration de Payzen
Paiement par formulaire
Version 1.4c
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 –
Réussir l’intégration de Payzen
1/18
Table des matières
1. Principe Général............................................................................................................ 3
2. Etape 1: Envoyer un formulaire de paiement en post ............................................... 4
3. Etape 2: Analyser le formulaire URL serveur en post .................................................. 6
3.1: Notion d’url serveur ........................................................................................................................................ 6
3.1.1: Notification à la fin du paiement ............................................................................................................. 6
3.1.2: Autres cas de notification .......................................................................................................................... 7
3.2: Extrait des paramètres renvoyés ................................................................................................................. 8
3.3: Analyse d’un paiement ................................................................................................................................. 9
3.4: Comment visualiser l’appel à l’URL serveur ............................................................................................. 10
3.5: Non synchronisation des paiements sur le site marchand ................................................................... 10
4. Etape 3: le retour à la boutique (facultatif) ............................................................... 11
5. Phase de test................................................................................................................ 12
5.1: Test de paiement .......................................................................................................................................... 12
5.2: Vérifier le bon fonctionnement de l’url serveur ...................................................................................... 12
5.3: Génération du certificat de production .................................................................................................. 14
6. Passage en production ............................................................................................... 15
7. Annexes........................................................................................................................ 16
7.1: Calcul de la signature ................................................................................................................................. 16
7.2: Certificat de TEST .......................................................................................................................................... 17
7.3: Certificat de Production.............................................................................................................................. 17
7.4: Personnalisation de la page de paiement. ............................................................................................ 17
8. ASSISTANCE TECHNIQUE.............................................................................................. 18
Payzen –
Réussir l’intégration de Payzen
2/18
1. PRINCIPE GENERAL
BOUTIQUE
Etape 1: Formulaire de paiement (https)
PAYZEN
Etape 2: Appel Url serveur
Etape 3: Retour à la boutique
L’implémentation technique se résume à 3 étapes :
Etape 1: Envoyer un formulaire de paiement en post.
Etape 2: Analyser le formulaire URL serveur en post (dialogue peer to peer)
Etape 3: le retour à la boutique (facultatif).
Comprendre et lire ces 3 étapes est essentiel pour implémenter le paiement.
Payzen –
Réussir l’intégration de Payzen
3/18
2. ETAPE 1: ENVOYER UN FORMULAIRE DE PAIEMENT EN POST
L’appel à la plateforme de paiement est réalisé via l’envoi d’un formulaire posté en https.
Ce formulaire contient au minimum les paramètres obligatoires listés ci-dessous ainsi qu’une
variable signature unique par formulaire attestant de son authenticité.
L’URL de la page de paiement est : https://secure.payzen.eu/vads-payment/
Paramètres obligatoires (minimum)
vads_amount
Montant de la transaction dans la plus petite unité de la devise (centime
pour €)
vads_currency
Devise : 978 pour euro
vads_site_id
Identifiant boutique à récupérer dans le back office
vads_trans_id
Identifiant transaction : unique au moins sur une même journée – nombre à
6 chiffres
vads_trans_date
Date de la transaction : fuseau horaire UTC (ex 20110710201030 )
vads_version
Valorisé à V2
vads_payment_config
Type de paiement valorisé à SINGLE pour un paiement en 1 fois
vads_page_action
Pour un paiement simple ce champ à valorisé à PAYMENT
vads_action_mode
INTERACTIVE : correspond au cas où l’acquisition des données
carte est déléguée à la plateforme.
vads_ctx_mode
Mode de fonctionnement TEST ou PRODUCTION
signature
Signature unique pour chaque paiement
Vous pouvez utiliser des paramètres facultatifs supplémentaires comme par exemple :
Paramètres facultatifs
vads_order_id
Numéro de commande sur 32 caractères alphanumériques
vads_cust_email
Adresse e-mail de l’acheteur
Grâce aux différents champs facultatifs disponibles, vous pourrez notamment :

Paramétrer le retour automatique du client vers le site marchand,

Décrire le contenu du panier et de la commande

Envoyer des informations sur le client et sur la livraison,

Personnaliser les pages de paiement…
Pour plus d’informations sur les différents paramètres disponibles lors de l’envoi du formulaire vous
pouvez vous référer à la documentation disponible sur : http://www.payzen.eu/support.php
Payzen –
Réussir l’intégration de Payzen
4/18
Signature : Pour calculer la signature il est nécessaire de récupérer le certificat de test ou de
production dans l’outil de gestion de caisse. (ONGLET PARAMETRAGE /BOUTIQUES/[NOM DE LA
BOUTIQUE]/CONFIGURATION)
Pour plus d’information sur le calcul de la signature se reporter au chapitre annexe ou à la
documentation sur http://www.payzen.eu/support.php
Remarque : Utilisation des balises html <iframe> et <frame>
Une iframe (inline frame) est utilisée pour afficher une page web dans une autre page web.
L’utilisation des iframes pour afficher la page de paiement
est interdite pour des raisons de sécurité
Exemples de codes interdits :
<FRAMESET>
<FRAME SRC="https://secure.payzen.eu/vads-payment/">
</FRAMESET>
<iframe src="https:// secure.payzen.eu/vads-payment/"></iframe>
Payzen –
Réussir l’intégration de Payzen
5/18
3. ETAPE 2: ANALYSER LE FORMULAIRE URL SERVEUR EN POST
3.1: Notion d’url serveur
La plateforme de paiement transmet automatiquement le résultat du paiement au moyen de
notifications (IPN : Instant Payment Notification).
Ces notifications sont transmises à une page de votre site qui analyse le résultat du paiement.
Cette page est appelée URL serveur.
Lors de la notification à votre URL serveur, les données sont envoyées via une requête POST, quel que
soit le protocole choisi http ou https.
L’URL serveur est le seul mécanisme à implémenter
pour synchroniser automatiquement le site de
paiement et votre site marchand.
3.1.1: Notification à la fin du paiement
Pour que la plateforme de paiement notifie systématiquement votre site marchand en cas de
paiement accepté ou refusé, vous devez paramétrer les règles de notifications.
Depuis votre back office Payzen :
1. Allez dans le menu : Paramétrage / Règles de notifications / Nom de la boutique
2. Effectuez un clic droit sur la ligne URL serveur à la fin du paiement
3. Sélectionnez Gérer la règle
4. Renseignez l’URL de votre page dans les champs URL à appeler en mode TEST et URL à
appeler en mode PRODUCTION
Payzen –
Réussir l’intégration de Payzen
6/18
5. Renseignez l’Adresses(s) mail(s) à avertir en cas d’échec
Les e-mails en cas d’échec de l’appel à l’URL serveur sont envoyés sur cette adresse.
6. Pour spécifier plusieurs adresses séparez-les par un point-virgule
7. Configurez le Rejeu automatique en cas d’échec
Cette option permet de renvoyer automatiquement la notification vers le site marchand en
cas d'échec. Après 4 tentatives infructueuses, un e-mail d'alerte est envoyé à l'adresse saisie
au paramètre précédent.
Les tentatives d'appel sont programmées à heures fixes toutes les 15 minutes (00, 15, 30, 45).
8. Sauvegardez vos modifications.
3.1.2: Autres cas de notification
En fonction des options commerciales souscrites, la plateforme de paiement pourra effectuer un
appel vers l’url serveur dans les cas suivants :

Remboursement effectué depuis le back office

Annulation d’une transaction depuis le back office

Validation d’une transaction depuis le back office

Modification d’une transaction depuis le back office

Abandon d’une transaction depuis le back office
Payzen –
Réussir l’intégration de Payzen
7/18
3.2: Extrait des paramètres renvoyés
Paramètres minimum
vads_result
Code retour général. Si égal à « 00 » le paiement est accepté, sinon le
paiement est refusé.
Ce paramètre permet de définir le statut de la transaction. Exemples de
valeurs :
REFUSED => le paiement a été refusé.
AUTHORISED => le paiement a été accepté pour le montant total de la
transaction et est en attente de remise en banque.
AUTHORISED_TO_VALIDATE => le paiement a été accepté mais est en
attente de validation manuelle de la part du marchand. Sans cette
validation, la transaction basculera dans le statut Expiré une fois le délai de
capture dépassé.
vads_trans_status
WAITING_AUTHORISATION => le paiement est en attente d’autorisation. Une
prise d’empreinte a été réalisée pour valider les données de la carte
bancaire car le délai de remise en banque est strictement supérieur à 7
jours. La demande d’autorisation pour le montant total sera réalisée
ultérieurement, avec un risque que le paiement soit refusé.
vads_auth_result
vads_auth_mode
vads_trans_id
signature
WAITING_AUTHORISATION_TO_VALIDATE => le paiement est en attente
d’autorisation et de validation manuelle. Une prise d’empreinte a été
réalisée pour valider les données de la carte bancaire car le délai de
remise en banque est strictement supérieur à 7 jours.
Sans validation de part du marchand, la transaction basculera dans le
statut Expiré une fois le délai de capture dépassé.
Code retour de la demande d'autorisation retournée par la banque
émettrice, si disponible (vide sinon). Exemples de valeur
 00 paiement accepté
 14 carte invalide
 05 ne pas honorer
Si contient FULL => Paiement accepté pour le montant total de la
transaction.
Si contient MARK => Paiement enregistré mais non encore autorisé (il s'agit
seulement d'une empreinte qui permet de valider les données cartes mais
pas la capacité de paiement de l’acheteur). L'autorisation pour le montant
total sera réalisée ultérieurement avec un risque de paiement refusé. (Se
reporter à la documentation pour plus d'information). MARK concerne les
paiements avec une date de remise en banque au-delà de la durée de
validité de l’autorisation (7 jours pour la France).
Si votre délai de remise en banque est inférieur à 7 jours pour
CB/Visa/Mastercard en France, FULL est la seule valeur possible.
Valorisé à l’identique à la valeur reçue dans le formulaire de paiement
Signature renvoyée et calculée par la plateforme de paiement
Pour plus d’information sur les paramètres renvoyés dans l’url serveur se reporter à la
documentation disponible sur http://www.payzen.eu/support.php
Payzen –
Réussir l’intégration de Payzen
8/18
3.3: Analyse d’un paiement
L’analyse du paiement s’effectue en fonction des paramètres envoyés en mode POST dans
votre URL serveur.
Dans cette requête est présente une signature qui permet de vérifier l’authenticité de la source
[vous pouvez vérifier que cette requête est bien été générée par Payzen et non par un tiers].
Une fois l’authenticité vérifiée, vous pourrez analyser les paramètres liés au paiement et traiter
la commande si le paiement est accepté.
Exemple d’algorithme d’analyse des paramètres :
Contrôle de la
signature reçue
Signature OK
NON
Ne pas tenir compte
de cette réponse ou
vérifier que le calcul
de signature est
correct.
OUI
Contrôle du type
de la transaction
vads_operation_type
CREDIT
DEBIT
La transaction est un débit ayant comme caractéristique :

Statut : vads_trans_status
La transaction est un
remboursement ayant comme
caractéristique :

Résultat : vads_result

Statut : vads_trans_status

Identifiant : vads_trans_id

Montant : vads_amount

Montant : vads_amount

Identifiant : vads_trans_id

Montant Effectif : vads_effective_amount

Type de paiement : vads_payment_config

Numéro de séquence : vads_sequence_number

Résultat d’autorisation : vads_auth_result

Garantie de paiement : vads_warranty_result

Statut 3DS : vads_threeds_status
Payzen –
Réussir l’intégration de Payzen
9/18
3.4: Comment visualiser l’appel à l’URL serveur
Chaque appel à l’URL serveur est enregistré par la plateforme de paiement. Pour vérifier l’appel à
l’URL serveur, depuis le back-office, faites un double clic sur le paiement, puis allez dans l’onglet
Historique.
La colonne Info contient le statut de l’appel à l’URL serveur.
Dans l’encadré rouge nous affichons les 80 premiers caractères envoyés par votre script.
Ceci a pour but de vous aider à débuguer votre script en cas de problème.
3.5: Non synchronisation des paiements sur le site marchand
Erreurs fréquentes :





URL serveur non renseignée dans le back office « outil de gestion de caisse »,
URL serveur qui pointe sur la page d’accueil du site marchand et qui n’exécute aucun
traitement,
URL serveur qui ne peut être appelée car bloquée par un fichier .htaccess
URL serveur bloquée par votre firewall,
Module Paypal pour Prestashop incompatible avec les autres moyens de paiement,

Redirection à l’arrivée qui entraine la perte des valeurs postées. L’url serveur contient toujours
les paramètres postés. Ne pas les trouver est toujours une erreur d’implémentation du côté du
site marchand,

Les paramètres postés dans l’URL serveur peuvent évoluer par ajout de nouveaux champs. Ne
jamais calculer la signature en se basant sur une liste fixe et prédéfinie correspondant à votre
comportement au moment de votre implémentation.
Payzen –
Réussir l’intégration de Payzen
10/18
4. ETAPE 3: LE RETOUR A LA BOUTIQUE (FACULTATIF)
Le retour à la boutique permet à l’internaute de revenir à la boutique après un clic sur le bouton
"retour boutique » présent sur la page de paiement.
Dans le formulaire de paiement il est possible de renseigner plusieurs URL de retour :

url en cas de succès,

url en cas d’annulation,

url en cas de refus, etc
(Se référer à la documentation pour connaître tous les cas possibles)
Il est conseillé dans le cas du retour à la boutique d’analyser le contenu des paramètres en
fonction du contexte de retour que vous voulez afficher à votre client:
Par exemple :

retour à l’accueil de votre site

retour sur un refus où vous pouvez proposer un moyen de paiement alternatif

retour sur un message de remerciement ou de synthèse de commande si paiement
accepté.
Il est aussi possible de paramétrer un retour automatique à la boutique en ajoutant un paramètre
dans le formulaire lors de l’appel à la page de paiement (Utilisé par les marchands qui font du
GOOGLE ANALYTICS).
La documentation est disponible sur http://www.payzen.eu/support.php
Par défaut nous ne renvoyons aucun paramètre dans l’URL retour à la boutique, mais vous pouvez
définir dans le formulaire de paiement comment recevoir les paramètres via le champ
vads_return_mode (valorisé lors de la construction de votre formulaire de paiement. c.f Etape 1).
Valeur de vads_return_mode
GET
POST
NONE
les paramètres sont renvoyés en mode GET.
les paramètres sont renvoyés en mode POST (non recommandé).
aucun paramètre n’est envoyé.
Payzen –
Réussir l’intégration de Payzen
11/18
5. PHASE DE TEST
5.1: Test de paiement
Lorsque le formulaire de paiement posté est correct une liste de cartes de test correspondant à
des scénarii différents vous sera proposée. Il suffit de cliquer sur un numéro de carte de test pour
remplir le champ de saisie pour remplir les champs de la page de paiement et ensuite cliquer sur
"Valider".
5.2: Vérifier le bon fonctionnement de l’url serveur
Pour valider le fonctionnement de l’URL serveur, suivez les étapes ci-dessous:

Vérifiez que votre url soit accessible depuis l’extérieur : La boutique ne doit pas être
protégée par un fichier .htaccess

Assurez-vous que vous n’utilisez pas de variables permettant de rediriger l’internaute
automatiquement sur votre boutique à la fin du paiement.

Vérifiez que l’URL serveur à la fin du paiement soit bien renseignée dans le back office
PayZen.

Réalisez une commande sur votre site et procédez au paiement,

A la fin du paiement ne cliquez pas sur le bouton “retour à la boutique”,

Vérifiez que votre script à bien été exécuté.
Vous avez la possibilité de voir le détail de l’appel à l’URL serveur dans votre Back Office PayZen :
Payzen –
Réussir l’intégration de Payzen
12/18
Envoyé signifie que votre serveur a bien répondu. Dans le cas contraire, un message sera affiché
en rouge avec le détail de l’erreur.
Vous pouvez également avoir un aperçu de l’appel en cliquant sur l’onglet Historique
Payzen –
Réussir l’intégration de Payzen
13/18
5.3: Génération du certificat de production
Il est conditionné par la réalisation des tests qui sont demandés dans l’outil de gestion de caisse
(onglet Paramétrage/Boutique / [Nom de votre boutique]/ Certificats) :
Pour valider chaque test, vous devrez effectuer un achat sur votre boutique, en utilisant au moins
un numéro de chaque ligne.
Chaque colonne correspond à un type de carte différent (CB/VISA, MASTERCARD, MAESTRO, VISAELECTRON).
Une fois tous les tests validés, vous pourrez cliquer sur le bouton Générer le certificat de production.
Payzen –
Réussir l’intégration de Payzen
14/18
6. PASSAGE EN PRODUCTION
Pour paramétrer votre boutique en mode production vous devez effectuer les 5 étapes suivantes :
1. La phase de test terminée vous pouvez demander auprès des services Payzen la
génération du certificat de production ou le générer vous-même suivant la délégation
donnée à la création de la boutique.
2. Modifier la variable précisant le mode de fonctionnement (vads_ctx_mode). Cette variable
devra être valorisée à "PRODUCTION" en majuscule, sans abréviation en lieu et place de la
valeur "TEST".
3. Affecter à la variable dans laquelle vous stocker votre certificat, la valeur du certificat de
Production.
4. Renseigner l’url serveur en mode production dans le back office Payzen.
5. Il est fortement conseillé de faire un paiement réel, de vérifier votre crédit en compte et de
vérifier le bon fonctionnement de l’url serveur.
Remarque :
Le mode TEST reste disponible même après avoir généré la clef de production. Il suffit de poster des
formulaires de paiement utilisant le mode TEST et le certificat de TEST.
Payzen –
Réussir l’intégration de Payzen
15/18
7. ANNEXES
7.1: Calcul de la signature

La signature sera constituée de l’intégralité des champs dont le nom commence par la
chaîne « vads_ ».

Les champs doivent être triés par ordre alphabétique.
 Les valeurs de ces champs doivent être concaténées entre elles avec le caractère « + ».

Au résultat de cette concaténation, on concatènera la valeur du certificat employé
(certificat de test ou de production).

Appliquer l’algorithme SHA1 pour obtenir la valeur de la signature
Erreur fréquente :
Le caractère + n’est pas présent entre les champs.
Dans le calcul de la signature, l’ordre alphabétique des paramètres doit être respecté.
La signature à transmettre n’est pas égale à cette chaine, mais au hachage de cette chaine à
l’aide de l’algorithme SHA-1.
Exemple :
Paramètres de la requête envoyée à la plateforme de paiement:
- vads_version = V2
- vads_page_action = PAYMENT
- vads_action_mode = INTERACTIVE
- vads_payment_config = SINGLE
- vads_site_id = 12345678
- vads_ctx_mode = TEST
- vads_trans_id = 654321
- vads_trans_date = 20090501193530
- vads_amount = 1524
- vads_currency = 978
Valeur du certificat en fonction du mode =1122334455667788
L’ordre alphabétique des paramètres est le suivant :
1.
2.
3.
4.
vads_action_mode
vads_amount
vads_ctx_mode
vads_currency
Payzen –
Réussir l’intégration de Payzen
16/18
5.
6.
7.
8.
9.
10.
vads_page_action
vads_payment_config
vads_site_id
vads_trans_date
vads_trans_id
vads_version
Il faudra rajouter à ces paramètres la valeur du certificat 1122334455667788
La chaîne à utiliser pour le hachage à l’aide de l’algorithme SHA-1 sera donc la suivante :
INTERACTIVE+1524+TEST+978+PAYMENT+SINGLE+12345678+20090501193530+654321+V2+1122334455
667788
La signature à envoyer dans le champ nommé signature est:
606b369759fac4f0864144c803c73676cbe470ff
7.2: Certificat de TEST
Le certificat de test est une chaîne qui vous servira à calculer une signature unique pour chaque
paiement. Le certificat de test est disponible dans le back office Payzen (onglet paramétrage
/boutique /[Nom de la boutique]/certificat).
7.3: Certificat de Production
Le certificat de production est une chaîne qui vous servira à calculer une signature unique pour
chaque paiement de production. Le certificat de production est disponible dans le back office
Payzen (onglet paramétrage /boutique /[Nom de la boutique]/certificat). Celui-ci ne sera plus
visible dès lors que vous aurez finalisé un paiement réel via le formulaire pour des raisons de
sécurité.
7.4: Personnalisation de la page de paiement.
Vous pouvez charger depuis le back office votre logo qui apparaîtra alors sur la page de
paiement.
Si vous souhaitez des paramètres plus avancés vous devez souscrire à l’option Personnalisation
avancée.
Cette option vous permet depuis le back office de modifier les CSS originales (mobile et écran
classique), ou encore d’ajouter plusieurs CSS. Vous pourrez à tout moment avant de valider la CSS
pré-visualiser le rendu visuel.
Payzen –
Réussir l’intégration de Payzen
17/18
8. ASSISTANCE TECHNIQUE
Pour tout problème d’accès au back office Payzen, il convient d’utiliser les liens « compte bloqué »
ou « mot de passe oublié » disponible sur la page de connexion du back office Payzen.
Pour toute question technique, vous pouvez nous contacter par téléphone au
Accessible les jours ouvrés du lundi au vendredi de 09h00 à 18h00 (heure légale française).
Tarification de ce numéro: Coût d’un appel local depuis un poste fixe
Payzen –
Réussir l’intégration de Payzen
18/18