VibeFox Xendit for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Devise de la boutique : IDR, PHP, VND, THB, MYR, USD ou SGD. Pour les autres devises du panier, le moyen de paiement n'est pas affiché. Les canaux de paiement et les devises réellement disponibles dépendent de votre compte Xendit.

Compte Xendit : vous avez besoin d'une clé API secrète avec l'autorisation d'écriture pour Money-in (factures) pour le mode test, et d'une autre pour le mode production, ainsi que du jeton de vérification de webhook de chaque mode (voir Configuration). Seuls les clés secrètes et les jetons de vérification sont utilisés. Aucune clé publique n'est nécessaire, car le client paie sur la page de facture hébergée par Xendit.

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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Xendit 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. Collez vos clés secrètes Xendit, définissez l'URL du webhook dans le tableau de bord Xendit et collez les jetons de vérification (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Passez une commande test en mode test, puis désactivez Test Mode pour accepter de vrais paiements.

À l'installation, le module crée le statut de commande Xendit 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 limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, un encadré indique le mode actif : TEST MODE (les factures sont créées avec la clé secrète de test et aucun argent réel n'est débité) ou LIVE MODE (les factures sont créées avec la clé secrète de production et les clients sont débités). L'encadré vous avertit si la clé secrète du mode actif est absente ou a un mauvais préfixe (le moyen de paiement est alors masqué à la commande), et si le jeton de vérification du webhook du mode actif est vide (les notifications Xendit sont rejetées, de sorte que les commandes ne sont créées que lorsque le client revient dans votre boutique).

Xendit

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

Title : le nom du moyen de paiement que voient les clients à la commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Xendit. Obligatoire.

Description : le texte affiché sous le moyen de paiement à la commande. Par défaut : Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Clés API

Créez une clé API secrète avec l'autorisation d'écriture pour Money-in (factures) dans Xendit Dashboard > Settings > Developers > API keys, une fois en mode test et une fois en mode production. La clé détermine où la facture est créée. À l'enregistrement, une clé qui ne commence pas par le préfixe de son champ n'est pas enregistrée, et la page affiche par exemple Test secret key was not saved: it must start with xnd_development_. Les autres réglages sont enregistrés.

Test Mode : crée les factures avec la clé secrète de test, si bien qu'aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour accepter de vrais paiements avec la clé secrète de production. Tant qu'il est activé, les clients voient Test mode: no real money is charged. sous le moyen de paiement.

Test Secret Key : la clé secrète du mode test de Xendit. Elle commence par xnd_development_.

Live Secret Key : la clé secrète du mode production de Xendit. Elle commence par xnd_production_.

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

Webhooks

Le webhook indique à votre boutique qu'une facture a été payée. Dans Xendit Dashboard > Settings > Developers > Webhooks, définissez l'URL affichée dans Webhook URL de cette section pour Invoices > Invoice paid, en mode test et en mode production. Vous pouvez aussi la définir pour Invoice expired. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_xendit_payment_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez-la exactement comme les réglages l'affichent.

Copiez ensuite le Webhook verification token de chaque mode depuis le tableau de bord Xendit dans le champ correspondant. Xendit l'envoie dans l'en-tête x-callback-token. Les notifications sans le jeton du mode dans lequel la facture a été créée sont rejetées. Le jeton prouve seulement que la notification provient de Xendit : le statut, le montant et la devise de la facture sont toujours relus depuis l'API Xendit avec la clé secrète de ce mode. Sans le webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Test Webhook Verification Token : le jeton de vérification du webhook du mode test de Xendit.

Live Webhook Verification Token : le jeton de vérification du webhook du mode production de Xendit.

Clear saved secrets : cochez une clé ou un jeton et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Invoice Description : la description affichée sur la facture Xendit. Vous pouvez utiliser les espaces réservés {order_id}, {order_number} et {site_name}. Comme la commande est créée après le paiement, {order_id} et {order_number} correspondent au numéro du panier. Le HTML est supprimé et le texte est tronqué à 255 caractères. Par défaut : Order #{order_id}.

Order Status After Payment : le statut de commande appliqué après la confirmation du paiement par Xendit.

Avancé

