VibeFox Midtrans for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 8.0 ou ultérieur, installé et activé. Sans WooCommerce, l'extension refuse de s'activer.
PHP : 8.0 ou ultérieur.
Devise de la boutique : roupie indonésienne (IDR). Pour les autres devises, le moyen de paiement est masqué sur la page de paiement. Il n'y a aucune conversion de devise.
Compte Midtrans : il vous faut la Server Key depuis Midtrans Dashboard > Settings > Access Keys, 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_midtrans_payment_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Réglez la devise de la boutique sur la roupie indonésienne (IDR).
4. Ouvrez les réglages : WooCommerce > Settings > Payments > Midtrans > Manage, ou cliquez sur Settings sous le nom du plugin sur la page Extensions.
5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
6. Saisissez les Server Keys et copiez l'URL de notification de paiement dans le tableau de bord Midtrans (voir Configuration).
7. Activez Enable/Disable. Testez en Sandbox, puis passez Environment sur Production.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Midtrans. Au-dessus des champs, la page vous avertit si la Server Key de l'environnement sélectionné est absente (le moyen de paiement est alors masqué sur la page de paiement) et si la devise de la boutique n'est pas IDR, et affiche Sandbox mode: payments are simulated, no real money is charged. tant que Sandbox est sélectionné. Dans la liste des moyens de paiement, Midtrans est signalé comme nécessitant une configuration tant qu'une Server Key n'a pas été saisie, et affiche Test mode en Sandbox.
Général
Enable/Disable : Enable Midtrans payments active ou désactive le moyen de paiement. Par défaut : off.
Title : le titre du moyen de paiement affiché aux clients sur la page de paiement. Par défaut : Midtrans.
Description : le texte affiché sous le moyen de paiement sur la page de 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 celui de sandbox.
Environment : l'environnement Midtrans utilisé pour les nouveaux paiements. Changer d'environnement utilise la clé et l'API de l'environnement sélectionné. Les commandes conservent l'environnement dans lequel elles ont été payées, 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-.
URL de notification de paiement
La notification indique à votre boutique qu'un paiement a été effectué. La section affiche l'URL à utiliser. Elle ressemble à https://your-site/wc-api/midtrans_p_callback/. Collez-la dans Midtrans Dashboard > Settings > Payment > Notification URL, dans le tableau de bord sandbox et dans celui de production que vous utilisez. Si vous ouvrez l'URL dans un navigateur, une courte explication s'affiche, ce qui permet de vérifier qu'elle est accessible. Le bouton Test notification URL du tableau de bord Midtrans reçoit aussi une réponse.
Chaque notification doit porter une signature valide créée avec l'une de vos Server Keys, et l'environnement de la clé doit correspondre à celui de la commande. Les notifications sans signature valide sont rejetées. Le statut est alors relu auprès de l'API de statut de Midtrans. L'extension gère les statuts de transaction Midtrans suivants :
Sans l'URL de notification, une commande n'est confirmée que lorsque le client revient dans la boutique après avoir payé.
Réglages de paiement
Midtrans n'encaisse qu'en IDR, et les montants sont envoyés en roupies entières. Si les lignes de la commande ne correspondent pas au total arrondi, une ligne Rounding adjustment est envoyée à Midtrans.
Status after payment : le statut de commande après un paiement confirmé. Le statut est défini en une seule étape, sans double e-mail au client.
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.
Order ID prefix : ajouté au numéro de commande envoyé à Midtrans, afin que plusieurs boutiques puissent partager un même compte Midtrans. 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 : Log API calls and notifications écrit dans WooCommerce > Status > Logs, source wcp_midtrans_payment_gateway. Les erreurs sont toujours journalisées. Les clés et les données clients ne sont jamais journalisées. Par défaut : off.
Delete data on uninstall : Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. Par défaut : off.
Paiement
Le client choisit le moyen de paiement (par défaut Midtrans) et passe la commande. L'extension crée une transaction Midtrans Snap pour le total de la commande en roupies entières, avec les lignes de commande, la livraison, les taxes et les coordonnées de facturation et de livraison du client, puis envoie le client sur la page de paiement Midtrans. Il y choisit parmi tous les moyens activés dans votre compte Midtrans.
Après le paiement, le client revient sur la page de confirmation de commande de votre boutique. Le lien de retour ne marque jamais une commande comme payée : l'extension interroge l'API de statut de Midtrans, et la commande n'est marquée payée qu'après confirmation de Midtrans. Tant que le paiement n'est pas confirmé, 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. La page indique aussi le moyen de paiement utilisé.
Si le paiement n'a pas été effectué, le client est renvoyé vers la page Pay for order avec 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. 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 confirmée et aucune nouvelle transaction n'est créée.
Si Midtrans ne peut pas démarrer le paiement, le client voit 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 avec une Server Key erronée) ou la raison fournie par Midtrans. La raison technique est ajoutée aux notes de commande.
Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension utilise uniquement Snap Redirect. Elle 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 WooCommerce Subscriptions. Les paiements par carte sont capturés immédiatement, sans autorisation et capture séparées.
Commandes et remboursements
Statuts de commande
Pending payment : le client a été envoyé vers Midtrans et n'a pas encore choisi de moyen de paiement.
On hold : le client a choisi un moyen différé et n'a pas encore payé, le paiement par carte est en contrôle antifraude (challenge), ou le montant ou la devise payés ne correspondent pas à la commande. Le statut « En attente » est aussi défini lorsqu'un paiement arrive pour une commande annulée ; la commande n'est pas rouverte automatiquement. La note de commande l'explique.
Processing, Completed or On hold after payment : le paiement a été confirmé. Le statut suit Status after payment. La note de commande indique le moyen de paiement et les identifiants Midtrans. L'ID de transaction est l'ID de transaction Midtrans et, sur l'écran de la commande, il renvoie vers la transaction dans le tableau de bord Midtrans de l'environnement de la commande.
Failed : le paiement a échoué, ou un paiement par carte en challenge a été refusé.
Cancelled : la transaction non payée a expiré ou a été annulée. Le stock est restitué. Lorsque vous annulez une commande Midtrans non payée dans WooCommerce (ou que le minuteur des commandes non payées le fait), sa transaction Midtrans en attente, par exemple un compte virtuel émis, est expirée afin qu'elle ne puisse plus être payée.
Si un second paiement arrive pour une commande déjà payée, la commande n'est plus modifiée. Une note vous invite à rembourser le second paiement dans le tableau de bord Midtrans. Un paiement pour une commande remboursée ajoute seulement une note.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Midtrans (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge en roupies entières ; un montant avec décimales est refusé. Le remboursement est envoyé dans l'environnement où la commande a été payée, la Server Key de cet environnement doit donc être configurée. Midtrans n'autorise les remboursements par API que pour certains moyens de paiement et états de transaction (par exemple les paiements par carte réglés, GoPay, QRIS ou ShopeePay). Si Midtrans n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré ; remboursez alors depuis le tableau de bord Midtrans. Un remboursement réussi est ajouté aux notes de commande.
Les remboursements effectués dans le tableau de bord Midtrans arrivent par notification et sont enregistrés automatiquement comme remboursements WooCommerce, avec le motif Refunded in the Midtrans dashboard.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Midtrans. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un seul domaine. Retirer la clé d'un site 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 sur la page de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés de la boutique voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. 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, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement en arrière-plan.
Dépannage
Midtrans n'apparaît pas sur la page de paiement : 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 de la boutique (ou celle de la commande sur la page Pay for order) est IDR. La page des réglages affiche un avertissement pour chacun de ces problèmes.
Le paiement a abouti, mais la commande reste Pending payment : la notification ne fonctionne pas. Vérifiez que l'URL de notification de paiement est renseignée dans le tableau de bord Midtrans de l'environnement utilisé (sandbox ou production) et qu'elle est accessible : ouvrez-la dans un navigateur, une courte explication s'affiche. Activez le Debug log pour voir les notifications. La commande est aussi confirmée lorsque le client revient dans la boutique après avoir payé.
La notification répond Invalid signature : la notification n'a pas été signée avec votre Server Key Sandbox ou Production. Vérifiez que les clés dans les réglages appartiennent au même compte Midtrans que le tableau de bord qui envoie les notifications.
La notification répond Server key not configured : aucune Server Key n'est renseignée. Saisissez-la dans les réglages ; Midtrans renouvelle la notification.
La notification répond Order not found — ignored : l'ID de commande Midtrans n'appartient à aucune commande de cette boutique, par exemple à une autre boutique utilisant le même compte Midtrans. Attribuez à chaque boutique un Order ID prefix différent.
La notification répond Environment mismatch — ignored : la notification a été signée avec la clé d'un autre environnement que celui dans lequel la commande a été payée.
La notification répond Verification failed, please retry : l'API de statut de Midtrans n'a pas pu être atteinte. Midtrans renouvelle la notification.
La commande est On hold : lisez la note de commande. Le client n'a pas terminé un paiement différé, le paiement par carte est en contrôle antifraude, ou le montant ou la devise payés ne correspondent pas à la commande.
Le client voit une erreur lors de la passation de commande : ouvrez les notes de commande ou activez le Debug log et consultez WooCommerce > Status > Logs, source wcp_midtrans_payment_gateway. Une commande qui n'est pas en IDR affiche Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
Le remboursement échoue : le moyen de paiement ou l'état de la transaction ne permet pas les remboursements par API ; remboursez depuis le tableau de bord Midtrans, le remboursement sera enregistré automatiquement dans WooCommerce. 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.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Désinstallation
Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Extensions. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
Midtrans est une marque de son détenteur respectif. Cette extension n'est ni affiliée à Midtrans ni approuvée par Midtrans.