Réussir l’intégration de Payzen Paiement par formulaire · 2014. 4. 2. · Payzen – Réussir...

Payzen –

Réussir l’intégration de Payzen 1/18

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 –


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 –


1. PRINCIPE GENERAL

BOUTIQUE PAYZEN

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.

Etape 1: Formulaire de paiement (https)

Etape 2: Appel Url serveur

Etape 3: Retour à la boutique

Payzen –


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

https://secure.payzen.eu/vads-payment/

http://www.payzen.eu/support.php

Payzen –


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 –


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 –


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 –


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é.

vads_trans_status

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é.

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é.

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é.

vads_auth_result

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

vads_auth_mode

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.

vads_trans_id Valorisé à l’identique à la valeur reçue dans le formulaire de paiement

signature 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 –


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 Ne pas tenir compte de cette réponse ou vérifier que le calcul

de signature est correct.

Contrôle du type de la transaction

vads_operation_type CREDIT

NON

OUI

DEBIT

La transaction est un débit ayant comme caractéristique :

Statut : vads_trans_status

Résultat : vads_result

Identifiant : vads_trans_id

Montant : vads_amount

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

La transaction est un remboursement ayant comme

caractéristique :

Statut : vads_trans_status

Montant : vads_amount

Identifiant : vads_trans_id

Payzen –


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 –


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 les paramètres sont renvoyés en mode GET.

POST les paramètres sont renvoyés en mode POST (non recommandé).

NONE aucun paramètre n’est envoyé.


Payzen –


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 –


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 –


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, VISA-

ELECTRON).

Une fois tous les tests validés, vous pourrez cliquer sur le bouton Générer le certificat de production.

Payzen –


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 –


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.

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. vads_action_mode

2. vads_amount

3. vads_ctx_mode

4. vads_currency

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.

Payzen –


5. vads_page_action

6. vads_payment_config

7. vads_site_id

8. vads_trans_date

9. vads_trans_id

10. 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 –


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

Réussir l’intégration de Payzen Paiement par formulaire · 2014. 4. 2. · Payzen – Réussir...

Documents

Transcript of Réussir l’intégration de Payzen Paiement par formulaire · 2014. 4. 2. · Payzen – Réussir...