MevvPos Documentation

Installation

MevvPos exige WordPress 6.0+, PHP 8.1+ et WooCommerce 9.0 ou plus récent. WooCommerce est une dépendance stricte, déclarée dans l’en-tête de l’extension : sans lui, WordPress refuse l’activation, et sur les versions plus anciennes de WordPress l’extension ne fait tout simplement rien.

Téléversez l’extension via Extensions → Ajouter → Téléverser une extension et activez-la.
Ouvrez MevvPos dans le menu d’administration de gauche. Il existe aussi un raccourci sous WooCommerce, là où les marchands ont l’habitude de chercher les réglages de paiement.
Dans l’onglet Général, activez le moyen de paiement et définissez le titre que la clientèle verra au moment de la commande.
Dans API de la banque, choisissez votre banque et saisissez les identifiants qu’elle vous a fournis.
Dans Mensualités et commission, saisissez vos taux de mensualités.
Testez avec les identifiants de test de votre banque avant de passer en production.

L’édition gratuite ne crée aucune table de base de données et n’enregistre aucune tâche planifiée. Tout vit dans les options WordPress et dans les metas de commande.

Pro est une extension distincte, installée à côté de la version gratuite — elle ne la remplace pas. L’extension gratuite est publiée sur WordPress.org, où tout ce qui est publié peut être redistribué sous la GPL ; garder le code payant dans le même paquet l’aurait rendu légalement redistribuable par quiconque aurait supprimé les vérifications de licence. La clé de licence se saisit dans l’onglet Licence.

Ouvrir WooCommerce → Réglages → Paiements → MevvPos vous redirige vers l’écran MevvPos. C’est délibéré : il y a un seul endroit pour ces réglages, pas deux qui pourraient se contredire.

Comment ça marche

Vous définissez un ou plusieurs enregistrements TPE. Un enregistrement TPE est le TPE virtuel d’une banque : ses identifiants, son adresse de passerelle, ses taux de mensualités.
Au moment du paiement, le client saisit sa carte. Les six premiers chiffres — le BIN — identifient la banque qui l’a émise.
MevvPos recherche le BIN et envoie le paiement vers votre TPE auprès de cette banque, si vous en avez un. Sinon, il retombe sur votre TPE par défaut.
Le paiement en plusieurs fois n’est proposé que si la carte appartient à la banque de ce TPE, car les banques n’accordent pas de mensualités sur les cartes d’une autre banque.
Le client passe par 3-D Secure auprès de la banque, et la banque revient vers une adresse de rappel unique sur votre site.
La signature du retour est vérifiée avec la clé du TPE que la commande a réellement utilisé, la commande est finalisée et le résultat est enregistré.

Le numéro de carte, la date d’expiration et le CVV ne sont jamais écrits dans votre base de données ni dans la session WooCommerce. Les seules données de carte conservées sont les six premiers chiffres et le nom de banque reconnu.

Enregistrements TPE

La barre des TPE se place au-dessus des onglets et reste visible sur chacun d’eux. Chaque carte affiche la banque, le numéro de commerçant et un badge quand quelque chose demande votre attention.

Par défaut: Le TPE qui prend le paiement quand aucune meilleure correspondance n’est trouvée. Il y en a toujours exactement un.
Inactif: Conservé mais n’encaissant pas. Utilisez cela plutôt que la suppression quand un TPE est configuré mais pas encore actif chez la banque — sans quoi un client porteur d’une carte de cette banque ne pourrait pas payer.
En attente d’une licence: L’enregistrement existe mais reste en sommeil parce que la licence n’est pas active. Rien n’a été supprimé ; il reprend là où il s’était arrêté au renouvellement de la licence.
Les informations de l’API n’ont pas été saisies: L’enregistrement n’a pas encore de numéro de commerçant.

Les banques sont représentées par une bande de couleur plutôt que par un logo. Les logos bancaires sont des marques déposées, et quinze d’entre eux représentent à la fois un risque juridique et une maintenance permanente — vous savez déjà quelle banque est la vôtre.

Le dernier POS ne peut pas être supprimé et le dernier activé ne peut pas être désactivé. Pour cesser complètement d’accepter les paiements par carte, désactivez plutôt le moyen de paiement dans l’onglet Général.

