Paiement en ligne : plugin WooCommerce

Voir en Markdown

Acceptez les paiements en ligne Yavin dans une boutique WordPress sans écrire de code. Le plugin Yavin WooCommerce ajoute Yavin comme moyen de paiement lors du passage en caisse, redirige le client vers la page de paiement hébergée par Yavin, puis met à jour la commande WooCommerce une fois que l'API Yavin a confirmé le paiement.

En bref

Plateforme	WordPress avec WooCommerce, tunnel de commande classique
Prérequis	WooCommerce installé et activé, PHP 7.4 ou supérieur
Expérience de paiement	Redirection vers la page de paiement hébergée par Yavin (lien de paiement)
Confirmation de commande	Webhook envoyé par Yavin à votre boutique sur `/wp-json/yavin/v1/webhook/`, puis vérifié auprès de l'API Yavin
Remboursements	Depuis la commande WooCommerce, facultatif (désactivé par défaut)
API sous-jacente	Paiement en ligne : E-commerce API, route `POST /api/v5/ecommerce/generate_link/`
Version actuelle	`1.3.0`
Code source	gitlab.com/yavin-public/woocommerce-yavin-plugin

Avant de commencer

Un compte Yavin avec le paiement en ligne activé. Contactez partnerships@yavin.com pour en obtenir un, ainsi qu'un compte sandbox
Votre clé d'API pour chaque environnement, disponible sur my.yavin.com (sandbox : my.sandbox.yavin.com) dans l'onglet API
Un accès administrateur à l'interface d'administration de WordPress
Une boutique accessible depuis internet en HTTPS. Yavin doit pouvoir envoyer une requête POST non authentifiée à https://your-store.example/wp-json/yavin/v1/webhook/, et votre serveur doit pouvoir appeler api.yavin.com
Des permaliens WordPress définis sur une valeur autre que Plain (Réglages → Permaliens), sinon /wp-json/ ne répond pas

Tunnel de commande classique uniquement. Le plugin ne prend pas en charge le bloc Checkout de WooCommerce : Yavin n'y apparaît pas comme moyen de paiement. Votre page de paiement doit utiliser le shortcode [woocommerce_checkout]. WooCommerce indique également que le plugin est incompatible avec le High-Performance Order Storage (HPOS), car le plugin ne déclare pas encore sa compatibilité.

Fonctionnement

La commande est créée dans WooCommerce avec le statut En attente de paiement avant que le client ne quitte votre boutique. Les webhooks Yavin ne sont pas signés : le plugin ne se fie donc jamais à leur contenu. Il lit uniquement cart_id, vérifie qu'il correspond à la commande, puis interroge l'API Yavin pour obtenir le statut du paiement, le montant et la transaction. La redirection qui ramène le client sur la boutique ne modifie jamais le statut de la commande.

Installation

Téléchargez yavin-woocommerce-gateway.zip, la dernière version. Toutes les versions et leurs modifications sont listées sur la page des versions
Dans WordPress, allez dans Extensions → Ajouter → Téléverser une extension, puis téléversez le fichier zip
Activez Yavin WooCommerce Gateway dans la liste des extensions
Allez dans WooCommerce → Réglages → Paiements et ouvrez Yavin

Si WooCommerce n'est pas activé, le plugin affiche un message d'erreur dans l'interface d'administration et ne fait rien d'autre.

Pour mettre à jour, téléversez le nouveau fichier zip de la même manière et choisissez Replace current with uploaded. Vos réglages sont conservés.

Mise à jour depuis la version 1.1 ? Les versions antérieures écrivaient des fichiers de logs dans wp-content/uploads/yavinpayment-log/. La mise à jour ne les supprime pas : supprimez ce dossier de votre serveur.

Configuration

Paramètre	Valeur à saisir
Enable/Disable	Cochez pour proposer Yavin lors du paiement
Title	Nom du moyen de paiement affiché au client. Valeur par défaut : `Yavin Payment`
Description	Texte affiché sous le moyen de paiement lors du paiement. Valeur par défaut : `Pay using Yavin`
Logos de paiement Yavin	Facultatif. URL des images des logos de cartes à afficher (CB, Visa, Mastercard), une par ligne
Environnement de l'API	`Sandbox` (par défaut) ou `Live`. Sélectionne la clé et l'URL ci-dessous qui sont utilisées
Clé API Sandbox / Clé API Live	Votre clé API Yavin pour chaque environnement. Les deux clés ne sont jamais interchangeables
URL de l'API Sandbox / URL de l'API Live	`https://api.sandbox.yavin.com` et `https://api.yavin.com`, sans slash final
Journal de débogage	Désactivé par défaut. Ajoute des entrées détaillées aux journaux WooCommerce
Remboursements	Désactivé par défaut. Autorise les remboursements depuis la commande WooCommerce, voir Remboursements ci-dessous
Rôles autorisés à rembourser	Par défaut : Administrateur

Les champs d'URL de l'API n'ont pas de valeur par défaut. Si l'un d'eux est vide, tous les paiements de cet environnement échouent avec le message « Payment failed. Please try again. » lors du paiement. Le plugin affiche un avertissement si vous saisissez une autre URL que les deux ci-dessus.

