VibeFox Midtrans for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise : roupie indonésienne (IDR). Midtrans n'encaisse qu'en IDR, donc le moyen de paiement n'est proposé que lorsque la devise du panier est l'IDR. Il n'y a aucune conversion de devise. Ajoutez la devise IDR dans International > Localization si votre boutique ne l'a pas.

Compte Midtrans : vous avez besoin de la Server Key, disponible dans Midtrans Dashboard > Settings > Access Keys, à la fois dans le tableau de bord sandbox et dans le tableau de bord production. Seule la Server Key est utilisée. La Client Key n'est pas nécessaire pour Snap Redirect. Les moyens de paiement eux-mêmes (GoPay, QRIS, comptes virtuels et autres) sont activés dans votre compte Midtrans.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléchargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Midtrans Payment Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez les Server Keys et copiez l'URL de notification de paiement dans le tableau de bord Midtrans (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez en Sandbox, puis passez Environment sur Production.

À l'installation, le module crée deux statuts de commande : Awaiting Midtrans payment et Midtrans payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences. Le module doit rester autorisé pour la devise IDR.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque la Server Key de l'environnement sélectionné est absente (le moyen de paiement est alors masqué au paiement) et lorsque la devise par défaut de la boutique n'est pas l'IDR, et affiche Sandbox mode: payments are simulated, no real money is charged. tant que Sandbox est sélectionné.

Midtrans

Enable/Disable : Enable Midtrans payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le titre du moyen de paiement affiché aux clients au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Midtrans. Obligatoire.

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. En Sandbox, la ligne SANDBOX MODE: no real money is charged. est ajoutée.

Identifiants API

Copiez la Server Key depuis Midtrans Dashboard > Settings > Access Keys. La section contient des liens vers le tableau de bord de production et vers le tableau de bord sandbox.

Environment : l'environnement Midtrans utilisé pour les nouveaux paiements. Le changement utilise la clé et l'API de l'environnement sélectionné. Les paiements conservent l'environnement dans lequel ils ont été effectués, pour les remboursements et les notifications. Par défaut : Sandbox.

Production Server Key : commence par Mid-server-. Gardez-la secrète.

Sandbox Server Key : commence par SB-Mid-server-.

Les clés enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

URL de notification de paiement

La notification indique à votre boutique qu'un paiement a été effectué. Le champ Notification URL affiche l'URL à utiliser. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_midtrans_payment_gateway/webhook, éventuellement suivie d'un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages et collez-la dans Midtrans Dashboard > Settings > Payment > Notification URL, dans le tableau de bord sandbox et dans le tableau de bord production que vous utilisez. Si vous ouvrez l'URL dans un navigateur, une courte explication s'affiche, ce qui vous permet de vérifier qu'elle est accessible. Le bouton Test notification URL du tableau de bord Midtrans reçoit également une réponse.

Chaque notification doit porter une signature valide, réalisée avec l'une de vos Server Keys, et l'environnement de la clé doit correspondre à celui du paiement. Les notifications sans signature valide sont rejetées. Le statut est alors relu auprès de l'API de statut de Midtrans. Le module gère les statuts de transaction Midtrans suivants :

Sans l'URL de notification, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé, et un paiement différé effectué plus tard n'est pas pris en compte tant que le client ne revient pas.

Réglages de paiement

Midtrans n'encaisse qu'en IDR, et les montants sont envoyés en roupies entières. Si les lignes de commande ne correspondent pas au total arrondi, une ligne Rounding adjustment est envoyée à Midtrans.

Status after payment : le statut de la commande après un paiement confirmé.

Payment page expiry (minutes) : durée pendant laquelle le client peut payer (page Snap, compte virtuel, etc.). Laissez vide ou mettez 0 pour la valeur par défaut de Midtrans. Une valeur qui n'est pas un nombre entier de minutes est refusée avec une erreur lors de l'enregistrement.

Order ID prefix : ajouté au numéro envoyé à Midtrans, pour que plusieurs boutiques puissent partager un même compte Midtrans. Le numéro est l'identifiant du panier suivi d'un horodatage, par exemple WC-123-1700000000. Lettres, chiffres et - _ . ~ uniquement, jusqu'à 20 caractères ; les autres caractères sont supprimés à l'enregistrement. Les notifications des autres boutiques sont ignorées. Par défaut : WC-.

Avancé

Debug log : écrit les appels à l'API et les notifications dans logs/midtrans_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours consignées. Les clés et les données clients ne sont jamais consignées. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : lorsque l'option est activée, la désinstallation du module supprime ses réglages et son journal. Les commandes, leurs références de paiement Midtrans et leurs remboursements, ainsi que les statuts de commande du module, sont toujours conservés, afin que les anciennes commandes puissent être remboursées après une réinstallation. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Midtrans) et confirme. Le module crée une transaction Midtrans Snap pour le total du panier en roupies entières, avec les lignes de commande, la livraison, les remises, l'emballage cadeau, la taxe ainsi que les coordonnées de facturation et de livraison du client, puis envoie le client sur la page de paiement Midtrans. Il y choisit n'importe quel moyen activé dans votre compte Midtrans. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. Le lien de retour ne marque jamais une commande comme payée : la commande n'est marquée payée qu'après confirmation de Midtrans, par la notification signée ou par une requête à l'API de statut de Midtrans lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec le moyen de paiement utilisé. Pour un paiement différé, la page affiche We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Pour une commande clôturée sans paiement, elle affiche Your Midtrans payment was not completed. Please contact us about this order. Si Midtrans est injoignable lorsque le client revient, une page Payment confirmation affiche We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. avec un bouton Check again.

