La solution Paybox System

Appel de la page de paiement

Pour afficher la page de paiement au client qui souhaite payer sur le site Marchand, il suffit d’envoyer à l’URL de Paybox System une requête HTTPS avec un certain nombre de variables.

PRÉPARATION DU MESSAGE
Les variables suivantes sont obligatoires dans toute requête :

•    PBX_SITE = Numéro de site (fourni par Paybox)
•    PBX_RANG = Numéro de rang (fourni par Paybox)
•    PBX_IDENTIFIANT = Identifiant interne (fourni par Paybox)
•    PBX_TOTAL = Montant total de la transaction
•    PBX_DEVISE = Devise de la transaction
•    PBX_CMD = Référence commande côté commerçant
•    PBX_PORTEUR = Adresse E-mail de l’acheteur
•    PBX_RETOUR = Liste des variables à retourner par Paybox
•    PBX_HASH = Type d’algorithme de hachage pour le calcul de l’empreinte
•    PBX_TIME = Horodatage de la transaction
•    PBX_HMAC = Signature calculée avec la clé secrète

La signification de ces différentes variables ainsi que des variables optionnelles est disponible dans la partie dictionnaire des données.
L’ensemble de ces variables doit être envoyé par la méthode http POST à l’un de nos serveurs de paiement.
Pour transmettre les variables, vous pouvez utiliser un formulaire comme celui-ci (à titre d’exemple, en pré-production) :

Ainsi, le seul élément visible sur la page sera un bouton « Envoyer ». Quand le client cliquera dessus, il sera automatiquement redirigé vers la page de paiement de Paybox System.

Le paiement sera de 1000 centimes d’euros (soit 10 €) et l’identification du paiement par rapport à la commande du commerçant sera la référence  « TEST Paybox ».
Une fois le paiement effectué, si ce dernier est accepté, un ticket de paiement sera envoyé par mail au commerçant ainsi qu’au client à « client@test.com ».
L’identification du commerçant (site 1999888, rang 32 et identifiant 2) correspond à la boutique de test Paybox, accessible sur notre environnement de pré-production.
Des informations complémentaires concernant les conditions de test sur notre environnement de pré-production sont disponibles au chapitre Jeux de tests.
L’exemple ci-dessus fait référence à une URL du serveur de pré-production. Les URLs de pré-production et production sont définies au chapitre Les plateformes de test.

Forçage du moyen de paiement

Si le commerçant préfère se charger lui-même du choix du moyen de paiement, il est possible de fournir directement à l’appel de Paybox System l’information du moyen de paiement choisi. Ceci se fait par l’intermédiaire des variables PBX_TYPEPAIEMENT et PBX_TYPECARTE.
Ainsi, le client sera redirigé directement sur la page de paiement adaptée au moyen de paiement choisi, et ne verra donc pas la page de présélection du moyen de paiement Paybox System.
Exemple : Pour un paiement avec une carte CB classique, il faut documenter PBX_TYPEPAIEMENT à « CARTE » et PBX_TYPECARTE à « CB ».
L’ensemble des valeurs possibles pour ces variables est disponible dans le dictionnaire des données.

Attention : Les 2 variables PBX_TYPEPAIEMENT et PBX_TYPECARTE doivent obligatoirement fonctionner conjointement et l’utilisation de l’une sans l’autre ou bien une valorisation non conforme à ce qui est indiqué dans ce manuel technique peut amener des risques d’erreurs d’accès à la page de paiement ou des comportements non attendus lors de la phase de paiement.

Authentification du message par empreinte

Afin de sécuriser le paiement, c’est-à-dire assurer que c’est bien le commerçant qui en est à l’origine et que personne de malveillant n’a modifié une variable (le montant par exemple), Paybox a choisi d’établir une authentification par empreinte HMAC de l’ensemble des paramètres transmis.

• Étape 0 : Si ce n’est pas déjà fait, le commerçant doit générer une clé secrète via l’accès Back-Office commerçant. Voir Gestion de la clé d’authentification.
• Étape 1 : il faut ensuite, lors de la création d’un message à destination des serveurs de Paybox, concaténer l’ensemble des variables en séparant chaque variable par le symbole « & ». Pour le message ci-dessus, il faut donc se baser sur la chaine suivante :

•  Étape2 : il est alors possible de lancer le calcul de l’empreinte HMAC en utilisant

• La chaine qui vient d’être construite
• La clé secrète obtenue via le Back Office
• Un algorithme au choix (cf. PBX_HASH dans le dictionnaire des données)

• Étape 3 : le résultat obtenu (l’empreinte) doit alors être placé dans le champ PBX_HMAC de la requête.

L’ordre dans la chaine à hasher doit être strictement identique à l’ordre des variables dans le formulaire.
Dans la chaine à hasher, il faut utiliser les données « brutes », c’est-à-dire ne pas utiliser les fonctions d’encodage URL.

Voici un exemple de code PHP permettant de calculer l’empreinte du message :

Attention : Si vous utilisez déjà l’ancienne méthode de communication avec Paybox (par module CGI sur le serveur marchand), le premier appel HMAC bloquera les paiements par l’ancienne méthode sur la plateforme appelée (Utiliser l’authentification HMAC en pré-production, n’affectera pas votre production).

Url appelée

La liste des URLs des serveurs Paybox est détaillée au paragraphe URLs d’appels et adresses IP.
En cas d’indisponibilité de cette URL, des URLs de secours sont disponibles. Il est de la responsabilité du site Marchand de vérifier la disponibilité d’une URL avant de rediriger le client.
Il est possible de tester la disponibilité des serveurs en essayant d’accéder à une page HTML « load.htm ». Cette page contient uniquement la chaîne « OK » qui confirme que le serveur est accessible.
Ci-dessous un exemple de code PHP pour tester la disponibilité des serveurs Paybox (attention les URLs indiquées dans l’exemple sont factices, elles sont à remplacer par les vraies URLs de production) :