Debug Log : écrit les requêtes API et les webhooks dans logs/xendit_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés, même si cette option est désactivée. Les clés API, les jetons et les données client ne sont pas journalisés. 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 : si cette option est activée, la désinstallation du module supprime les réglages du module et le journal. Les données de commande (identifiants de facture des commandes) et le statut Xendit payment on hold sont toujours conservés. Par défaut : désactivé.

Paiement

Le moyen de paiement est affiché lorsque la devise du panier est IDR, PHP, VND, THB, MYR, USD ou SGD. Le client le choisit à l'étape de paiement (par défaut Xendit) et confirme. Le module crée une facture Xendit pour le total du panier dans la devise du panier et envoie le client vers la page de facture Xendit. Les montants en IDR et VND sont arrondis à des nombres entiers, car Xendit n'accepte pas de décimales pour ces devises. L'adresse e-mail du client est transmise à Xendit. Sur la page de facture, le client paie avec l'un des canaux de paiement activés dans votre compte Xendit pour cette devise, par exemple un compte virtuel, un portefeuille électronique, un code QR, un point de vente ou une carte. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par Xendit : par le webhook, ou par une requête côté serveur à l'API Xendit lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande. Si Xendit n'a pas encore confirmé le paiement, une page Payment confirmation affiche Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. avec les boutons Check again et Back to checkout. Le webhook crée la commande dès son arrivée.

Si la facture échoue ou expire, Xendit renvoie le client. Le module vérifie d'abord la facture (elle a peut-être été payée dans un autre onglet), puis la fait expirer afin qu'elle ne puisse plus être payée. Le client revient à l'étape de paiement avec The Xendit payment was not completed. You can try again or choose another payment method. Le panier est conservé.

Un client peut payer à nouveau le même panier. Si le total du panier, la devise et le mode n'ont pas changé et que la facture ouverte reste valable au moins cinq minutes de plus, le client est envoyé vers la même facture. Sinon, l'ancienne facture est d'abord mise à expiration et une nouvelle est créée, de sorte qu'il n'y a jamais deux factures ouvertes pour un même panier. Si l'ancienne facture a déjà été payée, la commande est créée au lieu d'un nouveau paiement.

Si Xendit ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec un court message, par exemple Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., un message indiquant que la devise n'est pas acceptée pour votre compte ou que le total de la commande est hors des limites de montant de Xendit. La raison technique est écrite dans le journal. Un panier d'un total nul ne peut pas être payé avec Xendit.

Le webhook fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le paiement se fait toujours sur la page de Xendit. Le module ne propose pas de remboursements depuis le back office, ni de cartes enregistrées, d'abonnements ou de paiements récurrents, ni de champs carte ou portefeuille électronique sur la page de paiement, ni d'autorisation et capture séparées, ni de sous-comptes xenPlatform.

Commandes

Statuts de commande

Aucune commande pour l'instant : le client a été envoyé vers Xendit et n'a pas payé, ou Xendit n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted or Delivered : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de facture Xendit comme identifiant de transaction, et une note indique l'identifiant de facture, le montant payé, le canal de paiement et le mode.

Xendit payment on hold : la facture payée ne correspondait pas au total ou à la devise du panier, ou un montant inférieur au total a été payé (par exemple, le panier a été modifié après la création de la facture). La note l'explique. Vérifiez le paiement dans le tableau de bord Xendit, puis traitez la commande ou remboursez le paiement. Si une autre facture du même panier est payée plus tard avec le bon montant, le paiement est enregistré et la commande passe au statut payé.

Si une facture est payée pour une commande déjà annulée ou remboursée, le statut de la commande ne change pas. Une note vous demande de rembourser le paiement dans le tableau de bord Xendit ou de rétablir la commande manuellement. Si une seconde facture est payée pour une commande déjà payée, la commande ne change pas et une note vous demande de rembourser le paiement en double dans le tableau de bord Xendit.

Bloc Xendit payment

La page de commande affiche un bloc Xendit payment avec l'identifiant de facture, le mode (avec un badge Test mode pour les paiements test), le statut du paiement, la liste de toutes les factures de la commande (date, facture, ID externe, montant et montant payé, statut, canal de paiement) et les Payment notes de la commande.

Remboursements