Seuls les administrateurs voient les paramètres d'environnement, de clé API, d'URL de l'API, de débogage et de remboursement. Un gestionnaire de boutique peut uniquement modifier le titre, la description et les logos.

Ce que le plugin envoie

Pour chaque tentative de paiement, le plugin crée un lien de paiement avec :

amount : le total de la commande, en centimes, et currency : la devise de la boutique
items : une ligne par article de la commande, avec son nom, sa quantité et son total en centimes
reference et order_number : le numéro de commande WooCommerce, afin que vous puissiez retrouver la commande depuis le back-office Yavin
customer : prénom, nom, e-mail, téléphone, adresse, ville et code postal de facturation
cart_id : 16 caractères hexadécimaux aléatoires suivis de l'ID de commande WooCommerce, par exemple 9f86d081884c7d65-1234. Chaque nouvelle tentative sur la même commande reçoit un nouveau cart_id
webhook_url : l'endpoint /wp-json/yavin/v1/webhook/ de votre boutique
return_url_success : la page de confirmation de commande, et return_url_cancelled : la page de paiement

Cycle de vie de la commande

Événement	Effet sur la commande WooCommerce
Paiement confirmé par l'API Yavin, montant égal au total de la commande	Si la commande est En attente de paiement ou Échouée : marquée comme payée, stock décrémenté et note ajoutée avec l'ID de transaction Yavin
Paiement refusé	Si la commande est En attente de paiement : marquée Échouée
Paiement toujours en attente	Aucun changement. Yavin renvoie le webhook plus tard
Montant différent du total de la commande, ou paiement sur une commande annulée, en attente, remboursée ou déjà payée	Aucun changement. Une note d'avertissement est ajoutée à la commande et l'administrateur de la boutique reçoit un e-mail
Même paiement notifié deux fois	Une note est ajoutée, rien d'autre ne change
Le client revient de la page de paiement	Redirigé vers la page de confirmation de commande ou vers la page de paiement. Le statut de la commande provient uniquement du webhook

Une fois payée, la commande suit le flux WooCommerce standard : En cours pour les produits physiques, Terminée pour les produits virtuels et téléchargeables.

Remboursements

Depuis la version 1.3.0, vous pouvez rembourser un paiement Yavin depuis la commande WooCommerce avec le bouton standard Rembourser. Activez d'abord Remboursements dans les paramètres, puis choisissez les rôles autorisés à effectuer des remboursements.

Un seul remboursement par paiement. Un second remboursement n'est possible que si le premier a été rejeté
Les remboursements partiels sont possibles, après une seconde confirmation
Uniquement pour les commandes payées avec la version 1.2.0 ou ultérieure. Remboursez les commandes plus anciennes depuis my.yavin.com

Les remboursements sont traités de manière asynchrone. La note de commande indique si le remboursement est en attente ou en attente d'approbation dans my.yavin.com. WooCommerce envoie son e-mail « commande remboursée » dès que vous demandez le remboursement. Si Yavin rejette le remboursement, la commande passe en En attente et l'administrateur est notifié. Le remboursement WooCommerce n'est pas annulé : traitez-le manuellement. Une vérification quotidienne signale les remboursements encore en attente après 15 jours.

Tester en sandbox

Définissez API Environment sur Sandbox, avec votre clé sandbox et https://api.sandbox.yavin.com
Passez une commande sur votre boutique et choisissez Yavin
Sur la page de paiement sandbox, cliquez sur Pay : aucune carte n'est nécessaire, le paiement est validé immédiatement
Vérifiez que la commande est payée et que ses notes contiennent l'ID de transaction Yavin

Pour la mise en production, passez API Environment sur Live avec votre clé de production et https://api.yavin.com.

Dépannage

La commande reste en attente de paiement après un paiement réussi : le webhook n'a pas atteint votre boutique, ou votre boutique n'a pas pu joindre l'API Yavin. Vérifiez que :
- https://your-store.example/wp-json/yavin/v1/webhook/ accepte les requêtes POST non authentifiées provenant d'Internet. Les plugins de sécurité, les pare-feu, la protection anti-bots, un site de préproduction protégé par mot de passe ou une API REST désactivée la bloquent
- Les permaliens ne sont pas définis sur Simple
- Votre serveur peut appeler api.yavin.com
Yavin n'apparaît pas à la caisse : votre page de paiement utilise le bloc Checkout. Remplacez-le par le shortcode [woocommerce_checkout]
« Payment failed. Please try again. » lors du paiement : le lien de paiement n'a pas pu être créé. Vérifiez la clé API et l'URL de l'API de l'environnement sélectionné
Cache : excluez /wp-json/yavin/* et les URL de retour contenant cartId du cache de vos pages
Logs : allez dans WooCommerce → Statut → Journaux et choisissez la source yavin. Les erreurs sont toujours journalisées. Activez Debug log pour plus de détails. Les logs contiennent les ID de commande, les ID de panier, les statuts et les ID de transaction, jamais les données des clients ni les clés API

Pour toute autre question, contactez technical_support@yavin.com en indiquant votre numéro de commande et les entrées de log correspondantes.