VibeFox Xendit for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

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

Compte Xendit : vous avez besoin d'une clé API secrète avec 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_xendit_payment_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Xendit > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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).

6. Activez Enable/Disable. Passez une commande test en mode test, puis décochez Test Mode pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Xendit. Au-dessus des champs, une bannière 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). La bannière vous avertit lorsque la clé secrète du mode actif est absente ou a le mauvais préfixe (le moyen de paiement est alors masqué à la commande), et lorsque le jeton de vérification de webhook du mode actif est vide (les notifications Xendit sont rejetées, de sorte que les commandes ne sont mises à jour que lorsque le client revient dans votre boutique). Dans la liste des moyens de paiement, Xendit est signalé comme nécessitant une configuration tant que le mode actif n'a pas de clé secrète valide.

Général

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. Par défaut : Xendit.

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 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 : Enable test mode crée les factures avec la clé secrète de test, de sorte qu'aucun argent réel n'est débité. Par défaut : activé. Décochez-le pour accepter de vrais paiements avec la clé secrète de production.

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_.

Webhooks

Le webhook informe votre boutique qu'une facture a été payée. Dans Xendit Dashboard > Settings > Developers > Webhooks, définissez l'URL affichée dans cette section des réglages pour Invoices > Invoice paid, en mode test et en mode production. Vous pouvez aussi la définir pour Invoice expired. L'URL ressemble à https://your-site/wc-api/xendit_p_callback/. 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 webhook, une commande n'est confirmée que lorsque le client revient dans la boutique après avoir payé.

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

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

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}. 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 défini une fois que Xendit confirme le paiement. Le statut est défini immédiatement, en un seul changement de statut.

Avancé

Debug Log : Log API requests and webhooks écrit les requêtes, les webhooks et les changements de statut dans WooCommerce > Status > Logs, source wcp_xendit_payment_gateway. Les erreurs et avertissements sont toujours journalisés, même lorsque cette option est désactivée. Les clés API, les jetons et les données clients ne sont pas journalisés. Par défaut : désactivé.

Delete Data on Uninstall : Delete the plugin settings and logs when the plugin is deleted. La désactivation de l'extension ne supprime jamais rien. Les données de commande (identifiants de facture dans les commandes) sont toujours conservées. Par défaut : désactivé.

Page de paiement

Le moyen de paiement s'affiche lorsque la devise de la boutique est IDR, PHP, VND, THB, MYR, USD ou SGD. Sur la page Pay for order, c'est la devise de la commande qui compte. Le client choisit le moyen de paiement (par défaut Xendit) et passe la commande. L'extension crée une facture Xendit pour le total de la commande dans la devise de la commande et envoie le client sur 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 de facturation 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.

Une fois le paiement effectué, le client revient sur la page « Commande reçue » de votre boutique. La commande n'est marquée payée qu'après confirmation de Xendit : par le webhook, ou par une requête côté serveur à l'API Xendit lorsque le client arrive sur cette page. D'ici là, la commande reste En attente de paiement.

Si la facture échoue ou expire, Xendit renvoie le client vers la boutique. Une commande passée lors du paiement est alors annulée de la manière standard de WooCommerce, et sa facture expire. Une commande payée depuis la page Pay for order (par exemple une commande que vous avez créée pour le client) revient à sa page de paiement avec le message The Xendit payment was not completed. You can try again or choose another payment method. et reste payable.

Un client peut payer à nouveau une commande impayée. Si le total de la commande, la devise et le mode n'ont pas changé et que la facture ouverte est toujours valide, le client est redirigé vers la même facture. Sinon, l'ancienne facture expire d'abord et une nouvelle est créée, de sorte qu'il n'existe jamais deux factures ouvertes pour une même commande. Si l'ancienne facture avait déjà été payée, la commande passe à Terminée au lieu d'un nouveau paiement.

Si Xendit ne peut pas démarrer le paiement, le client voit un bref message et peut choisir un autre moyen de paiement, 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. Une commande d'un montant nul ne peut pas être payée avec Xendit.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. En mode test, le bloc Paiement affiche Test mode: no real money is charged. sous le moyen de paiement. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