Si le client a quitté la page Snap sans payer, il revient au paiement avec le message The Midtrans payment was not completed. You can try again below. Si le paiement a été refusé ou a expiré, le message est Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Le panier est conservé. Lorsque le client paie à nouveau, un Snap non utilisé ou en attente pour le même montant est réutilisé. Si le montant a changé, la transaction en attente est d'abord expirée chez Midtrans. Si le Snap précédent a été payé entre-temps, la commande est créée et aucune nouvelle transaction n'est effectuée. Si la commande existe déjà et a été clôturée sans paiement, le message est Your Midtrans payment was declined or has expired. Please place a new order or contact us.

Si Midtrans ne peut pas démarrer le paiement, le client reste au paiement avec un message court : Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (par exemple en cas de Server Key erronée) ou la raison indiquée par Midtrans. La raison technique est écrite dans le journal. Un panier qui n'est pas en IDR affiche Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

La notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Le module utilise uniquement Snap Redirect. Il n'a ni fenêtre Snap (pop-up), ni formulaire de carte sur votre site, ni cartes enregistrées ou paiements en un clic, ni paramètres de paiement en plusieurs fois ou de promotions (configurez les moyens de paiement dans le tableau de bord Midtrans), ni abonnements. Les paiements par carte sont encaissés immédiatement, sans autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé à Midtrans et n'a pas payé, ou Midtrans n'a pas encore confirmé le paiement. Seul le panier existe.

Awaiting Midtrans payment : le client a choisi un moyen différé (compte virtuel, magasin de proximité) ou a commencé un paiement par carte qui n'est pas terminé. La commande devient payée lorsque Midtrans signale le paiement.

Payment accepted, Delivered ou Midtrans payment on hold : le paiement a été confirmé. Le statut suit Status after payment. Le paiement est enregistré avec l'identifiant de transaction Midtrans, et une note indique le moyen de paiement et l'identifiant de commande Midtrans.

