Client Web MPay

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

Installation

L'installation se fait 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.1.tar.gz  (lien à prendre sur la page téléchargements)
tar zxf mpay-client-0.1.tar.gz
mv mpay-client-01 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>
	...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 'macleDeVaLidat0n').
  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 à insérer sur une page de votre site (pour un montant de 800F et https://www.votresite.com/payment/success?id=%ID% comme url de retour):

<p>effectuer le <a href="https://mpay.votresite.com/?amount=800&return_url=https%3A%2F%2Fwww.votresite.com%2Fpayment%2Fsuccess%3Fid%3D%25ID%25">paiement</a>.</p>

La page qui apparaît à l'utilisateur peut-être personnalisée 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, 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,...