Les remboursements ne sont pas envoyés à Xendit depuis la boutique. Remboursez le paiement dans le tableau de bord Xendit (recherchez l'identifiant de facture affiché dans le bloc Xendit payment) et enregistrez le remboursement manuellement dans la commande. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Xendit.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Xendit Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox Xendit 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-xendit 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-le dans votre compte vibefox.net.

Sans clé active, Xendit n'est pas proposé aux clients à la commande. 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 pas le tester à la commande. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà démarrés sont toujours confirmés.

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é 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

Xendit n'apparaît pas à la commande : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actif dispose d'une clé secrète avec le bon préfixe (Test Secret Key avec xnd_development_ en mode test, Live Secret Key avec xnd_production_ en mode production) et que la devise du panier est IDR, PHP, VND, THB, MYR, USD ou SGD. La page des réglages affiche un avertissement lorsque la clé est absente ou incorrecte. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : le webhook ne fonctionne pas. Dans le tableau de bord Xendit du mode utilisé (test ou production), vérifiez que l'URL affichée dans Webhook URL est définie pour Invoice paid et que le jeton de vérification de ce mode est enregistré dans le champ correspondant. Le tableau de bord Xendit affiche la réponse de votre boutique pour chaque webhook. La commande est aussi créée lorsque le client revient dans la boutique après le paiement.

Webhook answers Webhook verification token is not configured : aucun jeton de vérification n'est défini. Collez le jeton dans les réglages.

Webhook answers Unauthorized : le jeton envoyé par Xendit ne correspond à aucun jeton des réglages. Copiez à nouveau le jeton du bon mode.

Webhook answers Token does not match the mode of this invoice : la facture a été créée dans l'autre mode. Une notification de test ne confirme jamais un paiement réel, et inversement. Configurez le webhook et le jeton dans le mode dans lequel le panier a été payé.

Webhook answers Ignored: not an invoice of this store : la facture n'a pas été créée par cette boutique, par exemple par une autre intégration sur le même compte Xendit. Le bouton Test du tableau de bord Xendit reçoit aussi cette réponse, ce qui confirme que l'URL et le jeton fonctionnent. Ignored: unknown order et Ignored: unknown invoice signifient que le panier ou la facture n'est pas connu de cette boutique.

Webhook answers Temporary error : l'API Xendit n'a pas pu être jointe pour vérifier la facture, la clé secrète du mode de la facture est absente, 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, le module est désactivé). Xendit renouvelle le webhook. Vérifiez que les deux clés secrètes sont définies si des paiements ont été démarrés dans les deux modes, et activez Debug Log pour voir la raison.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes de Xendit.

Une clé n'est pas enregistrée : la valeur ne commence pas par le préfixe de son champ. Les clés de test commencent par xnd_development_, les clés de production par xnd_production_.

Le client voit This payment method is temporarily unavailable : Xendit a rejeté la requête, par exemple parce que la clé secrète est incorrecte ou n'a pas l'autorisation d'écriture pour Money-in (factures). Consultez le champ Log sur la page du module. Un message concernant les coordonnées de facturation signifie que Xendit n'a pas accepté les données de la requête, par exemple l'adresse e-mail.

Le client voit A payment for this order was already received by Xendit and is being reviewed : une facture antérieure de ce panier a été payée, mais la commande n'a pas encore pu être confirmée. Vérifiez le paiement dans le tableau de bord Xendit et dans le journal.

Le client voit We could not match this payment to an order : le lien de retour de Xendit n'appartient à aucun panier de cette boutique, ou aucune facture du panier n'a pu être associée. Vérifiez le paiement dans le tableau de bord Xendit et dans le journal.

La commande passe en Xendit payment on hold après le paiement : lisez les notes dans le bloc Xendit payment. Le montant ou la devise payé différait du panier. Traitez la commande ou remboursez le paiement dans le tableau de bord Xendit.

Pour les développeurs, le module fournit les hooks actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies et actionWcpXenditCurrencyDecimals pour modifier la requête de facture, la liste des devises et le nombre de décimales par devise.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Xendit 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 future réinstallation. Les données de facture Xendit des commandes et le statut Xendit payment on hold sont toujours conservés. Les commandes existantes conservent leurs notes de paiement et identifiants de transaction.

Xendit est une marque de son propriétaire respectif. Ce module n'est ni affilié à Xendit ni approuvé par Xendit.