Midtrans payment on hold : est aussi utilisé lorsqu'un paiement par carte est en cours d'examen antifraude (challenge, aucun paiement encore enregistré), lorsque le montant ou la devise payés ne correspondent pas à la commande (la commande n'est pas marquée payée), ou lorsqu'un paiement arrive pour une commande annulée (la commande n'est pas rouverte automatiquement). La note l'explique. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Canceled : la transaction non payée a expiré ou a été annulée. Lorsque vous annulez vous-même une commande Midtrans non payée, sa transaction Midtrans en attente, par exemple un compte virtuel émis, expire afin qu'elle ne puisse plus être payée.

Payment error : le paiement a échoué, ou un paiement par carte soumis à vérification a été refusé.

Refunded : le paiement a été entièrement remboursé.

Si un second paiement arrive pour une commande déjà payée, la commande ne change pas. Une note vous demande de rembourser le second paiement dans le tableau de bord Midtrans. Un paiement pour une commande remboursée ajoute seulement une note.

Bloc de paiement Midtrans

La page de commande affiche un bloc Midtrans payment avec l'identifiant de commande Midtrans, l'identifiant de transaction (lié à la transaction dans le tableau de bord Midtrans de l'environnement du paiement), le moyen de paiement, le statut, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Midtrans notes de la commande.

Remboursements

Dans le bloc Midtrans payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Midtrans. Confirmez la question Refund this amount through Midtrans? This cannot be undone. Les remboursements totaux et partiels sont pris en charge en roupies entières ; un montant comportant des décimales est refusé. Vous devez avoir le droit de modifier les commandes. Vous pouvez rembourser jusqu'au montant effectivement débité par Midtrans, même si la commande a été modifiée ensuite. Le remboursement est envoyé dans l'environnement où le paiement a été effectué ; la Server Key de cet environnement doit donc être renseignée. Midtrans n'autorise les remboursements par API que pour certains moyens de paiement et certains états de transaction (par exemple les paiements par carte réglés, GoPay, QRIS ou ShopeePay). Si Midtrans refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré ; remboursez alors dans le tableau de bord Midtrans. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Midtrans a signalé le paiement comme réglé.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Midtrans.

Les remboursements effectués dans le tableau de bord Midtrans arrivent par notification et sont ajoutés automatiquement à l'historique des remboursements, avec le motif Refunded in the Midtrans dashboard. Lorsque la totalité du paiement y est remboursée, la commande passe en Refunded.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Midtrans Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-midtrans et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : celui de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Midtrans n'est pas affiché aux clients au moment du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

Midtrans does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé et que l'Environment sélectionné dispose de sa Server Key. Vérifiez que la devise du panier est l'IDR. Dans Payment > Preferences, vérifiez que le module est autorisé pour l'IDR, le pays du client et le groupe du client. La page des réglages affiche un avertissement lorsque la clé est absente ou que la devise de la boutique n'est pas l'IDR.

The payment went through, but no order was created : la notification ne fonctionne pas. Vérifiez que l'URL de notification de paiement est configurée dans le tableau de bord Midtrans de l'environnement utilisé (sandbox ou production), qu'elle correspond exactement à l'URL affichée dans Notification URL et qu'elle est accessible : ouvrez-la dans un navigateur, une courte explication s'affiche. Activez Debug log pour voir les notifications. La commande est aussi créée lorsque le client revient dans la boutique après avoir payé.

Notification answers Invalid signature : la notification n'a pas été signée avec votre Server Key Sandbox ou Production. Vérifiez que les clés des réglages appartiennent au même compte Midtrans que le tableau de bord qui envoie les notifications.

Notification answers Server key not configured : aucune Server Key n'est renseignée. Saisissez-la dans les réglages ; Midtrans renouvelle la notification.

Notification answers Order not found — ignored : l'identifiant de commande Midtrans n'a pas été émis par cette boutique, par exemple par une autre boutique du même compte Midtrans. Attribuez à chaque boutique un Order ID prefix différent.

Notification answers Environment mismatch — ignored : la notification a été signée avec la clé de l'autre environnement que celui dans lequel le paiement a été effectué.

Notification answers Verification failed, please retry : l'API de statut de Midtrans n'a pas pu être jointe. Midtrans renouvelle la notification.

Notification answers Busy, please retry : le panier était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Midtrans renouvelle la notification. Consultez le journal pour en connaître la raison.

The order is Midtrans payment on hold : lisez les Midtrans notes dans le bloc. Le paiement par carte est en cours d'examen antifraude, le montant ou la devise payés ne correspondent pas à la commande, ou le paiement est arrivé après l'annulation de la commande.

The customer sees an error when choosing Midtrans : consultez le champ Log sur la page du module ; les erreurs sont toujours consignées. Une Server Key erronée affiche le message indiquant que les paiements Midtrans sont temporairement indisponibles.

Refund fails : le moyen de paiement ou l'état de la transaction n'autorise pas les remboursements par API ; remboursez dans le tableau de bord Midtrans, et le remboursement sera automatiquement enregistré sur la commande. Si le message indique qu'aucune Server Key n'est configurée pour l'environnement dans lequel la commande a été payée, saisissez cette clé et réessayez.

Les développeurs peuvent modifier les données envoyées à Midtrans avec le hook actionWcpMidtransSnapPayload ; l'identifiant de commande et le montant ne peuvent pas être modifiés.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Midtrans Payment Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages du module et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les références de paiement Midtrans et les remboursements des commandes, ainsi que les statuts de commande Awaiting Midtrans payment et Midtrans payment on hold, sont toujours conservés, afin que les commandes payées auparavant puissent être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Midtrans est une marque de son titulaire respectif. Ce module n'est ni affilié à Midtrans ni approuvé par Midtrans.