L’édition gratuite autorise un TPE. Les enregistrements supplémentaires sont une capacité Pro — et par conséquent le routage BIN aussi : avec un seul TPE, il n’y a rien entre quoi router.

API de la banque — identifiants et adresse de la passerelle

Banque: Choisissez la banque auprès de laquelle se trouve votre TPE. L’adresse de la passerelle et la liste de BIN utilisée pour les mensualités découlent toutes deux de ce choix. Les établissements sans implémentation à ce jour sont listés avec « — yakında » et ne peuvent pas être sélectionnés.
Numéro de commerçant (Client ID): Le numéro de commerçant que la banque vous a fourni.
Merchant key (Store key): La clé de sécurité du commerçant. Stockée dans un champ de mot de passe ; une fois enregistrée, elle s’affiche masquée.
Gate URL: L’adresse vers laquelle le formulaire de paiement est envoyé.
Activer le mode test: Arrête la redirection automatique pour que vous puissiez inspecter la requête avant son envoi.

Laisser la Store Key vide au moment d’enregistrer signifie « ne pas la modifier ». Écrire la valeur vide effacerait la clé et votre boutique cesserait d’accepter les paiements sans le moindre message d’erreur. La même règle vaut pour les autres champs secrets.

Certaines familles exigent des identifiants supplémentaires, et le formulaire ne les affiche que pour la banque que vous avez choisie :

Garanti BBVA — Merchant ID, nom d’utilisateur d’autorisation, mot de passe d’autorisation.
VakıfBank — Terminal No, et une adresse MPI (laissez-la vide pour utiliser l’adresse de test).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — pas de champs supplémentaires : la clé d’API va dans le Numéro de commerçant et le secret dans la Merchant key.

Ces identifiants supplémentaires entrent dans la signature. S’il en manque un, la signature est calculée avec une valeur vide et la banque refuse le paiement en silence — pas d’erreur, pas de message, juste un refus.

Pour les sept banques NestPay, l’adresse de la passerelle est renseignée à partir de votre choix de banque : vous pouvez donc laisser Gate URL vide. Pour les autres, le champ n’est pas prérempli : saisissez l’adresse fournie par votre banque ou votre prestataire, sinon le formulaire de paiement n’a nulle part où être envoyé.

Les treize établissements pris en charge

NestPay / Asseco (Payten): İş Bankası, Akbank, Halkbank, QNB, Şekerbank, TEB, Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
Établissements de paiement: iyzico, PayTR, Craftgate, Sipay

Les établissements sans implémentation restent volontairement dans la liste des banques, marqués « — yakında ». Les retirer masquerait quelles familles de protocoles manquent encore. Si la vôtre en fait partie, l’onglet Requête envoyée à la banque est l’endroit pour le dire.

Seule la signature NestPay dispose d’un test à vecteur de référence face à l’exemple publié par la banque elle-même. Tous les autres prestataires sont marqués beta dans leur propre code source : le flux est implémenté conformément à la documentation, mais il n’a pas encore été vérifié de bout en bout avec un compte marchand réel auprès de cet établissement. Cette mention reste tant que ce n’est pas fait.

Les établissements de paiement n’émettent pas de cartes : ils ne portent donc pas de liste de BIN. Vous les sélectionnez comme votre TPE plutôt que d’y router.

Routage basé sur le BIN

Les six premiers chiffres d’une carte identifient la banque qui l’a émise. MevvPos établit la correspondance sur exactement ces six chiffres.

Un instantané de la table des BIN est livré dans l’extension — 1 449 BIN répartis sur 36 banques dans la version actuelle — si bien que le routage fonctionne hors ligne, en édition gratuite, dès l’installation.
Pro la rafraîchit chaque semaine depuis nos serveurs. Le rafraîchissement se superpose à la table livrée plutôt que de la remplacer : une réponse partielle ou vide ne doit jamais laisser une boutique sans aucune donnée BIN.
Une réponse comportant moins de cent BIN est rejetée comme invraisemblable et n’est pas écrite.
Les conflits — un même BIN revendiqué par deux banques — sont résolus de notre côté avant l’envoi de la liste. Une boutique qui les résoudrait localement pourrait compter une carte comme « la nôtre » et la router ailleurs en même temps.

Un BIN non reconnu n’est jamais refusé. Il retombe sur votre TPE par défaut. Écarter une carte que nous n’avons simplement pas en fiche reviendrait à perdre une vente pour protéger une table de correspondance.

