La solution Paybox System

Gestion de la réponse

Une fois le paiement réalisé sur la page de paiement Paybox, le client a la possibilité de revenir sur le site commerçant par l’intermédiaire de 4 URLs.
Le commerçant pourra gérer de façon automatique la validation de ses bons de commandes suivant le résultat de la transaction par l’intermédiaire d’une 5ème URL nommée IPN (Instant Payment Notification).

Redirection du client

Le retour de Paybox System vers le site marchand peut se faire sur 4 adresses (URLs) différentes selon si le paiement est accepté, refusé, annulé ou en attente. Ces 4 adresses peuvent se définir de 2 manières :

  • Soit en les définissant pour chaque transaction,
  • Cela permet d’afficher une page personnalisée pour chaque client.
  • Il faut alors les définir à chaque transaction en utilisant les variables PBX_EFFECTUE, PBX_REFUSE, PBX_ANNULE, PBX_ATTENTE.
  • Soit en utilisant les valeurs par défaut enregistrées dans la base de données Paybox
  • Ces valeurs doivent être données lors de l’inscription à Paybox System. Il est également possible de les modifier via l’accès Back Office du Commerçant, onglet [Informations].

Le client sera dirigé sur une de ces pages après avoir cliqué sur le bouton “retour boutique” de la page récapitulative du paiement (phase d’affichage du ticket de paiement), ou de la page indiquant que la transaction n’a pas été autorisée.
Il est également possible de choisir un retour immédiat : il faut préciser cette option dans  le dossier d’adhésion ou auprès du support technique Paybox. Dans ce cas-là, le ticket récapitulatif n’est pas affiché et le client est redirigé directement vers le site du commerçant.

Il est fortement déconseillé d’utiliser exclusivement la variable “PBX_EFFECTUE” pour valider les bons de commandes du site Marchand : cette variable n’est pas sécurisée par Paybox et n’est pas garantie comme étant lancée systématiquement. En effet, un acheteur qui a réalisé son paiement peut ne pas vouloir revenir sur le site ou couper sa connexion.
Pour plus de précisions, voir ci-dessous Validation des bons de commande.

En cas de présence dans l’URL à appeler de caractères HTML spéciaux, il faut les « URL Encoder », c’est-à-dire les convertir en un code spécial compatible avec l’encodage d’une URL.
Par exemple, si l’URL “PBX_EFFECTUE” contient le caractère « ; », il faut remplacer ce caractère par « %3B » :
www.commerce.fr/effectue.jsp;id_session=134ERF47
Il faudra donc documenter la variable « PBX_EFFECTUE » de la manière suivante :
www.commerce.fr/effectue.jsp%3Bid_session=134ERF47
Cette restriction s’appelle l’URL Encodage et est due à la gestion de la balise META HTTP-EQUIV pour Internet Explorer.
Pour connaitre leur valeur convertie « URL Encodée » des caractères spéciaux : www.url-encode-decode.com . Sélectionner ISO-8859-1.

Gestion des paiements en attente de validation

Certains moyens de paiement (exemples : Paypal, Oney-Facilipay, iDeal) peuvent nécessiter un délai de quelques heures à quelques jours avant de confirmer le paiement.
Pour vous informer de la situation, Paybox vous envoie une première réponse dès la fin du paiement par le client avec le code réponse 99999 sur l’URL PBX_ATTENTE et via l’IPN.
Paybox se charge ensuite de mettre à jour la réponse, et quand une décision a été prise, Paybox vous rappelle via l’IPN avec la réponse définitive (ex : 00000 si la transaction est autorisée).
Pour plus d’informations sur ces moyens de paiement, vous pouvez vous référer aux documents :

 

Validation des bons de commande