Le paiement se fait toujours sur la page de Xendit. L'extension ne gère ni remboursements depuis WooCommerce, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni champs de carte ou de portefeuille électronique sur la page de paiement, ni autorisation et capture séparées, ni sous-comptes xenPlatform, ni expiration de facture personnalisée ni frais de paiement.

Commandes

Statuts de commande

Pending payment : la facture a été créée et le client n'a pas encore payé, ou Xendit n'a pas encore confirmé le paiement. La note de commande affiche l'identifiant de facture, le montant, la devise et le mode.

Processing or Completed : le paiement a été confirmé. Le statut suit Order Status After Payment. La note de commande affiche l'identifiant de facture, le montant payé, le canal de paiement et le mode. L'identifiant de transaction est l'identifiant de facture Xendit.

On hold : la facture payée ne correspondait pas au total ou à la devise de la commande, ou un montant inférieur au total a été payé (par exemple, la commande a été modifiée après la création de la facture). La note de commande l'explique, y compris lorsque la commande était déjà en attente. Vérifiez le paiement dans le tableau de bord Xendit, puis traitez la commande ou remboursez le paiement.

Failed : la facture en cours a expiré sans paiement. Le client peut payer la commande à nouveau.

Cancelled : le client est revenu après une facture échouée ou expirée, ou la commande a été annulée par vous ou par le délai d'expiration WooCommerce des commandes impayées. La facture ouverte expire, elle ne peut donc plus être payée. Si Xendit n'accepte pas cela, une note vous demande de faire expirer la facture dans le tableau de bord Xendit.

Si une facture est payée pour une commande déjà payée, annulée ou remboursée, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement dans le tableau de bord Xendit ou de rétablir la commande manuellement.

Remboursements

Les remboursements ne sont pas envoyés à Xendit depuis WooCommerce. Remboursez le paiement dans le tableau de bord Xendit (la note de commande et l'identifiant de transaction contiennent l'identifiant de facture), puis enregistrez le remboursement dans WooCommerce manuellement.

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 > Xendit. 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-le dans votre compte vibefox.net.

Sans clé active, Xendit n'est pas affiché 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. 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 Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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é à nouveau automatiquement en arrière-plan.

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 a une clé secrète au 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 de la boutique est IDR, PHP, VND, THB, MYR, USD ou SGD. La bannière des réglages affiche un avertissement lorsque la clé est absente ou incorrecte.

Le paiement est passé, mais la commande reste En attente de paiement : 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 les réglages 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 confirmée lorsque le client revient sur la page « Commande reçue ».

Réponse du webhook « Webhook verification token is not configured » : aucun des deux jetons de vérification n'est défini. Collez le jeton dans les réglages.

Réponse du webhook « Unauthorized » : le jeton envoyé par Xendit ne correspond à aucun jeton des réglages. Recopiez le jeton du bon mode.

Réponse du webhook « 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 une commande en production, et inversement. Configurez le webhook et le jeton dans le mode dans lequel la commande a été payée.

Réponse du webhook « 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.

Réponse du webhook « 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, ou la commande était en cours de mise à jour par une autre requête au même moment. Xendit renouvelle le webhook. Vérifiez que les deux clés secrètes sont définies si vous avez des commandes des deux modes.

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). Activez Debug Log si besoin et consultez WooCommerce > Status > Logs, source wcp_xendit_payment_gateway. Un message concernant les informations de facturation signifie que Xendit n'a pas accepté les données de la requête, par exemple l'e-mail.

Le client voit « A payment for this order was already received by Xendit and is being reviewed » : une facture antérieure de cette commande a été payée, mais elle ne correspondait pas à la commande, qui est donc en attente. Vérifiez le paiement dans le tableau de bord Xendit.

La commande est On hold après le paiement : lisez la note de commande. Le montant ou la devise payés différaient de la commande. Traitez la commande ou remboursez le paiement dans le tableau de bord Xendit.

Le bloc de licence affiche une erreur : suivez le message du 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

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les autres options de l'extension, les données temporaires et ses journaux (fichiers journaux, y compris les fichiers archivés, entrées de journal en base de données et dossier de journaux de la version 1.0) 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, identifiants de facture et identifiants de transaction.

Xendit est une marque commerciale de son propriétaire respectif. Cette extension n'est ni affiliée à Xendit ni approuvée par Xendit.