La même table répond au moment du paiement à une seconde question, différente : cette carte vient-elle de la banque de ce TPE ? C’est ce qui décide si le paiement en plusieurs fois est proposé — voir plus bas.

L’exactitude des BIN n’est pas une fonctionnalité payante. Ce que Pro achète, c’est la fraîcheur, pas la justesse : la liste livrée est la même liste, simplement figée au moment de la compilation.

Mensualités et commission

Les taux se règlent par POS, du paiement comptant jusqu’à douze mensualités, dans l’onglet Mensualités et commission. Ce sont des pourcentages : écrivez 5.50 pour 5,5 %.

0: L’option est affichée et aucune commission n’est ajoutée.
Vide: L’option n’est pas affichée du tout. Vide et zéro ne sont pas la même chose.

La commission apparaît dans le panier sous la forme d’un frais taxable nommé « N Taksit Komisyonu », calculé sur le total du panier, frais de livraison et taxes compris.

Le paiement en plusieurs fois n’est proposé que sur les cartes émises par la banque de ce TPE, et c’est appliqué côté serveur — pas seulement masqué dans l’interface. Une carte d’une autre banque est ramenée de force à un paiement en une fois et les frais sont annulés.

L’édition gratuite montre au client au maximum trois mensualités ; Pro porte le plafond à douze. Le plafond s’applique à trois endroits : la liste que voit le client, la valeur qui arrive avec le formulaire, et la valeur envoyée à la banque. La dernière compte, car une valeur choisie alors que la licence était encore valide peut survivre dans la session.

Le formulaire de réglages affiche toujours les douze champs, quelle que soit votre licence. S’ils disparaissaient à l’expiration d’une licence, enregistrer la page supprimerait silencieusement des taux que vous aviez déjà saisis. Les champs au-delà de votre plafond sont marqués « Débloqué dans Pro » et vos chiffres sont conservés.

Il n’existe pas de table de mensualités fournie par la banque. Les taux sont ceux que vous saisissez, et la commission d’une commande passée est calculée à partir du taux en vigueur le jour de la vente — modifier un taux aujourd’hui ne réécrit pas le rapport d’hier.

Le flux de paiement et la gestion de la carte

Chaque famille passe par 3-D Secure. Il n’y a pas de mode non-3D ni de réglage pour le désactiver.

Flux par formulaire: NestPay, Garanti, PayTR et Sipay : le navigateur envoie un formulaire signé à la banque, le client s’authentifie, et la banque revient sur votre site.
Flux serveur: VakıfBank, iyzico et Craftgate : votre serveur dialogue avec le prestataire, récupère la page 3-D, l’affiche, et finalise la vente de serveur à serveur après l’authentification.

La banque revient toujours vers une seule adresse sur votre site : ?wc-api=mevvpos_callback. La signature de ce retour est vérifiée avec la clé du TPE que la commande a réellement utilisé, consignée sur la commande elle-même — avec plus d’un TPE, vérifier avec la mauvaise clé produit une erreur de hachage sur chaque paiement.

La carte n’atteint jamais votre base de données. Elle est conservée dans le navigateur le temps de la redirection puis effacée. Si elle n’y est pas au chargement de la page de paiement — un nouvel onglet, un rafraîchissement, un stockage désactivé, un retour arrière depuis la banque —, un formulaire de carte visible est affiché plutôt que d’envoyer des champs vides à la banque. Le formulaire de carte est visible par défaut, à dessein : un parcours de paiement ne peut pas dépendre du fait que JavaScript se soit exécuté.

Quand la banque approuve le paiement, la commande est finalisée même si le code d’état 3-D était inattendu — une note de commande consigne l’anomalie et vous demande de la confirmer depuis l’écran de la banque. Si la banque dit approuvé, le client a été débité ; refuser reviendrait à dire « votre carte a été débitée mais votre commande a échoué ».

Chaque tentative enregistre le TPE utilisé, la banque et le BIN de la carte, le nombre de mensualités et le taux, le résultat, le code de réponse et le message de la banque, ainsi que les références d’autorisation et de transaction.

Rapports

L’onglet Rapports affiche le chiffre d’affaires, les transactions réussies, le taux de réussite et la répartition entre paiement comptant et mensualités, avec un graphique quotidien. Les transactions qui attendent encore la réponse de la banque sont comptées à part et exclues du taux de réussite.