Principe du IPN (Instant Payment Notification)
Ce paramètre IPN est spécialement utilisé pour gérer de façon automatique la validation des bons de commandes.
Ce paramètre est une URL enregistrée dans la base de données Paybox mais elle peut également être gérée dynamiquement comme les 4 URLs précédentes via la variable “PBX_REPONDRE_A”.
L’avantage de cette URL est qu’elle est appelée de serveur à serveur dès que le client valide son paiement (que ce dernier soit autorisé ou refusé).
Cela permet ainsi de valider automatiquement le bon de commande correspondant même si le client coupe la connexion ou décide de ne pas revenir sur la boutique, car cet appel ne transite pas par le navigateur du porteur de carte.
Lors de l’appel de cette URL, un script présent sur le serveur Marchand à l’emplacement spécifié par l’URL va s’exécuter. Il n’y a pas de contrainte sur le langage de ce script (ASP, PHP, PERL, …). La seule limitation est que ce script ne doit pas faire de redirection et doit générer une page HTML vide.
L’URL précisée dans le paramètre IPN est appelée à chaque tentative de paiement, quel que soit le nombre de tentatives effectuées par le porteur.
Cette URL n’a aucun lien direct avec les trois autres : elle est gérée de façon complètement indépendante et peut être appelée sur les ports TCP 80, 443 (HTTPS), 8080, 8081, 8082, 8083, 8084 ou 8085.

Paramètres
Il est possible de configurer la liste des variables qui sont renvoyées au site Marchand dans les différentes URLs de retour. Cette configuration est effectuée par la variable PBX_RETOUR, qui se configure en concaténant la liste des informations souhaitées sous le format suivant :

Exemple :

Le nom des variables (montant, maref,…) est personnalisable. Pour voir l’ensemble des données disponibles, consultez le dictionnaire des données.
Ces informations seront envoyées à toutes les URLs de retour (PBX_EFFECTUE, PBX_ANNULE, PBX_REFUSE, PBX_ATTENTE et PBX_REPONDRE_A). Par exemple, pour l’URL IPN, avec la valeur citée ci-dessus, la page appelée serait :

Cet appel est par défaut effectué via la méthode « GET ». Si la méthode « POST » est préférée pour le transfert des paramètres, il faut l’indiquer dans la variable PBX_RUF1.

Gestion des erreurs
Si une erreur se produit lors de l’appel de l’URL IPN, un mail d’avertissement sera envoyé au commerçant  sur l’adresse mail enregistrée pour l’envoi des tickets de paiements. Par exemple, si l’URL d’appel est :

Le message d’erreur reçu sera le suivant :

A la fin de ce message sont précisées entre parenthèses (XXX-YYY) des informations permettant de comprendre la cause de l’erreur :

  • Le premier nombre XXX correspond au code retour du protocole HTTP
  • Voir la liste des codes retour HTTP
  • Seuls les codes retour commençant par un 2 sont considérés comme valides.
  • Le second YYY correspond au code retour de la librairie “libcurl” assurant les échanges avec le serveur WEB Marchand.

Vérification des valeurs
L’IPN est appelée quel que soit le résultat du paiement (accepté ou refusé).
Comme tous les messages et signatures transportés au moyen du protocole HTTP (GET ou POST), l’IPN est sur-encodés (URL encodage et/ou Base64).
Il faut donc URL décoder le message transmis.
Pour connaître le résultat du paiement, il est indispensable de vérifier le contenu des variables suivantes :

  • Numéro d’autorisation (A) : alphanumérique, longueur variable.
  • Pour une transaction de test (pas de demande d’autorisation vers le serveur de la banque ou l’établissement financier privatif), la variable vaut toujours « XXXXXX »

Pour une transaction refusée, la variable n’est pas envoyée :

Pour s’assurer que la réponse provient bien de Paybox, il est fortement conseillé de vérifier le contenu de la variable suivante :

  • Signature Paybox (K) : Voir paragraphe ci-dessous
  • Adresse IP d’origine :
  • Pour améliorer la sécurité, il est possible de vérifier que l’appel de l’ URL IPN provient bien d’un des serveurs Paybox. Voir URLs d’appel et Adresses IP.

Il vous faudra alors vérifier impérativement le numéro d‘autorisation, le code erreur, le montant et la signature électronique : si le numéro d’autorisation existe (dans l’exemple précédent il est égal à 30258), que le code erreur est égal à « 00000 », que le montant est identique au montant d’origine et que la signature électronique est vérifiée, cela signifie que le paiement est accepté.
Dans le cas d’un paiement refusé par le centre d’autorisation (code erreur à 001xx), les « xx » représentent le code renvoyé par le centre. Ce code permet de connaître la raison exacte du rejet de la transaction.
Par exemple, pour une transaction refusée pour raison « provision insuffisante », le code erreur renvoyé sera 00151.
Pour consulter le détail de codes réponses du centre d’autorisation, cliquez-ici.

