Réussir l’intégration de Systempay · 2015. 10. 28. · Descriptif de l’interface vers la page de paiement ©Lyra Network- 1/13 1 PRINCIPE GENERAL L’implémentation technique

Guide d’implémentation

- Interface avec la plateforme de paiement -

Réussir l’intégration de Systempay

Version 1.4

Rédaction, Vérification, Approbation

Rédaction Vérification Approbation

Nom Date/Visa Nom Date/Visa Nom Date/Visa

Lyra-Network 27/12/2012 Lyra-Network 27/12/2012 Lyra-Network 27/12/2012

Version Auteur Date Commentaires

1.4 Lyra-Network 27/12/2012 Mise à jour



1.0 Lyra-Network 01/07/2011 Création

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.

Historique du document

SOMMAIRE

1 PRINCIPE GENERAL ............................................................................................................................... 1

2 ETAPE 1 : ENVOYER UN FORMULAIRE DE PAIEMENT EN POST ............................................. 2

3 ETAPE 2 : ANALYSER LE FORMULAIRE URL SERVEUR EN POST ........................................... 3

3.1 NOTIONS D’URL SERVEUR .......................................................................................................................... 3 3.2 URL SERVEUR ETENDUE ........................................................................................................................... 4 3.3 EXTRAIT DES PARAMETRES RENVOYES ...................................................................................................... 4 3.4 ANALYSE D’UN PAIEMENT ......................................................................................................................... 5 3.5 COMMENT VISUALISER L’APPEL A L’URL SERVEUR .................................................................................. 6 3.6 NON SYNCHRONISATION DES PAIEMENTS DES PAIEMENTS SUR LE SITE MARCHAND .................................. 6

4 ETAPE 3 : LE RETOUR A LA BOUTIQUE (FACULTATIF) .............................................................. 7

5 PHASE DE TEST ........................................................................................................................................ 8

5.1 TESTS DE PAIEMENT .................................................................................................................................. 8 5.2 VERIFIER LE BON FONCTIONNEMENT DE L’URL SERVEUR .......................................................................... 8 5.3 GENERATION DU CERTIFICAT DE PRODUCTION .......................................................................................... 9

6 PASSAGE EN PRODUCTION ................................................................................................................ 10

7 ANNEXES .................................................................................................................................................. 11

7.1 CALCUL DE LA SIGNATURE ...................................................................................................................... 11 7.2 CERTIFICAT DE TEST .............................................................................................................................. 12 7.3 CERTIFICAT DE PRODUCTION .................................................................................................................. 12 7.4 PERSONNALISATION DE LA PAGE DE PAIEMENT ....................................................................................... 12

8 ASSISTANCE TECHNIQUE ................................................................................................................... 13

Descriptif de l’interface vers la page de paiement

©Lyra Network- 1/13

1 PRINCIPE GENERAL

L’implémentation technique se résume à 3 étapes.

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

BOUTIQUE SYSTEMPAY



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://paiement.systempay.fr/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_transdate 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

Pour plus d’informations sur les différents paramètres disponibles lors de l’envoi du formulaire

vous pouvez vous référer au guide d’implémentation du formulaire de paiement, disponible

depuis votre outil de gestion de caisse (Menu : Aide/Documentations)

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. (Menu : Paramétrage/Boutiques/[Nom de la

boutique]/Certificat)

Pour plus d’information sur le calcul de la signature se reporter au chapitre Annexes ou au

guide d’implémentation du formulaire de paiement

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://paiement.systempay.fr/vads-payment/">

</FRAMESET>

<iframe src="https://paiement.systempay.fr/vads-payment/"></iframe>

https://systempay.cyberpluspaiement.com/vads-payment/



3 Etape 2 : Analyser le formulaire URL serveur en POST

3.1 Notions d’url serveur

L’URL serveur est le seul mécanisme à implémenter

pour synchroniser automatiquement le site de paiement

et votre site marchand.

A la fin d’un paiement, la plateforme de paiement appelle systématiquement l’url serveur

renseignée dans le back-office marchand.