L’édition gratuite fait ses rapports sur une fenêtre fixe de 30 jours. Pro ajoute des plages de 7 / 30 / 90 jours et trois ventilations :

Charge des mensualités et des commissions — nombre, chiffre d’affaires et charge de commission par palier de mensualités.
Ventilation par TPE et par banque — chiffre d’affaires, réussites, échecs et taux de réussite pour chaque TPE et pour chaque banque émettrice.
Répartition des codes de refus — avec export CSV. Un code de refus qui revient pointe vers quelque chose que vous pouvez corriger : un solde insuffisant est le problème du client, mais les erreurs de vérification 3-D et de configuration du TPE sont les vôtres.

Les données derrière les rapports sont collectées par l’extension gratuite : l’historique continue donc de s’accumuler que vous ayez Pro ou non. Il faut qu’il en soit ainsi : les données passées ne peuvent pas être générées rétroactivement au moment de la mise à niveau.

Une boutique fraîchement installée n’a pas de graphique. L’enregistrement commence avec l’extension, et l’écran se remplit après la première tentative de paiement.

Demandes bancaires et assistance

Requête envoyée à la banque: Liste chaque établissement pas encore implémenté, avec la raison : soit la famille de protocoles n’a pas été déterminée, soit la famille est connue et nous attendons la documentation. Vous pouvez ouvrir une demande pour l’un d’eux, ou nommer un établissement qui ne figure pas du tout dans la liste.
Assistance: Un objet, le TPE ou la banque concernés, ce qui se passe quand vous faites quoi, et le message d’erreur affiché par la banque.

Le formulaire d’assistance vous demande de ne pas inclure de numéro de carte ni de code de sécurité. Ils ne sont jamais nécessaires pour diagnostiquer un problème de paiement, et aucune donnée de paiement ou de carte n’est envoyée avec l’un ou l’autre formulaire.

L’extension gratuite ne contacte nos serveurs que lorsque vous appuyez sur l’un de ces boutons. Rien n’est envoyé selon un calendrier et il n’y a aucun appel de licence dans l’édition gratuite.

Free et Pro

La séparation porte sur la quantité, pas sur la capacité. Les treize établissements, 3-D Secure, le mode test, un volume de transactions illimité et le rapport de chiffre d’affaires de base sont dans l’édition gratuite.

Gratuit: Un TPE. Trois mensualités au maximum montrées au client. Un résumé de chiffre d’affaires fixe sur 30 jours. La table des BIN livrée avec l’extension.
Pro: Un nombre illimité d’enregistrements TPE — et donc le routage BIN. Jusqu’à douze mensualités. Les plages de rapport et les ventilations par TPE, banque, mensualité et code de refus, avec export CSV. Rafraîchissement BIN hebdomadaire en direct. Mises à jour automatiques de l’extension Pro elle-même.

Quand une licence expire ou est absente :

Votre boutique continue d’encaisser. Il n’y a aucune vérification de licence sur le chemin du paiement. Couper le chiffre d’affaires d’une boutique n’est pas une façon acceptable d’envoyer un rappel de renouvellement.
Le TPE par défaut continue de fonctionner, 3-D Secure et mode test compris.
Les enregistrements TPE supplémentaires se mettent en sommeil mais ne sont jamais supprimés, identifiants compris. Ils reprennent au renouvellement.
Le plafond de mensualités retombe à trois. Les taux que vous avez saisis au-delà sont conservés, pas effacés.
Les rapports retombent sur le résumé de 30 jours. L’historique collecté n’est pas supprimé.
Le rafraîchissement BIN en direct s’arrête ; la table livrée continue de fonctionner.

Si nos serveurs sont injoignables, une licence active continue de fonctionner pendant sept jours sur la foi de la dernière vérification réussie. Mais une licence dont la date d’expiration est passée est lue comme expirée quoi qu’il arrive — sinon, bloquer notre adresse serait un moyen de prolonger une licence d’une semaine.

Quand quelque chose ne fonctionne pas