Signature Paybox
En utilisant la signature Paybox dans les variables à retourner vers les URL du site Marchand, ce dernier peut s’assurer que :

  • les données renvoyées n’ont pas été altérées,
  • c’est bien Paybox qui effectue un appel des URL du site.

Il est important de noter que la donnée K de la variable « PBX_RETOUR » doit toujours être située en dernière position. Par exemple :

  • PBX_RETOUR=montant:M;auto:A;idtrans:S;sign:K est correcte
  • PBX_RETOUR=montant:M;auto:A;sign:K;idtrans:S est incorrecte

Télécharger ici, la clé publique PAYBOX.
Pour être en conformité avec les règles de sécurité, Paybox est susceptible de changer sa paire de clé publique/privée : il doit donc être possible de mettre en place différentes clés publiques au niveau des serveurs Marchand.

Signature Paybox
La signature Paybox est produite en chiffrant un condensé SHA-1 avec une clé privée RSA. La taille d’une empreinte SHA-1 étant de 160 bits et la clé Paybox faisant 1024 bits de long, la signature est toujours une valeur binaire de taille [fixe] 128 octets (172 octets en Base64).

Vérification de la signature
De par sa nature, la signature Paybox peut se vérifier directement dans les langages les plus répandus sur le web.
Par exemple en PHP, il suffit d’utiliser la fonction ‘openssl_verify()’ et en Java, la methode verify() en précisant “SHA1withRSA”.
Il est également possible d’utiliser d’autres langages, packages, composants ou utilitaires, qui peuvent demander de prendre en charge les opérations intermédiaires (condensé ou chiffrement). Dans tous les cas, il faut utiliser la clé publique Paybox, disponible en téléchargement.

Tests
La manière la plus souple de tester un programme de vérification de signature dans votre environnement, est d’utiliser une paire de clé RSA de test.
Vous serez ainsi en mesure de signer vous-même des messages dont vous pourrez vérifier la signature. Ensuite, il suffira de substituer la clé publique de test par la clé publique Paybox.
Exemple avec OpenSSL (http://www.openssl.org/docs/apps/openssl.html) :

Pour générer une clé privée RSA prvkey.pem et en extraire la clé publique pubkey.pem

Signature d’une donnée contenue dans le fichier data.txt

Vérification de la signature en utilisant la clé publique pubkey.pem

Encodage
Les messages et signatures transportés au moyen du protocole HTTP (GET ou POST) doivent être sur-encodés (URL encodage et/ou Base64).
De ce fait il faut procéder aux opérations inverses avant de vérifier la signature :

  1. détacher la signature du message,
  2. URL décoder la signature,
  3. décodage Base64 de la signature,
  4. vérification de la signature [binaire] sur les données (toujours encodées)

Avec l’URL IPN de notification (paramètre PBX_REPONDRE_A), la signature électronique s’effectue uniquement par rapport au contenu de la variable PBX_RETOUR contrairement aux trois autres URL où la signature est calculée sur l’ensemble des variables.
Données signées :

  • lors de la réponse Paybox de serveur à serveur (URL IPN), seules les informations demandées dans la variable PBX_RETOUR sont signées,
  • dans les 4 autres cas (redirection via le navigateur du client, PBX_EFFECTUE, PBX_REFUSE et PBX_ANNULE, PBX_ATTENTE), ce sont toutes les données suivant le ‘ ? ‘ (les paramètres URL).

La signature (df123dsfd3…1f1ffsre%20t321rt1t3e=) porte sur la partie :

  • cas a) pbxparam1=val1&pbxparam2=val2 …
  • cas b) monparam=mavaleur& pbxparam1=val1&pbxparam2=val2 …

Rappel : si la signature n’est pas la dernière valeur demandée dans la liste PBX_RETOUR, les valeurs suivantes seront retournées, mais pas signées.

Signature non vérifiée
Si une signature ne peut être vérifiée, alors les cas suivants doivent être envisagés :

  • Erreur technique : bug, environnement cryptographique mal initialisé ou mal configuré, …
  • Utilisation d’une clé erronée
  • Données altérées ou signature contrefaite

Le dernier cas est peu probable, mais grave. Il doit conduire à la recherche d’une intrusion dans les systèmes d’informations impliqués.