Client Web MPay

Le client web MPay est un mini site web à installer sur votre serveur afin de faciliter l'ajout de la fonctionnalité de paiement. Il est disponible sur la page des téléchargements.

Installation

La première chose à faire est de créer une entrée dans votre zone DNS qui fera pointer l'url de votre choix (par exemple mpay.votresite.com) vers l'adresse de votre serveur.

mpay.votresite.com     A      ip.de.votre.serveur     0     86400

L'installation se fait ensuite en décompressant l'archive dans un répertoire accessible à votre serveur web (en général ce sera /var/www/html)

cd /var/www/html
wget https://www.mpay.ytsamy.name/files/mpay-client-0.2.tar.gz  (lien à prendre sur la page téléchargements)
tar zxf mpay-client-0.2.tar.gz
mv mpay-client-02 mpay-client

Exemple de configuration Apache:

<VirtualHost *:80>
	ServerName mpay.votresite.com
	DocumentRoot /var/www/html/mpay-client/web
	<Directory /var/www/html/mpay-client/web>
		AllowOverride All
	</Directory>
</VirtualHost>

Ou, si vous utilisez le SSL:

<VirtualHost *:443>
	ServerName mpay.votresite.com
	DocumentRoot /var/www/html/mpay-client/web
	<Directory /var/www/html/mpay-client/web>
		AllowOverride All
	</Directory>
	... autres options SSL...
</VirtualHost>
Note: il est fortement recommandé d'utiliser la version SSL.

Vérifiez que le serveur web a bien accès aux fichiers (notez que les deux répertoires runtime/ et web/assets/ doivent être accessibles en lecture et en écriture :

cd mpay-client
find -type d -exec chmod go+rx {} \;
find -type f -exec chmod go+r {} \;
sudo chgrp apache runtime/ web/assets/
chmod 775 runtime/ web/assets/

Vous pouvez exécuter le script requirements.php à la racine du répertoire (directement en ligne de commande ou en passant par votre navigateur) afin de vérifier que les prérequis sont satisfaits.

Configuration

  1. Renseigner les paramètres d'accès à votre base de données dans config/db.php
  2. Indiquer votre clé d'accès à l'API MPay dans config/secret.php
  3. Personnalisez les options du fichier config/constants.php (le fichier contient des commentaires pour vous guider).
    Note: la constante CLE_VALIDATION_COOKIES doit obligatoirement être renseigné (mais vous pouvez y mettre une chaîne quelconque, genre 'macleDeVaLidat10n').
  4. Créez les différentes tables dans la base de données en tapant la commande
    ./yii migrate

    Le client MPay crée 3 tables dans votre base de données:

    • mpay_client_paiement: cette table contient les informations des paiements. Les champs sont peu ou prou les mêmes que ceux utilisés par l'API Mpay (cf «Détails d'une opération»)
    • mpay_client_queue: cette table est utilisée pour le système de queue afin de gérer de manière asynchrone les accès à l'API
    • mpay_client_migration: cette table assure le suivi des évolutions des deux autres table, dans le cas d'une migration vers une version supérieure.

    Le préfixe mpay_client_ peut être modifié dans le fichier config/constants.php.

Utilisation

Schéma 1

Lorsque vous souhaitez qu'un de vos utilisateurs fasse un paiement, envoyez-le sur le module client MPay en precisant dans la query string les paramètres amount (le montant à payer) et return_url (l'url à laquelle l'utilisateur devra être renvoyé par la suite). Le fichier config/constants.php permet de définir des valeurs par défaut pour ces deux paramètres.

Exemple: pour un montant de 800F et https://www.votresite.com/payment/success?id=%ID% comme url de retour, la valeur encodée est obtenue comme suit (en PHP):

<?php
$query_string=http_build_query(
	[
		'amount' => '800',
		'return_url' => 'https://www.votresite.com/payment/success?id=%ID%'
	]
);
?>
<p>effectuer le <a href="https://mpay.votresite.com/?<?= $query_string ?>">paiement</a>.</p>

ce qui donne comme https://mpay.votresite.com/?amount=800&return_url=https%3A%2F%2Fwww.votresite.com%2Fpayment%2Fsuccess%3Fid%3D%25ID%25 comme url pour le paiement.

Une mesure (simpliste) de sécurité: la query string peut être encodée en base 64; la chaine résultante est placé dans le paramètre enc de la query string.