La banque refuse tous les paiements sans message utile: Presque toujours la signature. Une mauvaise signature ne déclenche d’erreur nulle part — la banque refuse, tout simplement. Vérifiez le numéro de commerçant, la store key et tous les identifiants supplémentaires de cette famille : ils entrent tous dans la signature. Un test utile : les banques répondent différemment à une erreur de signature et à une carte invalide ; recevoir un message « carte invalide » signifie que votre signature est bonne.
« Erreur de hachage » au retour, avec plus d’un TPE: Le retour est une requête distincte, sans session. MevvPos consigne quel TPE une commande a utilisé et vérifie avec cette clé. Si vous avez supprimé l’enregistrement TPE par lequel une commande a été payée, la vérification retombe sur le TPE par défaut et peut échouer.
Le client atteint une page de paiement vide, ou le bouton Öde ne fait rien: Une extension de cache ou d’optimisation diffère les scripts. Sur LiteSpeed, excluez mevvpos, jquery et les scripts front-end de WooCommerce de la liste de délai. Le formulaire de carte est affiché par défaut pour que le parcours fonctionne quand même, mais pas la redirection automatique.
La commande reste « en attente » après un paiement réussi: La banque ou le prestataire n’a pas atteint l’adresse de rappel. Vérifiez que ?wc-api=mevvpos_callback est joignable depuis l’extérieur — un mode maintenance, une restriction d’IP ou un mur de connexion devant le site la bloquera.
Le formulaire de paiement se renvoie vers la même page: Le champ Gate URL est vide pour une banque dont l’adresse n’est pas préremplie. Saisissez l’adresse fournie par votre banque ou votre prestataire.
Le mode test est activé mais le paiement part quand même vers la banque en production: Le mode test arrête la redirection automatique et vous montre la requête ; il ne réécrit pas l’adresse de la passerelle pour les banques NestPay. Placez l’adresse de test de votre banque dans Gate URL pendant vos essais.
Les mensualités n’apparaissent pas: Soit le taux pour ce nombre est vide plutôt que zéro, soit la carte vient d’une autre banque, soit vous dépassez le plafond de trois de l’édition gratuite.
Les cartes vont vers le mauvais TPE après une mise à niveau: Les versions plus anciennes portaient des plages de BIN écrites à la main, en partie erronées. Vérifiez que chaque TPE est bien classé sous la banque auprès de laquelle il se trouve réellement.
L’écran d’administration semble sans style, ou un correctif n’apparaît pas: Un cache de navigateur périmé. Rechargez la page en contournant le cache.

Limites

La liste ci-dessous est délibérée. Rien de tout cela n’est un bug.

Aucun remboursement ni annulation depuis WordPress. L’extension n’implémente pas l’API de remboursement de WooCommerce et aucun prestataire ne porte d’appel de remboursement. Remboursez depuis l’écran de votre banque.
Livre turque uniquement. Le code de devise est figé chez chaque prestataire ; il n’y a pas de réglage multidevise.
Aucune carte enregistrée, aucune tokenisation, aucun abonnement ni paiement récurrent.
Aucune préautorisation. Chaque transaction est une vente directe.
Aucun routage basé sur des règles. Le routage se fait uniquement par banque émettrice — pas par montant, marque de carte ou pays.
Le formulaire de paiement est écrit pour la page de paiement WooCommerce classique. Aucun composant distinct pour la page de paiement en blocs n’est livré dans le paquet.
3D Pay Hosting a été écarté à dessein. La page hébergée supprime le périmètre PCI, mais aussi le BIN et la table des mensualités — et toute la valeur de cette extension réside dans le routage qu’ils rendent possible.
Pas d’éditeur de BIN. La table est gérée par nos soins et fusionnée avec le rafraîchissement en direct ; il n’existe aucun écran pour la modifier à la main.
Vingt-six établissements sont listés mais non implémentés. Ils restent visibles pour que le manque reste visible.
Tous les prestataires, sauf NestPay, sont auto-déclarés beta tant qu’ils n’ont pas été vérifiés de bout en bout avec un compte marchand réel.
Les onglets sont dans la page. Les entrées de la barre latérale ouvrent l’écran MevvPos ; le changement d’onglet se fait sur la page elle-même.

Ce qui n’est jamais conservé, sous aucune forme : le numéro de carte, la date d’expiration et le code de sécurité. Les seules données de carte conservées sont les six premiers chiffres et la banque qu’ils identifient. Conserver le code de sécurité est interdit en toutes circonstances, et même masqué, il révèle sa longueur.

D’un seul TPE virtuel à une carte routée vers la banque qui l’a émise.