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.

Attention: le client MPay requiert une mise en œuvre plutôt complexe et ne sert réellement que si vous avez des besoins avancés. Considérez l'utilisation du client hébergé, ne serait-ce que pour un début.

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.4.tar.gz  (lien à prendre sur la page téléchargements)
tar zxf mpay-client-0.4.tar.gz

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.
    Si vous souhaitez pouvoir vous assurer de l'intégrité des données que vous aurez passées de votre site vers le client MPay, créez une paire de clés (publique/privée). Vous utiliserez la clé publique sur votre site au moment d'appeler le client MPay. Et dans le client MPay, indiquez, toujours dans config/secret.php, votre clé privée afin que le client MPay puisse vérifier les données transmises.
  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 précisant dans la query string les paramètres du paiement. Le fichier config/constants.php du client MPay permet de définir des valeurs par défaut que vous n'aurez plus à préciser lors de l'invocation.

<?php
$params=http_build_query([
      'amount' => 800,
      'description' => 'nom article',
      'return_url' => 'https://www.votresite.com/payment/success?id=%ID%',
      'number_orange' => NUMBER_ORANGE,
      'number_telmob' => NUMBER_TELMOB,
      'shop_name' => NOM_BOUTIQUE,
      'logo_url' => PAIEMENT_LOGO_URL,
      // 'immutableRowIds' => [id1, id2],
    ]);
    $sum=hash('sha256',$params);
    if(defined('PUBLIC_KEY')) {
      while ($msg = openssl_error_string()) {};
      $sumTmp=$sum;
      $rv=openssl_public_encrypt($sumTmp, $sum, PUBLIC_KEY);
      $str="";
      while ($msg = openssl_error_string())
        $str.=$msg . "\n";
      // if($str) print_r($str);
    }
    $query_string = http_build_query(array('enc' => base64_encode($params), 'sum' => base64_encode($sum), 'id' => base64_encode(MPAY_USER_ID)));
?>
<p>effectuer le <a href=<?= "\"https://mpay.votresite.com?" . $query_string . "\""?>">paiement</a>.</p>

Les paramètres à fournir sont les suivants:

  • amount: le montant à payer. Ce peut être un entier ou un tableau (s'il y a plusieurs possibilités) 
    [
  [
      'label' => '1 mois',
      'montant' => 200,
  ],
  [
      'label' => '6 mois',
      'montant' => 1100,
  ],
  [
      'label' => '1 an',
      'montant' => 2000,
  ],
]
  • description: le nom de l'article à payer
  • return_url: l'url vers laquelle renvoyer l'utilisateur si le paiement est effectif. Au moment de rediriger l’utilisateur, les substitutions suivantes sont faites:
    • %ID% est remplacé par l’identifiant de l’enregistrement dans la table mpay_client_paiement
    • %TRANSACTION_ID% est remplacé par l’identifiant du transfert tel qu’indiqué dans le SMS de confirmation de l’opérateur
    • %AMOUNT% est remplacé par le montant du transfert.
  • number_orange et number_telmob: les numéros de téléphone Orange et Telmob sur lesquels l'argent du paiement doit être envoyé
  • shop_name: le nom de votre boutique / site web
  • logo_url: l'url d'un logo (au format 32x32 pixels) à afficher en regard du nom de votre boutique
  • immutableRowIds: si vous avez créé des codes promos (sous forme de transfert avec entre autre, identifiant de transfert) qui peuvent être utilisés par plusieurs personnes, une fois le paiement fait, les enregistrements doivent rester au statut 'Pending' au lieu de passer à 'OK'. Ce paramètre vous permet d'indiquer les identifiants des enregistrements correspondants auxdits codes promos.

La constante PUBLIC_KEY sert à chiffrer la somme de contrôle avant envoi afin de s'assurer qu'un petit malin n'a pas modifié les informations de vérification du paiement. Elle doit être initialisée avec votre clé publique (disponible sur la page d'informations de votre compte). Quant à la constante MPAY_USER_ID, il s'agit de l'identifiant (attention!, l'identifiant, et non l'adresse mail) de votre compte MPay (également disponible sur la page d'informations de votre compte).

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, après avoir effectué les substitutions (%AMOUNT%, %ID%, %TRANSACTION_ID%) et mis l'enregistrement au statut 'OK' sur le serveur MPay.

A vous à présent d'utiliser votre logique interne pour d'abord vérifier que le montant reçu correspond à celui qui était attendu (mesure supplémentaire de sécurité), 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,...