Cet appel a pour but d’informer le site marchand de l’état du paiement (même si le client

ne revient pas sur le site).

Le marchand pourra ainsi valider sa commande si le paiement est accepté.

L’appel est une requête HTTP ou en HTTPS contenant un POST dans lequel sont

valorisés des paramètres permettant l’analyse du paiement (accepté ou refusé

etc…).

L’url serveur (en mode TEST ou PRODUCTION) doit être renseignée dans le back office

marchand. (Onglet Paramétrage /Boutique/[Nom de la boutique]/Configuration)

Remarque importantes

Cette URL est toujours appelée avec un formulaire HTTP POST, et ce quelque soit la valeur

du paramètre vads_return_mode.

L’url serveur est le seul mécanisme qui doit permettre le lancement des tâches

dépendantes du paiement. (Mise à jour du statut de la commande dans votre back

office boutique, envoie d’email, déstockage produit etc …)

En cas d’échec de l’appel de l’url serveur, la plateforme de paiement envoie un mail à

l’administrateur de la boutique avec la raison de l’échec (erreur http etc …) Vous pourrez

alors rejouer l’url serveur depuis le back office de la solution de paiement.

Attention : l’URL serveur peut être appelée plusieurs fois, il est donc nécessaire que votre

implémentation prenne cela en considération.



3.2 URL serveur étendue

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

3.3 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 au guide

d’implémentation du formulaire de paiement.



3.4 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 Systempay 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



3.5 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

3.6 Non synchronisation des paiements 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.



4 Etape 3 : le retour à 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).Le détail est fourni dans le guide du retour

automatique à boutique, disponible depuis le Menu Aide/Documentation de l’outil de

gestion de caisse.

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.

cf. 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é (valeur par défaut)



5 Phase de Test

5.1 Tests 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 les champs de saisie de la page de

paiement et ensuite cliquer sur "Valider".

5.2 Vérifier le bon fonctionnement de l’url serveur

A la fin du paiement, vérifier que l’appel à l’url serveur en mode test a fonctionné correctement et

que par conséquent votre système d’information s’est mis à jour correctement.

En cas de problème dans la réception des informations sur votre URL serveur, vous pouvez consulter

l’historique d’une transaction. Double cliquez sur une transaction pour faire apparaitre la fenêtre de

détail. Allez dans l’onglet Historique et recherchez la ligne Appel URL serveur.

La colonne Info. contient le résultat de l’appel (SENT ou FAILED) ainsi que la réponse affichée par

votre script si cela est prévu dans votre code.



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.



6 Passage en production Pour paramétrer votre boutique en mode production vous devez effectuer les 5 étapes

suivantes :

1. Terminer la phase de test et générer le certificat de production.

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

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.



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 :

- vads_action_mode

- vads_amount

- vads_ctx_mode

- vads_currency

- 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+1122

334455667788

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 de test.

Il est disponible dans le back office Systempay (Menu : Paramétrage /Boutiques /[Nom de la

boutique]/Certificats).

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.

Il est disponible dans le back office Systempay (Menu : Paramétrage /Boutiques /[Nom de la

boutique]/Certificats). Pour des raisons de sécurité, il ne sera plus visible dès lors que vous

aurez finalisé un paiement réel via le formulaire.

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.

Dans le calcul de la signature, l’ordre alphabétique des paramètres doit être

respecté.

La signature n’est pas la chaîne obtenue après concaténation mais la

résultante de l’algorithme SHA1 appliqué à la chaîne obtenue.



8 ASSISTANCE TECHNIQUE

Pour toute question technique, vous pouvez nous contacter par téléphone au :

0811 363 364 pour les clients banque populaire

0810 004 724 pour les clients Caisse d’épargne

(Numéro Azur – Coût d’un appel local depuis un poste fixe) les jours ouvrés du lundi

au vendredi de 09h00 à 18h00 (heure légale française).

Documents

Réussir l’intégration de Systempay · 2015. 10. 28. · Descriptif de l’interface vers la page de paiement ©Lyra Network- 1/13 1 PRINCIPE GENERAL L’implémentation technique