<?php
$query_string=base64_encode(
	http_build_query(
		[
			'amount' => '800',
			'return_url' => 'https://www.votresite.com/payment/success?id=%ID%'
		]
	)
);
?>
<p>effectuer le <a href="https://mpay.votresite.com/?enc=<?= $query_string ?>">paiement</a>.</p>

Ce qui donne comme url: https://mpay.votresite.com/?enc=YW1vdW50PTgwMCZyZXR1cm5fdXJsPWh0dHBzJTNBJTJGJTJGd3d3LnZvdHJlc2l0ZS5jb20lMkZwYXltZW50JTJGc3VjY2VzcyUzRmlkJTNEJTI1SUQlMjU=

Enfin, si vous utilisez le framework Yii (qui est à la base du client MPay), vous pouvez facilement user de cryptage comme moyen (un peu moins simpliste) d'assurer la sécurité des données transférées entre votre site web et le client MPay. Pour ce faire, définissez une clé de hashage HASH_KEY dans le fichier config/secret.php. Ensuite, dans votre site web, utilisez le code suivant:

<?php
$query_string=http_build_query(
	[
		'amount' => '800',
		'return_url' => 'https://www.votresite.com/payment/success?id=%ID%'
	]
);
if(defined('HASH_KEY'))
        $query_string=Yii::$app->getSecurity()->hashData($query_string,HASH_KEY);
$query_string=base64_encode($query_string);
?>
<p>effectuer le <a href="https://mpay.votresite.com/?enc=<?= $query_string ?>">paiement</a>.</p>

Il va de soi que vous aurez défini la constante HASH_KEY à la même valeur à la fois dans votre site web et dans le client MPay.

Le client MPay apparaît à l'utilisateur sous la forme suivante (et peut être personnalisé en modifiant les fichiers views/site/index.php et views/layout/main.php):

  • «Votre application», dans le coin supérieur gauche, renvoie à votre site.
  • Le bouton orange «Retour» renvoie à RETURN_URL, défini plus haut.
  • Et si le paiement est effectif, le bouton «Envoyer« renverra l'utilisateur à votre RETURN_URL, mais avec en plus un paramètre id qui contient l'identifiant de l'enregistrement dans la table mpay_client_paiement.

A vous à présent d'utiliser votre logique interne pour d'abord vérifier que le montant reçu correspond à celui qui était attendu (comme indiqué plus haut, la sécurité est simpliste et n'arrêtera pas un utilisateur averti), et ensuite associer ce paiement à un utilisateur donné.

Schéma 2

Dans ce second schéma, c'est le serveur MPay qui se connecte au client web (sur votre site) pour le notifier que vous avez reçu un paiement, et le client rapatrie les informations dudit paiement. Étant donné que dans ce second schéma, l'utilisateur ne passe pas au préalable sur votre site pour choisir un produit, cela sous-entend que vous êtes en mesure de déterminer l'objet de l'achat à partir uniquement du montant (cas d'un abonnement par exemple).

  • La première chose à faire est de renseigner le paramètre «Url de rappel» sur la page d'informations de votre compte en mettant l'url suivante: https://mpay.votresite.com/incoming?id=%ID%.

  • Ensuite, sur votre serveur web, il faut créer et démarrer le service de mpay-client-yii-queue dont la définition est fournie dans le fichier files/mpay-client-yii-queue.service:
    sudo install -o root -m 600 files/mpay-client-yii-queue.service /usr/lib/systemd/system/
    systemctl start mpay-client-yii-queue
    systemctl enable mpay-client-yii-queue

    Note: ces commandes s'appliquent à un système Fedora Linux avec Systemd; veillez à les adapter si vous êtes sur une distribution différente (en particulier Ubuntu).

  • Enfin, vérifiez que vous avez bien renseigné le paramètre SERVICE_RETURN_URL dans le fichier config/constants.php. Ex: https://www.votresite.com/paiement/success?recordId=%ID%.

Dès que le serveur MPay enregistre un paiement, celui-ci est répercuté sur la base de données de votre site (avec un statut Pending, tandis que l'enregistrement côté serveur est mis à OK). Ensuite, l'url SERVICE_RETURN_URL est invoquée (via la méthode HEAD, avec, en query string, l'identifiant de l'enregistrement qui vient d'être créé) pour vous permettre d'effectuer vos traitements: vérification du montant, association à un utilisateur donné (à partir du numéro de l'expéditeur), correspondance avec vos produits,...